为 Application Insights JavaScript SDK 启用框架扩展

• 确保要安装的 React 插件版本与 Application Insights 版本兼容。 有关详细信息，请参阅 React 插件的兼容性矩阵。

• 必须使用版本 >= 2.0.0 的 @microsoft/applicationinsights-web。 此插件仅在 react-native 应用中工作。 它不适用于使用 Expo 框架的应用或创建基于 Expo 框架的 React Native 应用。

• Angular 插件与 ECMAScript 3 (ES3) 不兼容。
• 当我们添加新的 Angular 版本时，我们的 npm 包将与下层 Angular 版本不兼容。 继续使用旧的 npm 包，直到你准备好升级 Angular 版本。

使用 Application Insights JavaScript SDK 的 React 插件可以：

• 跟踪路由器历史记录
• 跟踪异常
• 跟踪组件使用情况
• 将 Application Insights 与 React Context 配合使用

适用于 Application Insights JavaScript SDK 的 React Native 插件支持：

• 跟踪异常

• 收集设备信息

  默认情况下，此插件会自动收集：

  • 唯一设备 ID（也称为安装 ID。）
  • 设备型号名称（如 iPhone XS、Samsung Galaxy Fold、Huawei P30 Pro 等）
  • 设备类型（例如手持设备、平板电脑等。）

• 禁用自动设备信息收集

• 使用你自己的设备信息收集类

• 替代设备信息

适用于 Application Insights JavaScript SDK 的 Angular 插件支持：

• 跟踪路由器历史记录
• 跟踪异常
• 链接更多自定义异常处理程序

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-device-info package 包，React Native Expo 不支持该包。

  
  npm install --save @microsoft/applicationinsights-react-native @microsoft/applicationinsights-web
  
  

npm install @microsoft/applicationinsights-angularplugin-js

初始化与 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 手动设备插件

  若要使用此插件，必须在将扩展添加到代码后禁用自动设备信息收集或使用你自己的设备信息收集类。

  1. 构造该插件并将其作为 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();
     

  2. 执行下列操作之一：

     • 禁用自动设备信息收集。

       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 实例：

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();
    }
}

以下代码示例展示了如何启用 enableAutoRouteTracking 字段。

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

React Native不会跟踪路由器更改，但会跟踪页面视图。

以下代码示例展示了如何启用路由器历史记录的跟踪。

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 { }

如果希望应用程序正常处理以前的未经处理的异常，但仍希望将此异常报告为应用程序故障，请链接更多自定义异常处理程序。

若要链接更多自定义异常处理程序，请执行以下操作：

1. 创建实现 IErrorService 的自定义异常处理程序。

   import { IErrorService } from '@microsoft/applicationinsights-angularplugin-js';
   
   export class CustomErrorHandler implements IErrorService {
       handleError(error: any) {
           ...
       }
   }
   

2. 通过 extensionConfig 传递 errorServices 数组。

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

设备信息（包括浏览器、OS、版本和语言）已由 Application Insights Web 程序包收集。

• React Native 插件：除了 Application Insights Web 程序包收集的浏览器中的用户代理信息外，React Native 还会收集设备信息。 添加插件时会自动收集设备信息。
• React Native 手动设备插件：根据将扩展添加到代码时配置插件的方式，此插件可以是：
  • 不收集设备信息
  • 使用你自己的设备信息收集类

设备信息（包括浏览器、OS、版本和语言）已由 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 Monitor 指标资源管理器绘制自定义指标名称 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 门户中。

我们提供常规挂钩，使你能够自定义各个组件的变更跟踪。 或者，可以使用 useTrackMetric 或 useTrackEvent，它们是我们提供的预定义联系方式，用于跟踪组件变更。

Application Insights React 挂钩旨在使用 React 上下文作为它的一个包含方面。 若要使用上下文，请初始化 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>
    );
};

此上下文提供程序使 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 挂钩复制 withAITracking 高阶组件的功能，而不会向组件结构中添加其他组件。 Hook 接受两个参数：

• Application Insights 实例，可以从 useAppInsightsContext Hook 获取。
• 用于跟踪的组件的标识符，例如其名称。

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;

该组件像高阶组件一样运行，但它响应挂钩生命周期事件而不是组件生命周期。 如果需要在特定交互上运行，则需要向用户事件显式提供 Hook。

使用 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 Angular 演示。