啟用 Application Insights JavaScript SDK 的架構延伸模組

發行項
03/25/2024

除了核心 SDK 之外，還有適用於特定架構的外掛程式，例如 React 外掛程式、React Native 外掛程式和 Angular 外掛程式。

這些外掛程式提供額外的功能以及與特定架構的整合。

必要條件

安裝 JavaScript SDK。

請確定您想要安裝的 React 外掛程式版本與您的 Application Insights 版本相容。如需詳細資訊，請參閱 React 外掛程式的相容性矩陣。

這個外掛程式有什麼作用？

適用於 Application Insights JavaScript SDK 的 React 外掛程式能夠：

追蹤路由器歷程記錄
追蹤例外狀況
追蹤元件使用量
搭配 React 內容使用 Application Insights

新增外掛程式

若要新增外掛程式，請遵循本節中的步驟。

Install the package


npm install @microsoft/applicationinsights-react-js

React Native 外掛程式

React Native 外掛程式預設需要 react-native-device-info 套件。您必須安裝並連結至此套件。讓 react-native-device-info 套件保持最新狀態，以便使用您的應用程式收集最新的裝置名稱。

自 v3 起，已將存取 DeviceInfo 的支援抽象化為介面 IDeviceInfoModule ，讓您能夠使用/設定自己的裝置資訊模組。這個介面會使用相同的函式名稱和結果 react-native-device-info。
```
npm install --save @microsoft/applicationinsights-react-native @microsoft/applicationinsights-web
npm install --save react-native-device-info
react-native link react-native-device-info
```
React Native 手動裝置外掛程式

如果您使用 React Native Expo，請新增 React Native 手動裝置外掛程式，而不是 React Native 外掛程式。 React Native 外掛程式會使用 React Native Expo 不支援的 react-native-device-info package 套件。
```
npm install --save @microsoft/applicationinsights-react-native @microsoft/applicationinsights-web
```

npm install @microsoft/applicationinsights-angularplugin-js

將延伸模組新增至您的程式碼

注意

針對檢測金鑰擷取的支援將在 2025 年 3 月 31 日結束。檢測金鑰擷取將會繼續運作，但我們不再提供該功能的更新或支援。轉換至連接字串以利用新功能。

初始化與 Application Insights 的連線：

import React from 'react';
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
import { ReactPlugin } from '@microsoft/applicationinsights-react-js';
import { createBrowserHistory } from "history";
const browserHistory = createBrowserHistory({ basename: '' });
var reactPlugin = new ReactPlugin();
// *** Add the Click Analytics plug-in. ***
/* var clickPluginInstance = new ClickAnalyticsPlugin();
   var clickPluginConfig = {
     autoCapture: true
}; */
var appInsights = new ApplicationInsights({
    config: {
        connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
        // *** If you're adding the Click Analytics plug-in, delete the next line. ***
        extensions: [reactPlugin],
     // *** Add the Click Analytics plug-in. ***
     // extensions: [reactPlugin, clickPluginInstance],
        extensionConfig: {
          [reactPlugin.identifier]: { history: browserHistory }
       // *** Add the Click Analytics plug-in. ***
       // [clickPluginInstance.identifier]: clickPluginConfig
        }
    }
});
appInsights.loadAppInsights();

React Native 外掛程式

若要使用此外掛程式，您需要建構外掛程式，並將其作為 extension 新增至現有的 Application Insights 執行個體。

import { ApplicationInsights } from '@microsoft/applicationinsights-web';
import { ReactNativePlugin } from '@microsoft/applicationinsights-react-native';
// *** Add the Click Analytics plug-in. ***
// import { ClickAnalyticsPlugin } from '@microsoft/applicationinsights-clickanalytics-js';
var RNPlugin = new ReactNativePlugin();
// *** Add the Click Analytics plug-in. ***
/* var clickPluginInstance = new ClickAnalyticsPlugin();
var clickPluginConfig = {
autoCapture: true
}; */
var appInsights = new ApplicationInsights({
    config: {
        connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
        // *** If you're adding the Click Analytics plug-in, delete the next line. ***
        extensions: [RNPlugin]
     // *** Add the Click Analytics plug-in. ***
     /* extensions: [RNPlugin, clickPluginInstance],
             extensionConfig: {
                 [clickPluginInstance.identifier]: clickPluginConfig
          } */
    }
});
appInsights.loadAppInsights();

React Native 手動裝置外掛程式

若要使用此外掛程式，您必須停用自動裝置資訊收集，或在將延伸模組新增至程式碼之後，使用您自己的裝置資訊集合類別。

