Mengaktifkan ekstensi kerangka kerja untuk Application Insights JavaScript SDK

Selain SDK inti, ada juga plugin yang tersedia untuk kerangka kerja tertentu, seperti plugin React, plugin React Native, dan plugin Angular.

Plugin ini menyediakan fungsionalitas dan integrasi tambahan dengan kerangka kerja tertentu.

Prasyarat

  • Pastikan versi plugin React yang ingin Anda instal kompatibel dengan versi Application Insights Anda. Untuk informasi selengkapnya, lihat Matriks Kompatibilitas untuk plugin React.

Apa yang diaktifkan plug-in?

Plug-in React untuk Application Insights JavaScript SDK memungkinkan:

  • Melacak riwayat router
  • Melacak pengecualian
  • Melacak penggunaan komponen
  • Menggunakan Application Insights dengan Konteks React

Menambahkan plug-in

Untuk menambahkan plug-in, ikuti langkah-langkah di bagian ini.

Pasang paket


npm install @microsoft/applicationinsights-react-js

Menambahkan ekstensi ke kode Anda

Catatan

Pada tanggal 31 Maret 2025, dukungan untuk penyerapan kunci instrumentasi akan berakhir. Penyerapan kunci instrumentasi akan berjalan terus, namun kami tidak akan lagi menyediakan pembaruan atau dukungan terhadap fitur tersebut. Transisi ke string koneksi untuk memanfaatkan kemampuan baru.

Inisialisasi koneksi ke 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();

(Opsional) Menambahkan plug-in Click Analytics

Jika Anda ingin menambahkan plug-in Click Analytics:

  1. Batalkan komentar baris untuk Click Analytics.

  2. Lakukan salah satu hal berikut, bergantung pada plug-in mana yang Anda tambahkan:

    • Untuk React, hapus extensions: [reactPlugin],.
    • Untuk React Native, hapus extensions: [RNPlugin].
    • Untuk Angular, hapus extensions: [angularPlugin],.
  3. Lihat Menggunakan plug-in Click Analytics untuk melanjutkan proses penyiapan.

Konfigurasi

Bagian ini mencakup pengaturan konfigurasi untuk ekstensi kerangka kerja untuk Application Insights JavaScript SDK.

Melacak riwayat router

Nama Tipe Wajib diisi? Default Deskripsi
Riwayat object Opsional nihil Lacak riwayat router. Untuk informasi selengkapnya, lihat dokumentasi paket router React.

Untuk melacak riwayat router, sebagian besar pengguna dapat menggunakan enableAutoRouteTracking bidang dalam konfigurasi JavaScript SDK. Bidang ini mengumpulkan data yang sama untuk tampilan halaman sebagai history objek.

history Gunakan objek saat Anda menggunakan implementasi router yang tidak memperbarui URL browser, yang merupakan apa yang didengarkan konfigurasi. Anda tidak boleh mengaktifkan enableAutoRouteTracking bidang dan history objek, karena Anda akan mendapatkan beberapa peristiwa tampilan halaman.

Contoh kode berikut menunjukkan cara mengaktifkan enableAutoRouteTracking bidang .

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

Melacak pengecualian

Batas kesalahan react menyediakan cara untuk menangani pengecualian yang tidak tertangkap ketika terjadi dalam aplikasi React. Ketika pengecualian seperti itu terjadi, kemungkinan pengecualian perlu dicatat. Plug-in React untuk Application Insights menyediakan komponen batas kesalahan yang secara otomatis mencatat pengecualian saat terjadi.

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

Membutuhkan AppInsightsErrorBoundary dua alat peraga untuk diteruskan ke itu. Instans adalah instans yang ReactPlugin dibuat untuk aplikasi dan komponen yang akan dirender saat pengecualian terjadi. Ketika pengecualian yang tidak tertangani terjadi, trackException dipanggil dengan informasi yang diberikan ke batas kesalahan, dan onError komponen muncul.

Mengumpulkan informasi perangkat

Informasi perangkat, yang mencakup Browser, OS, versi, dan bahasa, sudah dikumpulkan oleh paket web Application Insights.

Konfigurasi (lainnya)

Melacak penggunaan komponen

Fitur yang unik untuk plug-in React adalah Anda dapat melengkapi komponen tertentu dan melacaknya satu per satu.

Untuk melengkapi komponen React dengan pelacakan penggunaan, terapkan withAITracking fungsi komponen dengan urutan yang lebih tinggi. Untuk mengaktifkan Application Insights untuk komponen, bungkus withAITracking komponen:

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

