Udostępnij za pośrednictwem

Włącz rozszerzenie frameworku dla zestawu SDK JavaScript usługi Application Insights

Oprócz podstawowego zestawu SDK dostępne są również wtyczki dla określonych struktur, takich jak wtyczka React, wtyczka React Native i wtyczka Angular.

Te wtyczki zapewniają dodatkową funkcjonalność i integrację z określoną strukturą.

Wymagania wstępne

  • Zainstaluj zestaw SDK języka JavaScript.
  • Upewnij się, że wersja wtyczki React, którą chcesz zainstalować, jest zgodna z twoją wersją usługi Application Insights. Aby uzyskać więcej informacji, zobacz Macierz zgodności dla wtyczki React.

Co włącza wtyczka?

Wtyczka React dla zestawu SDK języka JavaScript usługi Application Insights umożliwia:

  • Śledzenie historii routera
  • Śledzenie wyjątków
  • Śledzenie użycia składników
  • Używanie usługi Application Insights z kontekstem React

Dodawanie wtyczki

Aby dodać wtyczkę, wykonaj kroki opisane w tej sekcji.

Instalowanie pakietu 


npm install @microsoft/applicationinsights-react-js @microsoft/applicationinsights-web

Dodawanie rozszerzenia do kodu

Uwaga

31 marca 2025 r. zostanie zakończone świadczenie pomocy technicznej dla pozyskiwania klucza instrumentacji. Pobieranie klucza instrumentacji będzie nadal działać, ale nie będziemy już udostępniać aktualizacji ani wsparcia dla tej funkcji. Przejście do ciągów połączenia w celu skorzystania z nowych funkcji.

Inicjowanie połączenia z usługą Application Insights:

Uwaga

Jeśli używasz historii w wersji 5 lub nowszej, opcja basename nie jest już obsługiwana w pliku createBrowserHistory.

Zamiast elementu const browserHistory = createBrowserHistory({ basename: '' }); należy używać elementu const browserHistory = createBrowserHistory();.

Aby sprawdzić, której wersji historii używasz, uruchom polecenie npm list history.

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

(Opcjonalnie) Dodawanie wtyczki Click Analytics

Jeśli chcesz dodać wtyczkę Click Analytics:

  1. Usuń znaczniki komentarza dla funkcji Click Analytics.

  2. Wykonaj jedną z następujących czynności, w zależności od dodawanej wtyczki:

    • W przypadku platformy React usuń element extensions: [reactPlugin],.
    • W przypadku oprogramowania React Native usuń element extensions: [RNPlugin].
    • W przypadku platformy Angular usuń element extensions: [angularPlugin],.

  3. Aby kontynuować konfigurację, skorzystaj z wtyczki Click Analytics.

Konfigurowanie

W tej sekcji opisano ustawienia konfiguracji rozszerzeń platformy dla zestawu SDK języka JavaScript usługi Application Insights.

Śledzenie historii routera

Nazwisko Typ Wymagane? Domyślny opis
historia obiekt Opcjonalnie null Śledzenie historii routera. Aby uzyskać więcej informacji, zobacz dokumentację pakietu routera React.

Aby śledzić historię routerów, większość użytkowników może używać enableAutoRouteTracking pola w konfiguracji zestawu SDK języka JavaScript. To pole zbiera te same dane dla widoków stron co history obiekt.

Użyj history obiektu, gdy używasz implementacji routera, która nie aktualizuje adresu URL przeglądarki, co jest tym, czego nasłuchuje konfiguracja. Nie należy włączać zarówno pola enableAutoRouteTracking, jak i obiektu history, ponieważ otrzymasz wiele zdarzeń widoku strony.

W poniższym przykładzie kodu pokazano, jak włączyć enableAutoRouteTracking pole.

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

Śledzenie wyjątków

Granice błędów React umożliwiają bezpieczną obsługę nieuchwyconego wyjątku, gdy wystąpi w aplikacji React. W przypadku wystąpienia takiego wyjątku prawdopodobnie należy zarejestrować wyjątek. Wtyczka React dla usługi Application Insights udostępnia składnik granicy błędu, który automatycznie rejestruje wyjątek, gdy wystąpi.

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

Element AppInsightsErrorBoundary wymaga przekazania do niego dwóch rekwizytów. ReactPlugin Są one instancją utworzoną dla aplikacji oraz składnikiem renderowanym w przypadku wystąpienia wyjątku. Gdy wystąpi nieobsługiwany wyjątek, trackException jest wywoływany z informacjami podanymi do granicy błędów, a onError komponent jest wyświetlany.

