Abilitare un'estensione del framework per Application Insights JavaScript SDK

• Assicurarsi che la versione del plug-in React che si vuole installare sia compatibile con la versione di Application Insights. Per altre informazioni, vedere Matrice di compatibilità per il plug-in React.

• È necessario usare una versione >= 2.0.0 di @microsoft/applicationinsights-web. Questo plug-in funziona solo nelle app native react. Non funziona con le app che usano il framework Expo o Create React Native App, basato sul framework Expo.

• Il plug-in Angular non è compatibile con ECMAScript 3 (ES3).
• Quando si aggiunge il supporto per una nuova versione di Angular, il pacchetto npm diventa incompatibile con le versioni angular di livello inferiore. Continuare a usare pacchetti npm meno recenti fino a quando non si è pronti per aggiornare la versione di Angular.

Il plug-in React per Application Insights JavaScript SDK abilita:

• Tenere traccia della cronologia dei router
• Traccia delle eccezioni
• Tenere traccia dell'utilizzo dei componenti
• Usare Application Insights con il contesto React

Il plug-in React Native per Application Insights JavaScript SDK abilita:

• Traccia delle eccezioni

• Raccogliere informazioni sul dispositivo

  Per impostazione predefinita, questo plug-in raccoglie automaticamente:

  • ID dispositivo univoco (noto anche come ID di installazione).
  • Device Model Name (ad esempio iPhone XS, Samsung Galaxy Fold, Huawei P30 Pro e così via)
  • Tipo di dispositivo (ad esempio, handset, tablet e così via)

• Disabilitare la raccolta automatica delle informazioni sul dispositivo

• Usare la propria classe di raccolta di informazioni sul dispositivo

• Eseguire l'override delle informazioni sul dispositivo

Il plug-in Angular per Application Insights JavaScript SDK abilita:

• Tenere traccia della cronologia dei router
• Traccia delle eccezioni
• Concatenare più gestori di eccezioni personalizzati

npm install @microsoft/applicationinsights-react-js

• Plug-in React Native

  Per impostazione predefinita, il plug-in React Native si basa sul react-native-device-info pacchetto. È necessario installare e collegare il pacchetto. Mantenere aggiornato il pacchetto react-native-device-info per raccogliere i nomi dei dispositivi più recenti usando l'app.

  A partire dalla versione 3, il supporto per l'accesso a DeviceInfo è stato astratto in un'interfaccia IDeviceInfoModule per consentire di usare/impostare il proprio modulo informazioni sul dispositivo. Questa interfaccia usa gli stessi nomi di funzione e il risultato 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 di dispositivo manuale React Native

  Se si usa React Native Expo, aggiungere il plug-in React Native Manual Device invece del plug-in React Native. Il plug-in React Native usa il pacchetto react-native-device-info package, che React Native Expo non supporta.

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

npm install @microsoft/applicationinsights-angularplugin-js

Inizializzare una connessione ad 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

  Per usare questo plug-in, è necessario costruire il plug-in e aggiungerlo come extension all’istanza Application Insights esistente.

  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 di dispositivo manuale React Native

  Per usare questo plug-in, è necessario disabilitare la raccolta automatica delle informazioni sul dispositivo o usare la propria classe di raccolta di informazioni sul dispositivo dopo aver aggiunto l'estensione al codice.

  1. Creare il plug-in e aggiungerlo come extension all’istanza Application Insights esistente.

     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. Esegui una delle operazioni seguenti:

     • Disabilitare la raccolta automatica delle informazioni sul dispositivo.

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

     • Usare la propria classe di raccolta di informazioni sul dispositivo.

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

Configurare un'istanza di Application Insights nel componente di immissione nell'app:

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

Nell'esempio di codice seguente viene illustrato come abilitare il campo enableAutoRouteTracking.

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

React Native non tiene traccia delle modifiche del router, ma tiene traccia delle visualizzazioni di pagina.

Nell'esempio di codice seguente viene illustrato come abilitare il rilevamento della cronologia del router.

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

I limiti di errore React consentono di gestire normalmente un'eccezione non rilevata quando si verifica all'interno di un'applicazione React. Quando si verifica un'eccezione di questo tipo, è probabile che l'eccezione debba essere registrata. Il plug-in React per Application Insights fornisce un componente limite di errore che registra automaticamente l'eccezione quando si verifica.

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

Il AppInsightsErrorBoundary richiede il passaggio di due oggetti. Si tratta dell'istanza ReactPlugin creata per l'applicazione e di un componente di cui eseguire il rendering quando si verifica un'eccezione. Quando si verifica un'eccezione non gestita, trackException viene chiamato con le informazioni fornite al limite di errore e viene visualizzato il componente onError.

Il rilevamento delle eccezioni non rilevate è abilitato per impostazione predefinita. Se si desidera disabilitare il rilevamento delle eccezioni non rilevate, impostare disableExceptionCollection su 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();

Per tenere traccia delle eccezioni non rilevate, configurare ApplicationinsightsAngularpluginErrorService in app.module.ts:

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

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

Concatenare più gestori di eccezioni personalizzati

Concatenare più gestori di eccezioni personalizzati quando si vuole che l'applicazione gestisca normalmente ciò che in precedenza sarebbe stata un'eccezione non gestita, ma si vuole comunque segnalare questa eccezione come errore dell'applicazione.

Per concatenare più gestori di eccezioni personalizzati:

1. Creare gestori eccezioni personalizzati che implementano IErrorService.

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

2. Passare la matrice errorServices tramite extensionConfig.

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

Le informazioni sul dispositivo, che includono Browser, sistema operativo, versione e lingua, sono già raccolte dal pacchetto Web di Application Insights.