Ini mengukur waktu dari ComponentDidMount peristiwa melalui ComponentWillUnmount peristiwa. Untuk membuat hasilnya lebih akurat, ini mengurangi waktu di mana pengguna menganggur dengan menggunakan React Component Engaged Time = ComponentWillUnmount timestamp - ComponentDidMount timestamp - idle time.

Jelajahi sampel Anda

Gunakan penjelajah metrik Azure Monitor untuk memplot bagan untuk nama React Component Engaged Time (seconds) metrik kustom dan membagi metrik kustom ini dengan Component Name.

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

Anda juga dapat menjalankan kueri kustom untuk membagi data Application Insights untuk menghasilkan laporan dan visualisasi sesuai kebutuhan Anda. Berikut adalah contoh kueri kustom. Lanjutkan dan tempelkan langsung ke editor kueri untuk mengujinya.

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

Diperlukan waktu hingga 10 menit agar metrik kustom baru muncul di portal Azure.

Menggunakan Application Insights dengan Konteks React

Kami menyediakan kait umum untuk memungkinkan Anda menyesuaikan pelacakan perubahan untuk komponen individual. Atau, Anda dapat menggunakan useTrackMetric atau useTrackEvent, yang merupakan kontak yang telah ditentukan sebelumnya yang kami sediakan untuk melacak perubahan pada komponen.

React Hooks untuk Application Insights dirancang untuk menggunakan React Context sebagai aspek yang memuatnya. Untuk menggunakan Konteks, inisialisasi Application Insights, lalu impor objek Konteks:

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

Penyedia Konteks ini membuat Application Insights tersedia sebagai useContext Hook dalam semua komponen turunannya:

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

useTrackMetric Hook mereplikasi fungsionalitas withAITracking komponen dengan urutan yang lebih tinggi, tanpa menambahkan komponen lain ke struktur komponen. Hook mengambil dua argumen:

  • Instans Application Insights, yang dapat diperoleh dari useAppInsightsContext Hook.
  • Pengidentifikasi untuk komponen untuk pelacakan, seperti namanya.
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;

Ini beroperasi seperti komponen urutan yang lebih tinggi, tetapi merespons peristiwa siklus hidup Hooks daripada siklus hidup komponen. Jika ada kebutuhan untuk berjalan pada interaksi tertentu, Hook harus secara eksplisit disediakan untuk peristiwa pengguna.

useTrackEvent

useTrackEvent Gunakan Hook untuk melacak peristiwa kustom apa pun yang mungkin perlu dilacak aplikasi, seperti klik tombol atau panggilan API lainnya. Dibutuhkan empat argumen:

  • Instans Application Insights, yang dapat diperoleh dari useAppInsightsContext Hook.
  • Nama untuk peristiwa tersebut.
  • Objek data peristiwa yang merangkum perubahan yang harus dilacak.
  • Bendera skipFirstRun (opsional) untuk melewati panggilan trackEvent saat inisialisasi. Nilai default diatur ke true untuk menimpulkan lebih dekat cara kerja versi non-Hook. Dengan useEffect Hooks, efek dipicu pada setiap pembaruan nilai termasuk pengaturan awal nilai. Akibatnya, pelacakan dimulai terlalu dini, yang menyebabkan peristiwa yang berpotensi tidak diinginkan dilacak.
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;

Saat Hook digunakan, payload data dapat disediakan untuk menambahkan lebih banyak data ke peristiwa saat disimpan di Application Insights.

Aplikasi sampel

Lihat demo React Application Insights.

Tanya jawab umum

Bagian ini menyediakan jawaban atas pertanyaan umum.

Bagaimana Application Insights menghasilkan informasi perangkat seperti browser, OS, bahasa, dan model?

Browser meneruskan string Agen Pengguna di header HTTP permintaan. Layanan penyerapan Application Insights menggunakan UA Parser untuk menghasilkan bidang yang Anda lihat dalam tabel dan pengalaman data. Akibatnya, pengguna Application Insights tidak dapat mengubah bidang ini.

Terkadang, data ini mungkin hilang atau tidak akurat jika pengguna atau perusahaan menonaktifkan pengiriman Agen Pengguna di pengaturan browser. Regex UA Parser mungkin tidak menyertakan semua informasi perangkat. Atau Application Insights mungkin belum mengadopsi pembaruan terbaru.

Langkah berikutnya