Application Insights JavaScript SDK のフレームワーク拡張機能を有効にする

[アーティクル]
11/15/2023

コア SDK に加えて、React プラグイン、React Native プラグイン、Angular プラグインなど、特定のフレームワークで使用できるプラグインもあります。

これらのプラグインは、追加の機能と特定のフレームワークとの統合を提供します。

前提条件

JavaScript SDK をインストールします。

インストールする React プラグインのバージョンが Application Insights のバージョンと互換性があることを確認してください。詳細については、「React プラグインの互換性マトリックス」を参照してください。

このプラグインで可能になること

Application Insights JavaScript SDK 用の React プラグインを使用すると、次が有効になります。

ルーター履歴の追跡
例外の追跡
コンポーネントの使用状況の追跡
React Context で Application Insights を使用する

プラグインを追加する

プラグインを追加するには、このセクションの手順に従います。

パッケージをインストールする


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

コードに拡張機能を追加する

Note

インストルメンテーションキーのインジェストのサポートは、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 プラグイン

このプラグインを使用するには、プラグインを構築し、既存の Application Insights インスタンスに extension として追加する必要があります。

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 手動デバイスプラグイン

このプラグインを使用するには、コードに拡張機能を追加した後、自動のデバイス情報収集を無効にするか、独自のデバイス情報収集クラスを使用する必要があります。

プラグインを構築し、既存の Application Insights インスタンスに extension として追加します。

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 拡張機能を含める必要があります。そうしないと、ErrorService でキャッチされた未処理のエラーが送信されません。

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 のフレームワーク拡張機能の構成設定について説明します。

ルーター履歴の追跡

名前	Type	必須	Default	説明
history	object	省略可能	null	ルーターの履歴を追跡します。詳細については、React ルーターパッケージに関するドキュメントを参照してください。ルーター履歴を追跡するために、ほとんどのユーザーは JavaScript SDK 構成の `enableAutoRouteTracking` フィールドを使用できます。このフィールドは、`history` オブジェクトと同じページビューのデータを収集します。 `history` オブジェクトは、構成がリッスンするブラウザーの URLを更新しないルーター実装を使用している場合に使用します。複数のページビューイベントが発生するため、`enableAutoRouteTracking` フィールドと `history` オブジェクトの両方を有効にしないでください。

次のコード例では、enableAutoRouteTracking を有効にする方法を示します。

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

名前	Type	必須	Default	説明
ルーター	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 プラグインには、例外が発生したときに自動的にログに記録する Error Boundary コンポーネントが用意されています。

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 では、2 つの Props を渡す必要があります。これは、アプリケーション用に作成された ReactPlugin インスタンスと、例外が発生したときにレンダリングされるコンポーネントです。未処理の例外が発生すると、Error Boundary に対して指定された情報を使用して 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()]
        }
      }

デバイス情報を収集する

ブラウザー、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"])

新しいカスタムメトリックが Azure portal に表示されるまでに最大で 10 分かかることがあります。

React Context で Application Insights を使用する

個々のコンポーネントの変更追跡をカスタマイズできるように、一般的なフックが用意されています。または、コンポーネントへの変更を追跡するために提供される定義済みの連絡先である useTrackMetric または useTrackEvent を使用することもできます。

Application Insights の React フックは、React Context をその格納アスペクトとして使用するように設計されています。 Context を使用するには、Application Insights を初期化してから、Context オブジェクトをインポートします。

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

useTrackMetric フックでは、コンポーネント構造に別のコンポーネントを追加することなく、withAITracking 高次コンポーネントの機能がレプリケートされます。フックは 2 つの引数を受け取ります。

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 呼び出しなど、アプリケーションで追跡が必要になる可能性があるカスタムイベントの追跡に使用されます。 4 つの引数を受け取ります。

Application Insights インスタンス (useAppInsightsContext フックから取得できます)。
イベントの名前。
追跡する必要がある変更をカプセル化するイベントデータオブジェクト。
初期化時の trackEvent 呼び出しをスキップするための skipFirstRun (省略可能) フラグ。既定値は 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 では、ブラウザー、OS、言語、モデルなどのデバイス情報はどのように生成されますか?

ブラウザーによって、要求の HTTP ヘッダーにユーザーエージェント文字列が渡されます。 Application Insights インジェストサービスでは、UA パーサーを使用して、データテーブルとエクスペリエンスに表示されるフィールドが生成されます。その結果、Application Insights ユーザーはこれらのフィールドを変更できなくなります。

ユーザーまたは企業がブラウザーの設定でユーザーエージェントの送信を無効にした場合、このデータが失われることや不正確になることがあります。 UA パーサーの正規表現に、すべてのデバイス情報が含まれていない場合があります。また、Application Insights に最新の更新プログラムが適用されていない場合があります。

次のステップ

データが流れていることを確認する