建構外掛程式，並將其作為 extension 新增至現有的 Application Insights 執行個體。

import { ApplicationInsights } from '@microsoft/applicationinsights-web';
import { ReactNativePlugin } from '@microsoft/applicationinsights-react-native';

var RNMPlugin = new ReactNativePlugin();
var appInsights = new ApplicationInsights({
    config: {
        instrumentationKey: 'YOUR_INSTRUMENTATION_KEY_GOES_HERE',
        extensions: [RNMPlugin]
    }
});
appInsights.loadAppInsights();

執行下列其中一項動作：

停用自動裝置資訊收集。

import { ApplicationInsights } from '@microsoft/applicationinsights-web';

var RNMPlugin = new ReactNativeManualDevicePlugin();
var appInsights = new ApplicationInsights({
    config: {
        instrumentationKey: 'YOUR_INSTRUMENTATION_KEY_GOES_HERE',
        disableDeviceCollection: true,
        extensions: [RNMPlugin]
    }
});
appInsights.loadAppInsights();

使用您自己的裝置資訊集合類別。

import { ApplicationInsights } from '@microsoft/applicationinsights-web';

// Simple inline constant implementation
const myDeviceInfoModule = {
    getModel: () => "deviceModel",
    getDeviceType: () => "deviceType",
    // v5 returns a string while latest returns a promise
    getUniqueId: () => "deviceId",         // This "may" also return a Promise<string>
};

var RNMPlugin = new ReactNativeManualDevicePlugin();
RNMPlugin.setDeviceInfoModule(myDeviceInfoModule);

var appInsights = new ApplicationInsights({
    config: {
        instrumentationKey: 'YOUR_INSTRUMENTATION_KEY_GOES_HERE',
        extensions: [RNMPlugin]
    }
});

appInsights.loadAppInsights();

在應用程式中的項目元件中，設定 Application Insights 的執行個體：

重要

使用 ErrorService 時， @microsoft/applicationinsights-analytics-js 擴充功能會有隱含相依性。您「必須」包含 '@microsoft/applicationinsights-web' 或包含 @microsoft/applicationinsights-analytics-js 延伸模組。否則，不會傳送錯誤服務攔截到的未處理例外狀況。

import { Component } from '@angular/core';
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
import { AngularPlugin } from '@microsoft/applicationinsights-angularplugin-js';
// *** Add the Click Analytics plug-in. ***
// import { ClickAnalyticsPlugin } from '@microsoft/applicationinsights-clickanalytics-js';
import { Router } from '@angular/router';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
    constructor(
        private router: Router
    ){
        var angularPlugin = new AngularPlugin();
     // *** Add the Click Analytics plug-in. ***
     /* var clickPluginInstance = new ClickAnalyticsPlugin();
        var clickPluginConfig = {
          autoCapture: true
        }; */
        const appInsights = new ApplicationInsights({
            config: {
                connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
                // *** If you're adding the Click Analytics plug-in, delete the next line. ***  
                extensions: [angularPlugin],
             // *** Add the Click Analytics plug-in. ***
             // extensions: [angularPlugin, clickPluginInstance],
                extensionConfig: {
                    [angularPlugin.identifier]: { router: this.router }
                 // *** Add the Click Analytics plug-in. ***
                 // [clickPluginInstance.identifier]: clickPluginConfig
                }
            } 
         });
        appInsights.loadAppInsights();
    }
}

(選擇性) 新增 Click Analytics 外掛程式

如果您想要新增 Click Analytics 外掛程式：

取消註解 Click Analytics 的行。
視您要新增的外掛程式而定，執行下列其中一項：
- 針對 React，刪除 extensions: [reactPlugin],。
- 針對 React Native，刪除 extensions: [RNPlugin]。
- 針對 Angular，刪除 extensions: [angularPlugin],。
請參閱使用 Click Analytics 外掛流程繼續設定流程。

組態

本節涵蓋 Application Insights JavaScript SDK 架構延伸模組的組態設定。

追蹤路由器歷程記錄

名稱	類型	是必要的嗎?	預設	描述
歷程	object	選擇性	null	追蹤路由器歷程記錄。如需詳細資訊，請參閱 React 路由器套件文件。若要追蹤路由器歷程記錄，大部分的使用者都可以在 `enableAutoRouteTracking`JavaScript SDK 設定中使用欄位。此欄位會收集與 `history` 物件相同的頁面檢視資料。您使用未更新瀏覽器 URL 的路由器實作時，請使用 `history` 物件，這是設定所接聽的內容。您不應該同時啟用 `enableAutoRouteTracking` 欄位和 `history` 物件，因為您會取得多個頁面檢視事件。

