تمكين ملحق إطار عمل ل Application Insights JavaScript SDK

  • مقالة

بالإضافة إلى SDK الأساسي، هناك أيضا مكونات إضافية متاحة لأطر عمل محددة، مثل المكون الإضافي React والمكون الإضافي React Native والمكون الإضافي Angular.

توفر هذه المكونات الإضافية وظائف إضافية والتكامل مع إطار العمل المحدد.

المتطلبات الأساسية

ما الذي يمكن المكون الإضافي من القيام به؟

يتيح المكون الإضافي React ل Application Insights JavaScript SDK ما يلي:

  • تعقب محفوظات الموجه
  • تتبع الاستثناءات
  • تعقب استخدام المكونات
  • استخدام Application Insights مع React Context

إضافة مكون إضافي

لإضافة مكون إضافي، اتبع الخطوات الواردة في هذا القسم.

تثبيت الحزمة


npm install @microsoft/applicationinsights-react-js

إضافة الملحق إلى التعليمات البرمجية الخاصة بك

إشعار

في 31 مارس 2025، سينتهي دعم إدخال مفاتيح الأجهزة. سيستمر استيعاب مفتاح الأجهزة في العمل ولكننا لن نقوم بتوفير تحديثات أو أي دعم للميزة. الانتقال إلى سلاسل الاتصال للاستفادة من الإمكانات الجديدة.

تهيئة اتصال إلى 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();

(اختياري) إضافة المكون الإضافي Click Analytics

إذا كنت تريد إضافة المكون الإضافي Click Analytics:

  1. قم بإلغاء التعليق على خطوط Click Analytics.

  2. قم بأحد الإجراءات التالية، استنادا إلى المكون الإضافي الذي تضيفه:

    • بالنسبة إلى React، احذف extensions: [reactPlugin],.
    • بالنسبة إلى React Native، احذف extensions: [RNPlugin].
    • بالنسبة إلى Angular، احذف extensions: [angularPlugin],.

  3. راجع استخدام المكون الإضافي Click Analytics لمتابعة عملية الإعداد.

التكوين

يغطي هذا القسم إعدادات التكوين لملحقات إطار العمل ل Application Insights JavaScript SDK.

تعقب محفوظات الموجه

الاسم النوع مطلوب؟ Default ‏‏الوصف
السجل كائن اختياري قيمة فارغة تعقب محفوظات الموجه. لمزيد من المعلومات، راجع وثائق حزمة موجه React.

لتعقب محفوظات الموجه، يمكن لمعظم المستخدمين استخدام enableAutoRouteTracking الحقل في تكوين JavaScript SDK. يجمع هذا الحقل نفس البيانات لطرق عرض الصفحة كعنصر history .

history استخدم الكائن عند استخدام تطبيق جهاز توجيه لا يقوم بتحديث عنوان URL للمستعرض، وهو ما يستمع إليه التكوين. يجب عدم تمكين كل من enableAutoRouteTracking الحقل والعنصر history ، لأنك ستحصل على أحداث عرض صفحة متعددة.

يوضح مثال التعليمات البرمجية enableAutoRouteTracking التالي كيفية تمكين الحقل.

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

تتبع الاستثناءات

توفر حدود خطأ React طريقة للتعامل بأمان مع استثناء غير محدد عند حدوثه داخل تطبيق React. عند حدوث مثل هذا الاستثناء، من المحتمل أن يكون الاستثناء بحاجة إلى تسجيل. يوفر المكون الإضافي React ل Application Insights مكون حد الخطأ الذي يسجل الاستثناء تلقائيا عند حدوثه.

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 يتطلب الأمر تمرير اثنين من الخصائص إليه. إنها المثيل الذي ReactPlugin تم إنشاؤه للتطبيق ومكون ليتم عرضه عند حدوث استثناء. عند حدوث استثناء غير معالج، trackException يتم استدعاء بالمعلومات المقدمة إلى حد الخطأ، onError ويظهر المكون.

جمع معلومات الجهاز

يتم بالفعل تجميع معلومات الجهاز، التي تتضمن المستعرض ونظام التشغيل والإصدار واللغة، بواسطة حزمة ويب Application Insights.

التكوين (غير ذلك)

تعقب استخدام المكونات

ميزة فريدة من نوعها للمكون الإضافي React هي أنك قادر على وضع علامة على مكونات محددة وتتبعها بشكل فردي.

لوضع علامة على مكونات React مع تتبع الاستخدام، قم بتطبيق withAITracking وظيفة المكون ذات الترتيب الأعلى. لتمكين Application Insights لمكون، التفاف 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);

