为 Application Insights JavaScript SDK 启用框架扩展

除了核心 SDK 之外,还有适用于特定框架的插件,例如 React 插件React Native 插件Angular 插件

这些插件提供额外的功能并与特定框架集成。

先决条件

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

此插件能够实现什么?

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

  • 跟踪异常

  • 收集设备信息

    默认情况下,此插件会自动收集:

    • 唯一设备 ID(也称为安装 ID。)
    • 设备型号名称(如 iPhone XS、Samsung Galaxy Fold、Huawei P30 Pro 等)
    • 设备类型(例如手持设备、平板电脑等。)
  • 禁用自动设备信息收集

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

  • 替代设备信息

添加插件

若要添加插件,请执行本部分中的步骤。

安装包

  • 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
    
    

将扩展添加到代码

备注

对检测密钥引入的支持将于 2025 年 3 月 31 日结束。 检测密钥引入功能将会继续工作,但我们将不再为该功能提供更新或支持。 转换为连接字符串,以利用新功能

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

(可选)添加 Click Analytics 插件

如果要添加 Click Analytics 插件,请执行以下操作:

  1. 取消对 Click Analytics 的行的注释。

  2. 执行下列操作之一,具体取决于要添加的插件:

    • 对于 React,请删除 extensions: [reactPlugin],
    • 对于 React Native,请删除 extensions: [RNPlugin]
    • 对于 Angular,请删除 extensions: [angularPlugin],
  3. 请参阅使用 Click Analytics 插件以继续执行安装过程。

Configuration

本部分包含适用于 Application Insights JavaScript SDK 的框架扩展的配置设置。

跟踪路由器历史记录

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

跟踪异常

默认情况下启用对未捕获异常的跟踪。 如果要禁用对未捕获异常的跟踪,请将 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();

收集设备信息

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

配置(其他)

禁用自动设备信息收集

如果不想收集设备信息,可以将 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 如何生成设备信息(例如浏览器、操作系统、语言和型号)?

浏览器在请求的 HTTP 标头中传递用户代理字符串。 Application Insights 引入服务使用用户代理分析程序生成你在数据表和体验中看到的字段。 因此,Application Insights 用户无法更改这些字段。

如果用户或企业禁止在浏览器设置中发送用户代理,则此数据偶尔可能会缺失或不准确。 用户代理分析程序正则表达式可能未包含所有设备信息。 或者 Application Insights 可能未采用最新更新。

后续步骤