下列程式碼範例示範如何啟用 enableAutoRouteTracking 欄位。

var reactPlugin = new ReactPlugin();
var appInsights = new ApplicationInsights({
    config: {
        connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
        enableAutoRouteTracking: true,
        extensions: [reactPlugin]
    }
});
appInsights.loadAppInsights();

名稱	類型	是必要的嗎?	預設	描述
路由器	object	選擇性	null	用於啟用 Application Insights PageView 追蹤的 Angular 路由器。

下列程式碼範例示範如何啟用路由器歷程記錄的追蹤。

import { Component } from '@angular/core';
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
import { AngularPlugin } from '@microsoft/applicationinsights-angularplugin-js';
import { Router } from '@angular/router';



@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
    constructor(
        private router: Router
    ){
        var angularPlugin = new AngularPlugin();
        const appInsights = new ApplicationInsights({ config: {
        connectionString: 'YOUR_CONNECTION_STRING',
        extensions: [angularPlugin],
        extensionConfig: {
            [angularPlugin.identifier]: { router: this.router }
        }
        } });
        appInsights.loadAppInsights();
    }
}

追蹤例外狀況

React 錯誤界限提供在 React 應用程式內發生例外狀況時，以正常方式處理未攔截到的例外狀況所用的方式。發生這類例外狀況時，可能需要記錄例外狀況。 Application Insights React 外掛程式提供錯誤界限元件，在例外狀況發生時會自動記錄例外狀況。

import React from "react";
import { reactPlugin } from "./AppInsights";
import { AppInsightsErrorBoundary } from "@microsoft/applicationinsights-react-js";

const App = () => {
    return (
        <AppInsightsErrorBoundary onError={() => <h1>I believe something went wrong</h1>} appInsights={reactPlugin}>
            /* app here */
        </AppInsightsErrorBoundary>
    );
};

有兩個屬性需要傳遞給 AppInsightsErrorBoundary。這兩個屬性是為應用程式所建立的 ReactPlugin 執行個體，以及發生例外狀況時要轉譯的元件。在未處理的例外狀況發生時，系統會透過提供給錯誤界限的資訊來呼叫 trackException，而且 onError 元件隨即顯示。

預設會啟用對於未攔截到的例外狀況進行的追蹤。如果您要停用對於未攔截到的例外狀況進行的追蹤，請將 disableExceptionCollection 設定為 true。

import { ApplicationInsights } from '@microsoft/applicationinsights-web';

var RNPlugin = new ReactNativePlugin();
var appInsights = new ApplicationInsights({
    config: {
        connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
        disableExceptionCollection: true,
        extensions: [RNPlugin]
    }
});
appInsights.loadAppInsights();

若要追蹤未攔截的例外狀況，請在 app.module.ts 中設定 ApplicationinsightsAngularpluginErrorService：

重要

import { ApplicationinsightsAngularpluginErrorService } from '@microsoft/applicationinsights-angularplugin-js';

@NgModule({
  ...
  providers: [
    {
      provide: ErrorHandler,
      useClass: ApplicationinsightsAngularpluginErrorService
    }
  ]
  ...
})
export class AppModule { }

鏈結更多自訂例外狀況處理常式

您想要讓應用程式正常處理先前未處理的例外狀況，但您仍要將此例外狀況報告為應用程式失敗時，請鏈結更多自訂例外狀況處理常式。

若要鏈結更多自訂例外狀況處理常式：

建立實作 IErrorService 的自訂例外狀況處理常式。

import { IErrorService } from '@microsoft/applicationinsights-angularplugin-js';

export class CustomErrorHandler implements IErrorService {
    handleError(error: any) {
        ...
    }
}

透過 extensionConfig 傳遞 errorServices 陣列。

extensionConfig: {
        [angularPlugin.identifier]: {
          router: this.router,
          errorServices: [new CustomErrorHandler()]
        }
      }

收集裝置資訊

Application Insights Web 套件已經收集包含瀏覽器、作業系統、版本和語言的裝置資訊。

設定 (其他)

追蹤元件使用量

React 外掛程式特有的功能是您可以檢測特定元件並個別追蹤這些元件。

如要藉由使用量追蹤檢測 React 元件，請套用 withAITracking 高階元件函式。若要啟用元件的 Application Insights，請包裝 withAITracking 元件：