يقيس الوقت من ComponentDidMount الحدث من ComponentWillUnmount خلال الحدث. لجعل النتيجة أكثر دقة، فإنها تطرح الوقت الذي كان المستخدم راكد فيه باستخدام React Component Engaged Time = ComponentWillUnmount timestamp - ComponentDidMount timestamp - idle time.

استكشف بياناتك

استخدم مستكشف مقاييس Azure Monitor لرسم مخطط لاسم React Component Engaged Time (seconds) المقياس المخصص وتقسيم هذا المقياس المخصص حسب Component Name.

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

يمكنك أيضا تشغيل استعلامات مخصصة لتقسيم بيانات Application Insights لإنشاء تقارير وتصورات وفقا لمتطلباتك. فيما يلي مثال على استعلام مخصص. امض قدما والصقه مباشرة في محرر الاستعلام لاختباره.

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

قد يستغرق ظهور المقاييس المخصصة الجديدة في مدخل Microsoft Azure ما يصل إلى 10 دقائق.

استخدام Application Insights مع React Context

نحن نقدم خطافات عامة للسماح لك بتخصيص تعقب التغيير للمكونات الفردية. بدلا من ذلك، يمكنك استخدامTrackMetric أو useTrackEvent، وهي جهات اتصال معرفة مسبقا نوفرها لتعقب التغييرات على المكونات.

تم تصميم React Hooks لـ Application Insights لاستخدام سياق التفاعل كجانب يحتوي عليه. لاستخدام Context، قم بتهيئة Application Insights، ثم قم باستيراد كائن 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>
    );
};

يجعل موفر السياق هذا Application Insights متوفرا useContext ك Hook داخل جميع المكونات التابعة له:

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;
استخدامTrackMetric

ينسخ useTrackMetric Hook وظيفة withAITracking المكون ذي الترتيب الأعلى، دون إضافة مكون آخر إلى بنية المكون. يأخذ Hook وسيطتين:

  • مثيل Application Insights، والذي يمكن الحصول عليه من Hook useAppInsightsContext .
  • معرف للمكون للتعقب، مثل اسمه.
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;

يعمل مثل المكون الأعلى ترتيبا، ولكنه يستجيب لأحداث دورة حياة Hooks بدلا من دورة حياة المكون. إذا كانت هناك حاجة للتشغيل على تفاعلات معينة، يجب توفير Hook بشكل صريح لأحداث المستخدم.

useTrackEvent

استخدم Hook useTrackEvent لتعقب أي حدث مخصص قد يحتاج التطبيق إلى تعقبه، مثل النقر على زر أو استدعاء واجهة برمجة التطبيقات الأخرى. يتطلب الأمر أربع وسيطات:

  • مثيل Application Insights، والذي يمكن الحصول عليه من Hook useAppInsightsContext .
  • اسم الحدث.
  • كائن بيانات الحدث الذي يغلف التغييرات التي يجب تعقبها.
  • علامة skipFirstRun (اختيارية) لتخطي استدعاء الاستدعاء trackEvent عند التهيئة. يتم تعيين القيمة الافتراضية إلى true لمحاكاة الطريقة التي يعمل بها الإصدار غير Hook بشكل وثيق. باستخدام useEffect Hooks، يتم تشغيل التأثير على كل تحديث قيمة بما في ذلك الإعداد الأولي للقيمة. ونتيجة لذلك، يبدأ التعقب مبكرا جدا، مما يؤدي إلى تعقب الأحداث غير المرغوب فيها.
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;

عند استخدام Hook، يمكن توفير حمولة بيانات إليه لإضافة المزيد من البيانات إلى الحدث عند تخزينه في Application Insights.

تطبيق النموذج

تحقق من العرض التوضيحي حول Application Insights React.

الأسئلة الشائعة

يقدم هذا القسم إجابات للأسئلة الشائعة.

كيف يقوم Application Insights بإنشاء معلومات الجهاز مثل المتصفح ونظام التشغيل واللغة والطراز؟

يمرر المستعرض سلسلة عامل المستخدم في رأس HTTP للطلب. تستخدم خدمة استيعاب Application Insights محلل UA لإنشاء الحقول التي تراها في جداول البيانات وتجاربها. ونتيجة لذلك، لا يمكن لمستخدمي Application Insights تغيير هذه الحقول.

في بعض الأحيان، قد تكون هذه البيانات مفقودة أو غير دقيقة إذا عطل المستخدم أو المؤسسة إرسال عامل المستخدم في إعدادات المستعرض. قد لا تتضمن سجلات محلل UA جميع معلومات الجهاز. أو ربما لم تعتمد Application Insights آخر التحديثات.

الخطوات التالية