Włączanie rozszerzenia platformy dla zestawu SDK javaScript usługi Application Szczegółowe informacje

  • Artykuł

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 wersją aplikacji Szczegółowe informacje. Aby uzyskać więcej informacji, zobacz Macierz zgodności dla wtyczki React.

Co włącza wtyczka?

Wtyczka React dla zestawu SDK javaScript usługi Application Szczegółowe informacje umożliwia:

  • Śledzenie historii routera
  • Śledzenie wyjątków
  • Śledzenie użycia składników
  • Używanie Szczegółowe informacje aplikacji z kontekstem React

Dodawanie wtyczki

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

Instalowanie pakietu 


npm install @microsoft/applicationinsights-react-js

Dodawanie rozszerzenia do kodu

Uwaga

31 marca 2025 r. zostanie zakończone świadczenie pomocy technicznej dla pozyskiwania klucza instrumentacji. Pozyskiwanie klucza instrumentacji będzie nadal działać, ale nie udostępnimy już aktualizacji ani obsługi funkcji. Przejście do parametry połączenia w celu skorzystania z nowych funkcji.

Zainicjuj połączenie z aplikacją Szczegółowe informacje:

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 pozycji 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. Zobacz Używanie wtyczki Click Analytics, aby kontynuować proces instalacji.

Konfigurowanie

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

Śledzenie historii routera

Imię i nazwisko/nazwa Type Wymagane? Wartość domyślna 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.

history Użyj obiektu, gdy używasz implementacji routera, która nie aktualizuje adresu URL przeglądarki, czyli tego, na czym nasłuchuje konfiguracja. Nie należy włączać zarówno pola, jak enableAutoRouteTracking i history obiektu, 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 zapewniają możliwość bezpiecznego obsługi nieuchwyconego wyjątku w przypadku wystąpienia w aplikacji React. W przypadku wystąpienia takiego wyjątku prawdopodobnie należy zarejestrować wyjątek. Wtyczka React dla aplikacji Szczegółowe informacje 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 wystąpieniem utworzonym dla aplikacji i składnikiem, który ma być renderowany w przypadku wystąpienia wyjątku. Gdy wystąpi nieobsługiwany wyjątek, trackException jest wywoływany z informacjami podanymi na granicy błędu, a onError składnik jest wyświetlany.

Zbieranie informacji o urządzeniu

Informacje o urządzeniu, które obejmują przeglądarkę, system operacyjny, wersję i język, są już zbierane przez pakiet internetowy application Szczegółowe informacje.

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ć składniki React za pomocą śledzenia użycia, zastosuj funkcję składnika wyższego withAITracking rzędu. Aby włączyć Szczegółowe informacje aplikacji 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 przez ComponentWillUnmount zdarzenie. 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.

Screenshot that shows a chart that displays the custom metric React Component Engaged Time (seconds) split by Component Name

Możesz również uruchamiać zapytania niestandardowe, aby podzielić dane aplikacji Szczegółowe informacje 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 witrynie Azure Portal może potrwać do 10 minut.

Używanie Szczegółowe informacje aplikacji 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ć funkcji UseTrackMetric lub useTrackEvent, które są wstępnie zdefiniowanymi kontaktami, które udostępniamy do śledzenia zmian w składnikach.

Zestawy React Hooks for Application Szczegółowe informacje są przeznaczone do używania kontekstu React jako aspektu zawierającego. Aby użyć kontekstu, zainicjuj Szczegółowe informacje aplikacji, 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 aplikację Szczegółowe informacje jako useContext element zaczepienia we wszystkich 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. Element Hook przyjmuje dwa argumenty:

  • Wystąpienie aplikacji Szczegółowe informacje, które można uzyskać z useAppInsightsContext elementu 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 składnik o wyższej kolejności, ale reaguje na zdarzenia cyklu życia haków, a nie cykl życia składnika. Jeśli konieczne jest uruchomienie określonych interakcji, element Hook musi zostać jawnie udostępniony 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 aplikacji Szczegółowe informacje, które można uzyskać z elementu useAppInsightsContext Hook.
  • Nazwa zdarzenia.
  • Obiekt danych zdarzenia, który hermetyzuje zmiany, które muszą być śledzone.
  • skipFirstRun (opcjonalnie) flaga, aby pominąć wywoływanie trackEvent wywołania podczas inicjowania. Wartość domyślna jest ustawiona tak, aby bardziej naśladować true sposób działania wersji innej niż hook. W przypadku useEffect elementów hooks efekt jest wyzwalany dla każdej aktualizacji wartości, w tym początkowe ustawienie 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 aplikacji Szczegółowe informacje.

Przykładowa aplikacja

Zapoznaj się z pokazem aplikacji Szczegółowe informacje React.

Często zadawane pytania

Ta sekcja zawiera odpowiedzi na typowe pytania.

Jak aplikacja Szczegółowe informacje generuje informacje o urządzeniu, takie jak przeglądarka, system operacyjny, język i model?

Przeglądarka przekazuje ciąg agenta użytkownika w nagłówku HTTP żądania. Usługa pozyskiwania aplikacji Szczegółowe informacje używa analizatora interfejsu użytkownika do generowania pól widocznych w tabelach danych i środowiskach. W związku z tym użytkownicy aplikacji Szczegółowe informacje nie mogą zmienić tych pól.

Czasami te dane mogą być brakujące lub niedokładne, jeśli użytkownik lub przedsiębiorstwo wyłączy wysyłanie agenta użytkownika w ustawieniach przeglądarki. Wyrażenia regularne analizatora UA mogą nie zawierać wszystkich informacji o urządzeniu. Lub aplikacja Szczegółowe informacje może nie przyjąć najnowszych aktualizacji.

Następne kroki