• Plugin React Native: oltre alle informazioni dell'agente utente dal browser, raccolte dal pacchetto Web di Application Insights, React Native raccoglie anche le informazioni sul dispositivo. Le informazioni sul dispositivo vengono raccolte automaticamente quando si aggiunge il plug-in.
• Plug-in manuale del dispositivo React Native: a seconda di come è stato configurato il plug-in quando è stata aggiunta l'estensione al codice, questo plug-in:
  • Non raccoglie informazioni sul dispositivo
  • Usa la propria classe di raccolta di informazioni sul dispositivo

Le informazioni sul dispositivo, che includono Browser, sistema operativo, versione e lingua, sono già raccolte dal pacchetto Web di Application Insights.

Tenere traccia dell'utilizzo dei componenti

Una funzionalità unica per il plug-in React è che è possibile instrumentare componenti specifici e monitorarli singolarmente.

Per instrumentare i componenti React con il rilevamento dell'utilizzo, applicare la funzione withAITracking del componente di ordine superiore. Per abilitare Application Insights per un componente, eseguire il wrapping di withAITracking attorno aò componente:

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

Misura l'ora dall'evento ComponentDidMount all'evento ComponentWillUnmount. Per rendere il risultato più accurato, sottrae il tempo in cui l'utente è stato inattivo usando React Component Engaged Time = ComponentWillUnmount timestamp - ComponentDidMount timestamp - idle time.

Esplorare i dati

Usare Esplora metriche di Monitoraggio di Azure per tracciare un grafico per il nome React Component Engaged Time (seconds) della metrica personalizzata e dividere questa metrica personalizzata per Component Name.

È anche possibile eseguire query personalizzate per dividere i dati di Application Insights per generare report e visualizzazioni in base alle esigenze. Ecco un esempio di query personalizzata. Procedere e incollarlo direttamente nell'editor di query per testarlo.

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

La visualizzazione delle nuove metriche personalizzate nel portale di Azure può richiedere fino a 10 minuti.

Usare Application Insights con il contesto React

Forniamo hook generali per consentire di personalizzare il rilevamento delle modifiche per singoli componenti. In alternativa, è possibile usare TrackMetric o useTrackEvent, che sono contatti predefiniti forniti per tenere traccia delle modifiche apportate ai componenti.

Gli hook React per Application Insights sono progettati per l'uso del Contesto React come aspetto che lo contiene. Per usare il Contesto, inizializzare Application Insights e quindi importare l'oggetto Contesto:

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

Questo provider di contesto rende Application Insights disponibile come hook useContext all'interno di tutti i componenti figlio di esso:

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

Hook useTrackMetric replica la funzionalità del componente di ordine superiore withAITracking, senza aggiungere un altro componente alla struttura del componente. L'hook accetta due argomenti:

• Istanza di Application Insights, che può essere ottenuta dall'hook useAppInsightsContext.
• Identificatore del componente per il rilevamento, ad esempio il relativo nome.

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;

Funziona come il componente di ordine superiore, ma risponde agli eventi del ciclo di vita hook anziché a un ciclo di vita dei componenti. Se è necessario eseguire interazioni specifiche, l'hook deve essere fornito in modo esplicito agli eventi utente.

useTrackEvent

Usare l'hook useTrackEvent per tenere traccia di qualsiasi evento personalizzato di cui potrebbe essere necessario tenere traccia di un'applicazione, ad esempio un clic su un pulsante o un'altra chiamata API. Accetta quattro argomenti:

• Istanza di Application Insights, che può essere ottenuta dall'hook useAppInsightsContext.
• Nome dell'evento.
• Oggetto dati evento che incapsula le modifiche che devono essere rilevate.
• Flag skipFirstRun (facoltativo) per ignorare la chiamata trackEvent all'inizializzazione. Il valore predefinito è impostato su true per simulare più strettamente il funzionamento della versione non Hook. Con hook useEffect, l'effetto viene attivato in ogni aggiornamento dei valori, inclusa l'impostazione iniziale del valore. Di conseguenza, il rilevamento inizia troppo presto, causando il rilevamento di eventi potenzialmente indesiderati.

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;

Quando si usa Hook, è possibile fornire un payload di dati per aggiungere altri dati all'evento quando vengono archiviati in Application Insights.

Disabilitare la raccolta automatica delle informazioni sul dispositivo

Se non’si desidera raccogliere le informazioni sul dispositivo, è possibile impostare disableDeviceCollection su 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();

Usare la propria classe di raccolta di informazioni sul dispositivo

Se si vuole eseguire l'override delle informazioni del proprio dispositivo, è possibile usare myDeviceInfoModule per raccogliere informazioni sul tuo dispositivo.

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

Eseguire l'override delle informazioni sul dispositivo

Usare l'interfaccia IDeviceInfoModule per astrarre il modo in cui il plug-in può accedere alle informazioni sul dispositivo. Questa interfaccia è una versione rimossa dell'interfaccia react-native-device-info e viene fornita principalmente per i test.

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

Se gli eventi vengono "bloccati" perché il Promise restituito tramite getUniqueId non viene mai risolto/rifiutato, è possibile chiamare setDeviceId() sul plug-in per sbloccare questo stato di attesa. Esiste anche un timeout automatico configurato tramite uniqueIdPromiseTimeout (il valore predefinito è 5 secondi), che chiamerà internamente setDeviceId() con qualsiasi valore configurato in precedenza.

N/D

Vedere la demo di Application Insights React.

Attualmente non disponibile.

Vedere la demo di Angular application insights.