Abilitare un'estensione del framework per Application Insights JavaScript SDK

  • Articolo

Oltre all'SDK principale, sono disponibili anche plug-in per framework specifici, ad esempio il plug-in React, il plug-in React Native e il plug-in Angular.

Questi plug-in offrono funzionalità e integrazione aggiuntive con il framework specifico.

Prerequisiti

  • 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.

Cosa abilita il plug-in?

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

Aggiungere un plug-in

Per aggiungere un plug-in, seguire la procedura descritta in questa sezione.

Installare il pacchetto 


npm install @microsoft/applicationinsights-react-js

Aggiungere l'estensione al codice

Nota

Il 31 marzo 2025, il supporto per l'inserimento delle chiavi di strumentazione terminerà. L'inserimento di chiavi di strumentazione continuerà a funzionare, ma non forniamo più aggiornamenti o supporto per la funzionalità. Passare alle stringa di connessione per sfruttare le nuove funzionalità.

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

(Facoltativo) Aggiungere il plug-in Click Analytics

Per aggiungere il plug-in Click Analytics:

  1. Rimuovere il commento dalle righe per Click Analytics.

  2. Eseguire una delle operazioni seguenti, a seconda del plug-in che si sta aggiungendo:

    • Per React, eliminare extensions: [reactPlugin],.
    • Per React Native eliminare extensions: [RNPlugin].
    • Per Angular, eliminare extensions: [angularPlugin],.

  3. Vedere Usare il plug-in Click Analytics per continuare con il processo di installazione.

Configurazione

Questa sezione illustra le impostazioni di configurazione per le estensioni del framework per Application Insights JavaScript SDK.

Tenere traccia della cronologia dei router

Nome Type Obbligatorio? Default Descrizione
history oggetto Facoltativo Null Tenere traccia della cronologia del router. Per altre informazioni, vedere la documentazione del pacchetto router React.

Per tenere traccia della cronologia dei router, la maggior parte degli utenti può usare il enableAutoRouteTracking campo nella configurazione di JavaScript SDK. Questo campo raccoglie gli stessi dati per le visualizzazioni pagina dell'oggetto history .

Usare l'oggetto history quando si usa un'implementazione del router che non aggiorna l'URL del browser, ovvero ciò che la configurazione è in ascolto. Non è consigliabile abilitare sia il campo history che l'oggettoenableAutoRouteTracking, perché si otterranno più eventi di visualizzazione pagina.

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

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

Traccia delle eccezioni

I limiti degli errori 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>
    );
};

Richiede AppInsightsErrorBoundary il passaggio di due oggetti props. Sono l'istanza ReactPlugin creata per l'applicazione e un componente di cui eseguire il rendering quando si verifica un'eccezione. Quando si verifica un'eccezione non gestita, trackException viene chiamata con le informazioni fornite al limite di errore e viene visualizzato il onError componente.

Raccogliere informazioni sul dispositivo

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

Configurazione (altro)

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 withAITracking funzione del componente di ordine superiore. Per abilitare Application Insights per un componente, eseguire il wrapping withAITracking del 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.

Screenshot that shows a chart that displays the custom metric React Component Engaged Time (seconds) split by 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 nella 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 usareTrackMetric 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 Context, inizializzare Application Insights e quindi importare l'oggetto 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>
    );
};

Questo provider di contesto rende Application Insights disponibile come useContext hook 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 withAITracking componente di ordine superiore, 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

useTrackEvent Usare Hook per tenere traccia di qualsiasi evento personalizzato che 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.
  • skipFirstRun (facoltativo) flag per ignorare la chiamata all'inizializzazione trackEvent . Il valore predefinito è impostato su true per simulare più strettamente il funzionamento della versione non Hook. Con useEffect hook, 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.

Esempio di app

Vedere la demo react di Application Insights.

Domande frequenti

Questa sezione fornisce le risposte alle domande comuni.

In che modo Application Insights genera informazioni sul dispositivo, ad esempio browser, sistema operativo, lingua e modello?

Il browser passa la stringa agente utente nell'intestazione HTTP della richiesta. Il servizio di inserimento di Application Insights usa il parser UA per generare i campi visualizzati nelle tabelle dati ed esperienze. Di conseguenza, gli utenti di Application Insights non possono modificare questi campi.

In alcuni casi, questi dati potrebbero essere mancanti o imprecisi se l'utente o l'organizzazione disabilita l'invio dell'agente utente nelle impostazioni del browser. Le espressioni regolari del parser UA potrebbero non includere tutte le informazioni sul dispositivo. In alternativa, Application Insights potrebbe non aver adottato gli aggiornamenti più recenti.

Passaggi successivi