Activer une extension de système pour le Kit de développement logiciel (SDK) JavaScript Application Insights

• Assurez-vous que la version du plug-in React à installer est compatible avec votre version d’Application Insights. Pour plus d’informations, consultez Compatibilité Matrix pour le plug-in React.

• Vous devez utiliser une version >= 2.0.0 de @microsoft/applicationinsights-web. Ce plug-in fonctionne seulement dans les applications React Native. Il ne fonctionne pas avec les applications utilisant l’infrastructure Expo ou Create React Native App, qui est basée sur l’infrastructure Expo.

• Le plug-in Angular n’est pas compatible avec ECMAScript 3 (ES3).
• Lorsque nous ajoutons la prise en charge d’une nouvelle version d’Angular, notre package npm devient incompatible avec les versions de bas niveau d’Angular. Continuez à utiliser des packages npm plus anciens jusqu’à ce que vous soyez prêt à mettre à niveau votre version d’Angular.

Le plug-in React pour le Kit de développement logiciel (SDK) JavaScript Application Insights permet :

• Suivre l’historique des routeurs
• Suivre les exceptions
• Suivre l’utilisation des composants
• Utiliser Application Insights avec React Context

Le plug-in React Native pour le kit de développement logiciel (SDK) JavaScript Application Insights permet de :

• Suivre les exceptions

• Collecter des informations sur l’appareil

  Par défaut, ce plug-in collecte automatiquement :

  • ID d’appareil unique (également appelé ID d’installation.)
  • Nom du modèle d’appareil (par exemple, iPhone XS, Samsung Galaxy Fold, Huawei P30 Pro, etc.)
  • Type d’appareil (par exemple, téléphone, tablette, etc.)

• Désactiver la collecte automatique d’informations sur l’appareil

• Utilisez votre propre classe de collecte d’informations sur l’appareil

• Remplacer les informations de l’appareil

Le plug-in Angular pour le kit de développement logiciel (SDK) JavaScript Application Insights permet de :

• Suivre l’historique des routeurs
• Suivre les exceptions
• Chaîner davantage de gestionnaires d’exceptions personnalisés

npm install @microsoft/applicationinsights-react-js

• Plug-in React Native

  Par défaut, le plug-in React Native s’appuie sur le react-native-device-info package. Vous devez installer et créer un lien vers ce package. Maintenez le package react-native-device-info à jour pour collecter les noms des appareils les plus récents à l’aide de votre application.

  Depuis v3, la prise en charge de l’accès à DeviceInfo a été abstraite dans une interface IDeviceInfoModule pour vous permettre d’utiliser/définir votre propre module d’informations sur l’appareil. Cette interface utilise les mêmes noms de fonction et résultat 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
  
  

• Plug-in d’appareil manuel React Native

  Si vous utilisez React Native Expo, ajoutez le plug-in d’appareil manuel React Native au lieu du plug-in React Native. Le plug-in React Native utilise le package react-native-device-info package, que React Native Expo ne prend pas en charge.

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

npm install @microsoft/applicationinsights-angularplugin-js

Initialisez une connexion à 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();

• Plug-in React Native

  Pour utiliser ce plug-in, vous devez construire le plug-in et l’ajouter en tant que extension à votre instance Application Insights existante.

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

• Plug-in d’appareil manuel React Native

  Pour utiliser ce plug-in, vous devez désactiver la collecte automatique d’informations sur l’appareil ou utiliser votre propre classe de collection d’informations sur l’appareil après avoir ajouté l’extension à votre code.

  1. Construisez le plug-in et ajoutez-le en tant que extension à votre instance Application Insights existante.

     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. Effectuez l’une des opérations suivantes :

     • Désactiver la collecte automatique d’informations sur l’appareil.

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

     • Utiliser votre propre classe de collecte d’informations sur l’appareil.

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

Configurez une instance d’Application Insights dans le composant d’entrée de votre application :

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

L’exemple de code suivant montre comment activer le champ enableAutoRouteTracking.

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

React Native ne suit pas les modifications apportées au routeur, mais suit les vues de page.

L’exemple de code suivant montre comment activer le suivi de l’historique du routeur.

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

Les limites d’erreur React permettent de gérer correctement une exception non détectée lorsqu’elle se produit dans une application React. Lorsqu’une telle exception se produit, il est probable que l’exception doive être journalisée. Le plug-in React pour Application Insights fournit un composant de limite d’erreur qui journalise automatiquement l’exception lorsqu’elle se produit.

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

Le AppInsightsErrorBoundary nécessite que deux accessoires lui soient transférés. Il s’agit de l’instance ReactPlugin créée pour l’application et d’un composant à afficher lorsqu’une exception se produit. Lorsqu’une exception non prise en charge se produit, trackException est appelé avec les informations fournies à la limite d’erreur et le composant onError s’affiche.

Le suivi des exceptions non détectées est activé par défaut. Si vous souhaitez désactiver le suivi des exceptions non détectées, définissez disableExceptionCollection sur 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();

Pour suivre les exceptions non interceptées, configurez ApplicationinsightsAngularpluginErrorService dans app.module.ts :

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

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

Chaîner davantage de gestionnaires d’exceptions personnalisés

Chaînez davantage de gestionnaires d’exceptions personnalisés lorsque vous souhaitez que l’application gère correctement ce qui aurait été auparavant une exception non prise en charge, mais vous souhaitez toujours signaler cette exception en tant que défaillance de l’application.

Pour chaîner davantage de gestionnaires d’exceptions personnalisés :

1. Créez des gestionnaires d’exceptions personnalisés qui implémentent IErrorService.

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

2. Passez le tableau errorServices par extensionConfig.

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