import React from 'react';
import { withAITracking } from '@microsoft/applicationinsights-react-js';
import { reactPlugin, appInsights } from './AppInsights';

// To instrument various React components usage tracking, apply the `withAITracking` higher-order
// component function.

class MyComponent extends React.Component {
    ...
}

// withAITracking takes 4 parameters (reactPlugin, Component, ComponentName, className). 
// The first two are required and the other two are optional.

export default withAITracking(reactPlugin, MyComponent);

其會測量從 ComponentDidMount 事件到 ComponentWillUnmount 事件的時間。為了讓結果更加精確，其會使用 React Component Engaged Time = ComponentWillUnmount timestamp - ComponentDidMount timestamp - idle time 來減去使用者閒置的時間。

探索資料

使用 Azure 監視器計量瀏覽器來繪製自訂計量名稱 React Component Engaged Time (seconds) 的圖表，並且依 Component Name分割此自訂計量。

您也可以執行自訂查詢來分割 Application Insights 資料，以根據您的需求產生報表和視覺效果。以下是自訂查詢的範例。繼續並直接貼到查詢編輯器中，以進行測試。

customMetrics
| where name contains "React Component Engaged Time (seconds)"
| summarize avg(value), count() by tostring(customDimensions["Component Name"])

新的自訂計量最多可能需要 10 分鐘時間才會出現在 Azure 入口網站中。

搭配 React 內容使用 Application Insights

我們提供一般勾點，可讓您自訂個別元件的變更追蹤。或者，您可以使用 useTrackMetric 或 useTrackEvent，這是我們為了追蹤元件變更所提供的預先定義接點。

Application Insights 的 React 勾點其設計目的為使用 React Context 作為其所包含的層面。若要使用 Context，請初始化 Application Insights，然後匯入內容物件：

import React from "react";
import { AppInsightsContext } from "@microsoft/applicationinsights-react-js";
import { reactPlugin } from "./AppInsights";

const App = () => {
    return (
        <AppInsightsContext.Provider value={reactPlugin}>
            /* your application here */
        </AppInsightsContext.Provider>
    );
};

此 Context 提供者會讓 Application Insights 成為其所有子元件內的可用 useContext 勾點：

import React from "react";
import { useAppInsightsContext } from "@microsoft/applicationinsights-react-js";

const MyComponent = () => {
    const appInsights = useAppInsightsContext();
    const metricData = {
        average: engagementTime,
        name: "React Component Engaged Time (seconds)",
        sampleCount: 1
      };
    const additionalProperties = { "Component Name": 'MyComponent' };
    appInsights.trackMetric(metricData, additionalProperties);
    
    return (
        <h1>My Component</h1>
    );
}
export default MyComponent;

useTrackMetric

useTrackMetric 勾點會複寫 withAITracking 高階元件的功能，而不需將其他元件新增至元件結構。勾點會採用兩個引數：

Application Insights 執行個體，您可從 useAppInsightsContext 勾點取得。
進行追蹤的元件所用的識別碼，例如其名稱。

import React from "react";
import { useAppInsightsContext, useTrackMetric } from "@microsoft/applicationinsights-react-js";

const MyComponent = () => {
    const appInsights = useAppInsightsContext();
    const trackComponent = useTrackMetric(appInsights, "MyComponent");
    
    return (
        <h1 onHover={trackComponent} onClick={trackComponent}>My Component</h1>
    );
}
export default MyComponent;

其運作方式如同高階元件，但會回應勾點生命週期事件，而非元件的生命週期。如果需要對於特定互動執行，則必須明確將勾點提供給使用者事件。

useTrackEvent

useTrackEvent 勾點可用於追蹤應用程式可能需要追蹤的任何自訂事件，例如按一下按鈕或呼叫其他 API。採用四個引數：

Application Insights 執行個體，您可從 useAppInsightsContext 勾點取得。
事件的名稱。
事件資料物件，封裝了必須追蹤的變更。
skipFirstRun (選擇性) 旗標，以在初始化時跳過對 trackEvent 的呼叫。預設值會設定為 true，以更接近非勾點版本的運作方式來模擬。使用 useEffect 勾點，此效果會在每次值更新時觸發，包括值的初始設定。因此，追蹤太早開始，這會導致追蹤潛在不想要的事件。

import React, { useState, useEffect } from "react";
import { useAppInsightsContext, useTrackEvent } from "@microsoft/applicationinsights-react-js";