Zbieranie informacji o urządzeniu

Informacje o urządzeniu, w tym przeglądarka, system operacyjny, wersja i język, są już zbierane przez pakiet internetowy usługi Application Insights.

Konfiguracja (inne)

Śledzenie użycia składników

Funkcja unikatowa dla wtyczki React polega na tym, że można instrumentować określone składniki i śledzić je indywidualnie.

Aby instrumentować komponenty React za pomocą śledzenia użycia, zastosuj funkcję wyższego rzędu withAITracking. Aby włączyć usługę Application Insights dla składnika, zawijaj withAITracking wokół składnika:

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

Mierzy czas od ComponentDidMount zdarzenia do ComponentWillUnmount zdarzenia. Aby wynik był dokładniejszy, odejmuje czas bezczynności użytkownika przy użyciu polecenia React Component Engaged Time = ComponentWillUnmount timestamp - ComponentDidMount timestamp - idle time.

Eksplorowanie danych

Użyj Eksploratora metryk usługi Azure Monitor, aby wykreślić wykres dla niestandardowej nazwy React Component Engaged Time (seconds) metryki i podzielić tę niestandardową metrykę według wartości Component Name.

Zrzut ekranu przedstawiający wykres pokazujący niestandardową metrykę czas zaangażowania składnika React (w sekundach) podzieloną według nazwy składnika

Możesz również uruchamiać zapytania niestandardowe, aby podzielić dane usługi Application Insights w celu generowania raportów i wizualizacji zgodnie z wymaganiami. Oto przykład zapytania niestandardowego. Przejdź dalej i wklej go bezpośrednio do edytora zapytań, aby go przetestować.

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

Wyświetlenie nowych metryk niestandardowych w portalu Azure może potrwać do 10 minut.

Używanie usługi Application Insights z kontekstem React

Udostępniamy ogólne haki umożliwiające dostosowanie śledzenia zmian dla poszczególnych składników. Alternatywnie można użyć useTrackMetric lub useTrackEvent, które są wstępnie zdefiniowanymi kontaktami, które udostępniamy do śledzenia zmian w składnikach.

Haczyki React dla Application Insights są zaprojektowane do używania kontekstu React jako formy jego zawierania. Aby użyć kontekstu, zainicjuj usługę Application Insights, a następnie zaimportuj obiekt 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>
    );
};

Ten dostawca kontekstu udostępnia Application Insights jako useContext hook we wszystkich jego składnikach podrzędnych.

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

Element useTrackMetric Hook replikuje funkcjonalność withAITracking składnika o wyższym porządku bez dodawania innego składnika do struktury składników. Hak przyjmuje dwa argumenty:

  • Wystąpienie usługi Application Insights, które można uzyskać za pomocą useAppInsightsContext Hook.
  • Identyfikator składnika do śledzenia, taki jak jego nazwa.
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;

Działa jak komponent wyższego rzędu, ale reaguje na zdarzenia cyklu życia Hooków, a nie na cykl życia komponentu. Jeśli konieczne jest uruchomienie określonych interakcji, Hook musi zostać jawnie udostępniony dla zdarzeń użytkownika.

useTrackEvent

Użyj elementu useTrackEvent Hook, aby śledzić dowolne zdarzenie niestandardowe, które może być konieczne przez aplikację, na przykład kliknięcie przycisku lub inne wywołanie interfejsu API. Przyjmuje cztery argumenty:

  • Wystąpienie usługi Application Insights, które można uzyskać z komponentu useAppInsightsContext Hook.
  • Nazwa zdarzenia.
  • Obiekt danych zdarzenia, który obejmuje zmiany wymagające śledzenia.
  • skipFirstRun (opcjonalnie) flaga, aby pominąć wywołanie trackEvent podczas inicjowania. Domyślna wartość jest ustawiona na true, aby bardziej zbliżyć się do sposobu działania wersji bez Hooka. W przypadku useEffect Hooks efekt jest wywoływany przy każdej aktualizacji wartości, łącznie z początkowym ustawieniem wartości. W rezultacie śledzenie rozpoczyna się zbyt wcześnie, co powoduje śledzenie potencjalnie niechcianych zdarzeń.
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;

Gdy element Hook jest używany, można podać do niego ładunek danych, aby dodać więcej danych do zdarzenia, gdy jest on przechowywany w usłudze Application Insights.

Przykładowa aplikacja

Zapoznaj się z demonstracją React usługi Application Insights.

Następne kroki