Les informations sur l’appareil, notamment le navigateur, le système d’exploitation, la version et la langue, sont déjà collectées par le package web Application Insights.

• Plug-in React Native : outre les informations de l’agent utilisateur du navigateur, qui sont collectées par le package web Application Insights, React Native collecte également des informations sur l’appareil. Les informations sur l’appareil sont collectées automatiquement lorsque vous ajoutez le plug-in.
• Plug-in d’appareil manuel React Native: selon la façon dont vous avez configuré le plug-in à l’ajout de l’extension à votre code, ce plug-in :
  • Ne collecte pas d’informations sur l’appareil
  • Utilise votre propre classe de collecte d’informations sur l’appareil

Les informations sur l’appareil, notamment le navigateur, le système d’exploitation, la version et la langue, sont déjà collectées par le package web Application Insights.

Suivre l’utilisation des composants

Une fonctionnalité propre au plug-in React est la possibilité d’instrumenter des composants spécifiques et de les suivre individuellement.

Pour instrumenter des composants React avec le suivi de l’utilisation, appliquez la fonction de composant d’ordre supérieur withAITracking. Pour activer Application Insights pour un composant, entourer le composant de 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);

Il mesure le temps à partir de l’événement ComponentDidMount par le biais de l’événement ComponentWillUnmount. Pour rendre le résultat plus précis, il soustrait le temps d’inactivité de l’utilisateur à l’aide de React Component Engaged Time = ComponentWillUnmount timestamp - ComponentDidMount timestamp - idle time.

Exploration de vos données

Utilisez l’explorateur de métriques afin de tracer un graphique pour le nom de métrique personnalisée React Component Engaged Time (seconds) et fractionner cette métrique personnalisée par Component Name.

Vous pouvez également exécuter des requêtes personnalisées pour diviser les données d’Application Insights afin de générer des rapports et des visualisations selon vos besoins. Voici un exemple de requête personnalisée. Ensuite, collez-le directement dans l’éditeur de requête pour le tester.

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

Il peut s’écouler jusqu’à 10 minutes avant que de nouvelles mesures personnalisées n’apparaissent dans le portail Azure.

Utiliser Application Insights avec React Context

Nous fournissons des Hooks généraux qui permettent de personnaliser le suivi des modifications pour des composants individuels. Vous pouvez également utiliser useTrackMetric ou useTrackEvent, qui sont des contacts prédéfinis que nous fournissons pour le suivi des modifications apportées aux composants.

Les React Hooks pour Application Insights sont conçus pour utiliser React Context comme un aspect contenant. Pour utiliser Context, initialisez Application Insights, puis importez l’objet 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>
    );
};

Ce fournisseur de Context rend Application Insights disponible en tant que Hook useContext dans tous ses composants enfants :

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

Le Hook useTrackMetric réplique les fonctionnalités du composant d’ordre supérieur withAITracking sans ajouter d’autre composant à la structure du composant. Le Hook nécessite deux arguments :

• L’instance Application Insights qui peut être obtenue à partir du Hook useAppInsightsContext.
• Un identificateur du composant pour le suivi, tel que son nom.

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;

Il fonctionne comme le composant d’ordre supérieur, mais répond aux événements de cycle de vie des Hooks, plutôt qu’au cycle de vie d’un composant. S’il doit s’exécuter sur des interactions particulières, le Hook doit être fourni explicitement aux événements de l’utilisateur.

useTrackEvent

Utilisez le Hook useTrackEvent pour suivre tout événement personnalisé qu’une application peut avoir besoin de suivre, par exemple un clic sur un bouton ou tout autre appel d’API. Il y a quatre arguments :

• Instance Application Insights, qui peut être obtenue à partir du Hook useAppInsightsContext.
• Nom pour l’événement.
• Objet de données d’événement qui encapsule les modifications à suivre.
• Indicateur skipFirstRun (facultatif) pour ignorer l’appel trackEvent de l’appel lors de l’initialisation. La valeur par défaut est définie sur true pour imiter plus étroitement le fonctionnement de la version non-Hook. Avec des Hooks useEffect, l’effet est déclenché sur chaque mise à jour de valeur, y compris la définition initiale de la valeur. Par conséquent, le suivi démarre donc trop tôt, ce qui entraîne le suivi d’événements potentiellement indésirables.

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;

Lorsque le Hook est utilisé, une charge utile de données peut lui être fournie pour ajouter d’autres données à l’événement lorsqu’il est stocké dans Application Insights.

Désactiver la collecte automatique d’informations sur l’appareil

Si vous ne souhaitez pas collecter les informations de l’appareil, vous pouvez définir disableDeviceCollection sur 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();

Utilisez votre propre classe de collecte d’informations sur l’appareil

Si vous souhaitez remplacer les informations sur votre propre appareil, vous pouvez utiliser myDeviceInfoModule pour collecter les informations sur votre appareil.

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

Remplacer les informations de l’appareil

Utilisez l’interface IDeviceInfoModule pour extraire la façon dont le plug-in peut accéder aux informations de l’appareil. Cette interface est une version supprimée de l’interface react-native-device-info et est principalement fournie pour les tests.

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

Si les événements sont « bloqués » parce que le Promise via retourné n’est getUniqueId jamais résolu/rejeté, vous pouvez appeler setDeviceId() sur le plug-in pour « débloquer » cet état d’attente. Il existe également un délai d’expiration automatique configuré via uniqueIdPromiseTimeout (5 secondes par défaut), qui appellera setDeviceId() en interne avec n’importe quelle valeur configurée précédemment.

N/A

Consultez la démonstration de React d’Application Insights.

Actuellement indisponible.

Consultez la démonstration de Angular d’Application Insights.