const MyComponent = () => {
    const appInsights = useAppInsightsContext();
    const [cart, setCart] = useState([]);
    const trackCheckout = useTrackEvent(appInsights, "Checkout", cart);
    const trackCartUpdate = useTrackEvent(appInsights, "Cart Updated", cart);
    useEffect(() => {
        trackCartUpdate({ cartCount: cart.length });
    }, [cart]);
    
    const performCheckout = () => {
        trackCheckout();
        // submit data
    };
    
    return (
        <div>
            <ul>
                <li>Product 1 <button onClick={() => setCart([...cart, "Product 1"])}>Add to Cart</button></li>
                <li>Product 2 <button onClick={() => setCart([...cart, "Product 2"])}>Add to Cart</button></li>
                <li>Product 3 <button onClick={() => setCart([...cart, "Product 3"])}>Add to Cart</button></li>
                <li>Product 4 <button onClick={() => setCart([...cart, "Product 4"])}>Add to Cart</button></li>
            </ul>
            <button onClick={performCheckout}>Checkout</button>
        </div>
    );
}

export default MyComponent;

使用勾點時，可向其提供資料承載，藉以在事件儲存至 Application Insights 中時，新增更多資料至事件。

停用自動裝置資訊收集

如果您不想收集裝置資訊，您可以將 disableDeviceCollection 設定為 true。

import { ApplicationInsights } from '@microsoft/applicationinsights-web';

var RNPlugin = new ReactNativePlugin();
var appInsights = new ApplicationInsights({
    config: {
        connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
        disableDeviceCollection: true,
        extensions: [RNPlugin]
    }
});
appInsights.loadAppInsights();

使用您自己的裝置資訊集合類別

如果您想要覆寫您自己的裝置資訊，您可以使用 myDeviceInfoModule 收集您自己的裝置資訊。

import { ApplicationInsights } from '@microsoft/applicationinsights-web';

// Simple inline constant implementation
const myDeviceInfoModule = {
    getModel: () => "deviceModel",
    getDeviceType: () => "deviceType",
    // v5 returns a string while latest returns a promise
    getUniqueId: () => "deviceId",         // This "may" also return a Promise<string>
};

var RNPlugin = new ReactNativePlugin();
RNPlugin.setDeviceInfoModule(myDeviceInfoModule);

var appInsights = new ApplicationInsights({
    config: {
        connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
        extensions: [RNPlugin]
    }
});

appInsights.loadAppInsights();

覆寫裝置資訊

IDeviceInfoModule 介面用來抽象化外掛程式如何存取裝置資訊。此介面是 react-native-device-info 介面的精簡版，而且大部分都提供進行測試。

export interface IDeviceInfoModule {
    /**
     * Returns the Device Model
     */
    getModel: () => string;

    /**
     * Returns the device type
     */
    getDeviceType: () => string;

    /**
     * Returns the unique Id for the device. To support both the current version and previous
     * versions react-native-device-info, this may return either a `string` or `Promise<string>`.
     * When a promise is returned, the plugin will "wait" for the promise to `resolve` or `reject`
     * before processing any events. This WILL cause telemetry to be BLOCKED until either of these
     * states, so when returning a Promise, it MUST `resolve` or `reject`. Tt can't just never resolve.
     * There is a default timeout configured via `uniqueIdPromiseTimeout` to automatically unblock
     * event processing when this issue occurs.
     */
    getUniqueId: () => Promise<string> | string;
}

如果事件因為從未解析 / 拒絕透過 getUniqueId 傳回的 Promise 而遭到「封鎖」，您可以在外掛程式上呼叫 setDeviceId()，藉以「解除封鎖」此等候狀態。另外還有透過 uniqueIdPromiseTimeout 設定的自動逾時 (預設值為 5 秒)，這會在內部以任何先前設定的值呼叫 setDeviceId()。

範例應用程式

查看 Application Insights React 示範。

常見問題集

本節提供常見問題的答案。

Application Insights 如何產生裝置資訊，例如瀏覽器、作業系統、語言和模型？

瀏覽器會在要求的 HTTP 標頭中傳遞使用者代理程式字串。 Application Insights 內嵌服務會使用 UA 剖析器來產生您在資料表和經驗中看到的欄位。因此，Application Insights 使用者無法變更這些欄位。

如果使用者或企業停用瀏覽器設定中的傳送使用者代理程式，則偶爾會遺失或不正確的資料。 UA 剖析器 regex 可能不包含全部裝置資訊。或者，Application Insights 可能尚未採用最新的更新。

下一步

確認資料正在流動。