Bagikan melalui

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

Apa yang dimungkinkan oleh plug-in?

Plug-in React untuk Application Insights JavaScript SDK memungkinkan:

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

Tambahkan plug-in

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

Pasang paket 


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

Menambahkan ekstensi ke kode Anda

Catatan

Pada tanggal 31 Maret 2025, dukungan untuk penggunaan 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:

Catatan

Jika Anda menggunakan riwayat versi 5 atau yang lebih baru, opsi nama dasar tidak lagi didukung di createBrowserHistory.

Alih-alih const browserHistory = createBrowserHistory({ basename: '' });, gunakan const browserHistory = createBrowserHistory();.

Untuk memeriksa versi riwayat mana yang Anda gunakan, jalankan 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();

(Tambahan) Tambahkan 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? Bawaan Deskripsi
Riwayat objek 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 seperti objek history.

Gunakan objek history saat Anda menggunakan implementasi router yang tidak memperbarui URL browser, yang dipantau oleh konfigurasi. Anda tidak seharusnya mengaktifkan kolom enableAutoRouteTracking dan objek history, karena Anda akan menerima berkali-kali 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 kesalahan

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

AppInsightsErrorBoundary memerlukan dua properti untuk diteruskan kepadanya. Mereka adalah instans yang ReactPlugin dibuat untuk aplikasi dan merupakan komponen yang akan dirender ketika pengecualian terjadi. Ketika pengecualian yang tidak tertangani terjadi, trackException dipanggil dengan informasi yang diberikan ke pembatas kesalahan, dan komponen onError 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 menginstrumen komponen spesifik dan melacaknya secara individu.

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

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 peristiwa ComponentDidMount hingga peristiwa ComponentWillUnmount. 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.

Cuplikan layar yang memperlihatkan bagan yang menampilkan metrik kustom React Component Engaged Time (detik) dibagi berdasarkan Nama Komponen

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 Konteks React sebagai elemen yang menampungnya. 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 berfungsi seperti komponen higher-order, tetapi merespons peristiwa siklus hidup Hooks bukan 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 acara.
  • Objek data peristiwa yang merangkum perubahan yang harus dilacak.
  • Flag skipFirstRun (opsional) untuk melewatkan panggilan trackEvent pada saat inisialisasi. Nilai default diatur ke true untuk lebih menyerupai 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

Langkah berikutnya