تمكين المكون الإضافي Click Analytics Auto-Collection

مقالة
09/13/2024

ملحقات ميزات Application Insights JavaScript SDK هي ميزات إضافية يمكن إضافتها إلى Application Insights JavaScript SDK لتحسين وظائفها.

في هذه المقالة، نغطي المكون الإضافي Click Analytics، الذي يتعقب تلقائيا أحداث النقر على صفحات الويب ويستخدم data-* سمات أو علامات مخصصة على عناصر HTML لملء بيانات تتبع الاستخدام للحدث.

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

قم بتثبيت JavaScript SDK قبل تمكين المكون الإضافي Click Analytics.

ما هي البيانات التي يجمعها المكون الإضافي؟

يتم التقاط خصائص المفتاح التالية بشكل افتراضي عند تمكين المكون الإضافي.

خصائص الحدث المخصصة

Name	‏‏الوصف	عينة
الاسم	اسم الحدث المخصص. لمزيد من المعلومات حول كيفية ملء الاسم، راجع عمود الاسم.	حول
itemType	نوع الحدث.	customEvent
sdkVersion	إصدار Application Insights SDK مع النقر فوق المكون الإضافي.	JavaScript:2_ClickPlugin2

الأبعاد المخصصة

Name	‏‏الوصف	عينة
actionType	نوع الإجراء الذي تسبب في حدث النقر. يمكن أن يكون النقر بزر الماوس الأيمن أو الأيمن.	CL
baseTypeSource	مصدر النوع الأساسي للحدث المخصص.	ClickEvent
clickCoordinates	إحداثيات مكان بدء حدث النقر.	659X47
المحتوى	عنصر نائب لتخزين سمات وقيم إضافية `data-*` .	[{sample1:value1, sample2:value2}]
pageName	عنوان الصفحة حيث يتم تشغيل حدث النقر.	عنوان العينة
معرف الأصل	معرف العنصر الأصل أو اسمه. لمزيد من المعلومات حول كيفية ملء parentId، راجع مفتاح parentId.	navbarContainer

القياسات المخصصة

Name	‏‏الوصف	عينة
timeToAction	الوقت المستغرق بالمللي ثانية للمستخدم للنقر فوق العنصر منذ تحميل الصفحة الأولية.	87407

إضافة المكون الإضافي Click Analytics

يمكن للمستخدمين إعداد المكون الإضافي Click Analytics Auto-Collection عبر JavaScript (Web) SDK Loader Script أو npm ثم إضافة ملحق إطار عمل اختياريا.

إشعار

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

الصق برنامج JavaScript (Web) SDK Loader Script في أعلى كل صفحة تريد تمكين Application Insights لها.

<script type="text/javascript" src="https://js.monitor.azure.com/scripts/b/ext/ai.clck.2.min.js"></script>
<script type="text/javascript">
var clickPluginInstance = new Microsoft.ApplicationInsights.ClickAnalyticsPlugin();
  // Click Analytics configuration
var clickPluginConfig = {
    autoCapture : true,
    dataTags: {
        useDefaultContentNameOrId: true
    }
}
// Application Insights configuration
var configObj = {
    connectionString: "YOUR_CONNECTION_STRING",
    // Alternatively, you can pass in the instrumentation key,
    // but support for instrumentation key ingestion will end on March 31, 2025.
    // instrumentationKey: "YOUR INSTRUMENTATION KEY",
    extensions: [
        clickPluginInstance
    ],
    extensionConfig: {
        [clickPluginInstance.identifier] : clickPluginConfig
    },
};
// Application Insights JavaScript (Web) SDK Loader Script code
!(function (cfg){function e(){cfg.onInit&&cfg.onInit(n)}var x,w,D,t,E,n,C=window,O=document,b=C.location,q="script",I="ingestionendpoint",L="disableExceptionTracking",j="ai.device.";"instrumentationKey"[x="toLowerCase"](),w="crossOrigin",D="POST",t="appInsightsSDK",E=cfg.name||"appInsights",(cfg.name||C[t])&&(C[t]=E),n=C[E]||function(g){var f=!1,m=!1,h={initialize:!0,queue:[],sv:"8",version:2,config:g};function v(e,t){var n={},i="Browser";function a(e){e=""+e;return 1===e.length?"0"+e:e}return n[j+"id"]=i[x](),n[j+"type"]=i,n["ai.operation.name"]=b&&b.pathname||"_unknown_",n["ai.internal.sdkVersion"]="javascript:snippet_"+(h.sv||h.version),{time:(i=new Date).getUTCFullYear()+"-"+a(1+i.getUTCMonth())+"-"+a(i.getUTCDate())+"T"+a(i.getUTCHours())+":"+a(i.getUTCMinutes())+":"+a(i.getUTCSeconds())+"."+(i.getUTCMilliseconds()/1e3).toFixed(3).slice(2,5)+"Z",iKey:e,name:"Microsoft.ApplicationInsights."+e.replace(/-/g,"")+"."+t,sampleRate:100,tags:n,data:{baseData:{ver:2}},ver:undefined,seq:"1",aiDataContract:undefined}}var n,i,t,a,y=-1,T=0,S=["js.monitor.azure.com","js.cdn.applicationinsights.io","js.cdn.monitor.azure.com","js0.cdn.applicationinsights.io","js0.cdn.monitor.azure.com","js2.cdn.applicationinsights.io","js2.cdn.monitor.azure.com","az416426.vo.msecnd.net"],o=g.url||cfg.src,r=function(){return s(o,null)};function s(d,t){if((n=navigator)&&(~(n=(n.userAgent||"").toLowerCase()).indexOf("msie")||~n.indexOf("trident/"))&&~d.indexOf("ai.3")&&(d=d.replace(/(\/)(ai\.3\.)([^\d]*)$/,function(e,t,n){return t+"ai.2"+n})),!1!==cfg.cr)for(var e=0;e<S.length;e++)if(0<d.indexOf(S[e])){y=e;break}var n,i=function(e){var a,t,n,i,o,r,s,c,u,l;h.queue=[],m||(0<=y&&T+1<S.length?(a=(y+T+1)%S.length,p(d.replace(/^(.*\/\/)([\w\.]*)(\/.*)$/,function(e,t,n,i){return t+S[a]+i})),T+=1):(f=m=!0,s=d,!0!==cfg.dle&&(c=(t=function(){var e,t={},n=g.connectionString;if(n)for(var i=n.split(";"),a=0;a<i.length;a++){var o=i[a].split("=");2===o.length&&(t[o[0][x]()]=o[1])}return t[I]||(e=(n=t.endpointsuffix)?t.location:null,t[I]="https://"+(e?e+".":"")+"dc."+(n||"services.visualstudio.com")),t}()).instrumentationkey||g.instrumentationKey||"",t=(t=(t=t[I])&&"/"===t.slice(-1)?t.slice(0,-1):t)?t+"/v2/track":g.endpointUrl,t=g.userOverrideEndpointUrl||t,(n=[]).push((i="SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details)",o=s,u=t,(l=(r=v(c,"Exception")).data).baseType="ExceptionData",l.baseData.exceptions=[{typeName:"SDKLoadFailed",message:i.replace(/\./g,"-"),hasFullStack:!1,stack:i+"\nSnippet failed to load ["+o+"] -- Telemetry is disabled\nHelp Link: https://go.microsoft.com/fwlink/?linkid=2128109\nHost: "+(b&&b.pathname||"_unknown_")+"\nEndpoint: "+u,parsedStack:[]}],r)),n.push((l=s,i=t,(u=(o=v(c,"Message")).data).baseType="MessageData",(r=u.baseData).message='AI (Internal): 99 message:"'+("SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details) ("+l+")").replace(/\"/g,"")+'"',r.properties={endpoint:i},o)),s=n,c=t,JSON&&((u=C.fetch)&&!cfg.useXhr?u(c,{method:D,body:JSON.stringify(s),mode:"cors"}):XMLHttpRequest&&((l=new XMLHttpRequest).open(D,c),l.setRequestHeader("Content-type","application/json"),l.send(JSON.stringify(s)))))))},a=function(e,t){m||setTimeout(function(){!t&&h.core||i()},500),f=!1},p=function(e){var n=O.createElement(q),e=(n.src=e,t&&(n.integrity=t),n.setAttribute("data-ai-name",E),cfg[w]);return!e&&""!==e||"undefined"==n[w]||(n[w]=e),n.onload=a,n.onerror=i,n.onreadystatechange=function(e,t){"loaded"!==n.readyState&&"complete"!==n.readyState||a(0,t)},cfg.ld&&cfg.ld<0?O.getElementsByTagName("head")[0].appendChild(n):setTimeout(function(){O.getElementsByTagName(q)[0].parentNode.appendChild(n)},cfg.ld||0),n};p(d)}cfg.sri&&(n=o.match(/^((http[s]?:\/\/.*\/)\w+(\.\d+){1,5})\.(([\w]+\.){0,2}js)$/))&&6===n.length?(d="".concat(n[1],".integrity.json"),i="@".concat(n[4]),l=window.fetch,t=function(e){if(!e.ext||!e.ext[i]||!e.ext[i].file)throw Error("Error Loading JSON response");var t=e.ext[i].integrity||null;s(o=n[2]+e.ext[i].file,t)},l&&!cfg.useXhr?l(d,{method:"GET",mode:"cors"}).then(function(e){return e.json()["catch"](function(){return{}})}).then(t)["catch"](r):XMLHttpRequest&&((a=new XMLHttpRequest).open("GET",d),a.onreadystatechange=function(){if(a.readyState===XMLHttpRequest.DONE)if(200===a.status)try{t(JSON.parse(a.responseText))}catch(e){r()}else r()},a.send())):o&&r();try{h.cookie=O.cookie}catch(k){}function e(e){for(;e.length;)!function(t){h[t]=function(){var e=arguments;f||h.queue.push(function(){h[t].apply(h,e)})}}(e.pop())}var c,u,l="track",d="TrackPage",p="TrackEvent",l=(e([l+"Event",l+"PageView",l+"Exception",l+"Trace",l+"DependencyData",l+"Metric",l+"PageViewPerformance","start"+d,"stop"+d,"start"+p,"stop"+p,"addTelemetryInitializer","setAuthenticatedUserContext","clearAuthenticatedUserContext","flush"]),h.SeverityLevel={Verbose:0,Information:1,Warning:2,Error:3,Critical:4},(g.extensionConfig||{}).ApplicationInsightsAnalytics||{});return!0!==g[L]&&!0!==l[L]&&(e(["_"+(c="onerror")]),u=C[c],C[c]=function(e,t,n,i,a){var o=u&&u(e,t,n,i,a);return!0!==o&&h["_"+c]({message:e,url:t,lineNumber:n,columnNumber:i,error:a,evt:C.event}),o},g.autoExceptionInstrumented=!0),h}(cfg.cfg),(C[E]=n).queue&&0===n.queue.length?(n.queue.push(e),n.trackPageView({})):e();})({                
  src: "https://js.monitor.azure.com/scripts/b/ai.3.gbl.min.js",
  crossOrigin: "anonymous",
  // sri: false, // Custom optional value to specify whether fetching the snippet from integrity file and do integrity check
  cfg: configObj // configObj is defined above.
});
</script>

لإضافة أو تحديث تكوين برنامج JavaScript (Web) SDK Loader Script، راجع تكوين برنامج JavaScript (Web) SDK Loader Script.

تثبيت حزمة npm :

npm install --save @microsoft/applicationinsights-clickanalytics-js @microsoft/applicationinsights-web


import { ApplicationInsights } from '@microsoft/applicationinsights-web';
import { ClickAnalyticsPlugin } from '@microsoft/applicationinsights-clickanalytics-js';

const clickPluginInstance = new ClickAnalyticsPlugin();
// Click Analytics configuration
const clickPluginConfig = {
  autoCapture: true
};
// Application Insights Configuration
const configObj = {
  connectionString: "YOUR_CONNECTION_STRING", 
  // Alternatively, you can pass in the instrumentation key,
  // but support for instrumentation key ingestion will end on March 31, 2025.  
  // instrumentationKey: "YOUR INSTRUMENTATION KEY",
  extensions: [clickPluginInstance],
  extensionConfig: {
    [clickPluginInstance.identifier]: clickPluginConfig
  },
};

const appInsights = new ApplicationInsights({ config: configObj });
appInsights.loadAppInsights();

تلميح

إذا كنت ترغب في إضافة ملحق إطار عمل أو قمت بالفعل بإضافة ملحق، فشاهد نماذج React وReact Native وAngular code لمعرفة كيفية إضافة المكون الإضافي Click Analytics.

(اختياري) تعيين سياق المستخدم المصادق عليه

إذا كنت تريد تعيين هذا الإعداد الاختياري، فشاهد تعيين سياق المستخدم المصادق عليه.

إذا كنت تستخدم مصنف HEART مع المكون الإضافي Click Analytics، فلن تحتاج إلى تعيين سياق المستخدم المصادق عليه لمشاهدة بيانات تتبع الاستخدام. لمزيد من المعلومات، راجع وثائق مصنف HEART.

استخدام المكون الإضافي

تصف الأقسام التالية كيفية استخدام المكون الإضافي.

تخزين بيانات تتبع الاستخدام

يتم تخزين بيانات تتبع الاستخدام التي تم إنشاؤها من أحداث النقر كما هو الحال customEvents في قسم Application Insights > Logs في مدخل Microsoft Azure>.

`name`

name يتم ملء عمود استنادا customEvent إلى القواعد التالية:

إذا customDataPrefix لم يتم الإعلان عنه في التكوين المتقدم، id يتم استخدام المتوفر في data-id كاسم customEvent .
إذا customDataPrefix تم الإعلان، id يتم استخدام المقدم في data-*-id، مما يعني أنه يجب أن يبدأ ب data وينتهي ب id، كاسم customEvent . على سبيل المثال، إذا كان عنصر HTML الذي تم النقر فوقه يحتوي على السمة "data-sample-id"="button1"، فهذا "button1" هو customEvent الاسم.
إذا لم تكن السمة أو موجودة وإذا useDefaultContentNameOrId تم تعيينها إلى true، يتم استخدام سمة id HTML للعنصر الذي تم النقر فوقه أو اسم محتوى العنصر كاسمcustomEvent.data-*-id data-id إذا كان كل من id واسم المحتوى موجودين، يتم إعطاء الأسبقية إلى id.
إذا كان useDefaultContentNameOrId هو ، فإن customEvent الاسم هو "not_specified"false. نوصي بتعيين useDefaultContentNameOrId إلى true لإنشاء بيانات ذات معنى.

`contentName`

إذا كانت لديك دالة contentName رد الاتصال في التكوين المتقدم المعرفة، contentName يتم ملء عمود customEvent استنادا إلى القواعد التالية:

بالنسبة لعنصر HTML <a> الذي تم النقر فوقه، يحاول المكون الإضافي جمع قيمة سمة innerText (النص) الخاصة به. إذا لم يتمكن المكون الإضافي من العثور على هذه السمة، فإنه يحاول جمع قيمة سمةhtml الداخلية الخاصة به.
بالنسبة لعنصر HTML <img> أو <area> عنصر تم النقر فوقه، يجمع المكون الإضافي قيمة السمة الخاصة به alt .
بالنسبة لكافة عناصر HTML الأخرى التي تم النقر فوقها، contentName يتم ملؤها استنادا إلى القواعد التالية، والتي يتم سردها بترتيب الأسبقية:
1. قيمة السمة value للعنصر
2. قيمة السمة name للعنصر
3. قيمة السمة alt للعنصر
4. قيمة سمة innerText للعنصر
5. قيمة السمة id للعنصر

`parentId` مفتاح

لملء parentId المفتاح داخل customEvent customDimensions الجدول في السجلات، قم بتعريف العلامة parentDataTag أو تعريف السمةdata-parentid.

يتم إحضار قيمة استنادا parentId إلى القواعد التالية:

عند تعريف parentDataTag، يجلب المكون الإضافي قيمة id أو data-*-id المعرفة داخل العنصر الأقرب إلى العنصر الذي تم النقر فوقه ك parentId.
إذا تم تعريف كل من data-*-id و id ، يتم إعطاء الأسبقية إلى data-*-id.
إذا parentDataTag تم تعريفه ولكن لم يتمكن المكون الإضافي من العثور على هذه العلامة ضمن شجرة DOM، فإن المكون الإضافي يستخدم id أو data-*-id المحدد داخل العنصر الأقرب إلى العنصر الذي تم النقر فوقه ك parentId. ومع ذلك، نوصي بتعريف السمة data-{parentDataTag} أو customDataPrefix-{parentDataTag} لتقليل عدد الحلقات المطلوبة للعثور على parentId. يعد الإعلان parentDataTag مفيدا عندما تحتاج إلى استخدام المكون الإضافي مع خيارات مخصصة.
إذا لم يتم تعريف أي parentDataTag معلومات ولم يتم تضمينها parentId في العنصر الحالي، فلن يتم جمع أي parentId قيمة.
إذا parentDataTag تم تعريف ، useDefaultContentNameOrId يتم تعيين إلى false، ويتم تعريف سمة id فقط داخل العنصر الأقرب إلى العنصر الذي تم النقر عليه، يتم parentId ملء ك "not_specified". لإحضار قيمة id، قم بتعيين useDefaultContentNameOrId إلى true.

عند تعريف السمة data-parentid أو data-*-parentid ، يجلب المكون الإضافي مثيل هذه السمة الأقرب إلى العنصر الذي تم النقر فوقه، بما في ذلك داخل العنصر الذي تم النقر فوقه إذا كان ذلك ممكنا.

إذا قمت بتعريف parentDataTag السمة data-parentid أو data-*-parentid وتعريفها، يتم إعطاء الأسبقية إلى data-parentid أو data-*-parentid.

إذا ظهر تحذير بيانات تتبع الاستخدام "انقر فوق صفوف الأحداث بدون قيمة parentId"، فشاهد إصلاح التحذير "انقر فوق صفوف الأحداث بدون قيمة parentId".

للحصول على أمثلة توضح القيمة التي يتم إحضارها ك parentId لتكوينات مختلفة، راجع أمثلة على parentid المفتاح.

تنبيه

بمجرد parentDataTag تضمينه في أي عنصر HTML عبر التطبيق الخاص بك، تبدأ SDK في البحث عن علامات الوالدين عبر التطبيق بأكمله وليس فقط عنصر HTML حيث استخدمته.
إذا كنت تستخدم مصنف HEART مع المكون الإضافي Click Analytics، لتسجيل أحداث HEART أو اكتشافها، يجب الإعلان عن العلامة parentDataTag في جميع الأجزاء الأخرى من تطبيق المستخدم النهائي.

`customDataPrefix`

customDataPrefix يوفر الخيار في التكوين المتقدم للمستخدم القدرة على تكوين بادئة سمة بيانات للمساعدة في تحديد مكان وجود القلب داخل قاعدة التعليمات البرمجية للفرد. يجب أن تكون البادئة دائما صغيرة وتبدأ ب data-. على سبيل المثال:

data-heart-
data-team-name-
data-example-

في HTML، data-* تسمى السمات العمومية سمات البيانات المخصصة التي تسمح بتبادل المعلومات الخاصة بين HTML وتمثيل DOM الخاص به بواسطة البرامج النصية. المتصفحات القديمة مثل سمات إسقاط Internet Explorer وSafari التي لا يفهمونها، ما لم تبدأ ب data-.

يمكنك استبدال العلامة النجمية (*) في data-* بأي اسم يتبع قاعدة الإنتاج لأسماء XML بالقيود التالية.

يجب ألا يبدأ الاسم ب "xml"، مهما كانت الحالة المستخدمة للأحرف.
يجب ألا يحتوي الاسم على فاصلة منقوطة (U+003A).
ينبغي ألا يحتوي الاسم على أحرف كبيرة.

إضافة تكوين متقدم

Name	نوع	Default	‏‏الوصف
autoCapture	Boolean	صواب	تكوين الالتقاط التلقائي.
أتصل مرة أخرى	IValueCallback	قيمة فارغة	تكوين عمليات رد الاتصال.
pageTags	‏‏الكائن	قيمة فارغة	علامات الصفحة.
dataTags	ICustomDataTags	قيمة فارغة	توفير علامات البيانات المخصصة لتجاوز العلامات الافتراضية المستخدمة لالتقاط بيانات النقرات.
urlCollectHash	Boolean	خطأ	تمكين تسجيل القيم بعد الحرف "#" لعنوان URL.
urlCollectQuery	Boolean	خطأ	تمكين تسجيل سلسلة الاستعلام الخاصة بعنوان URL.
behaviorValidator	الدالة	قيمة فارغة	دالة رد الاتصال لاستخدامها للتحقق من صحة القيمة `data-*-bhvr`. لمزيد من المعلومات، راجع قسم behaviorValidator.
defaultRightClickBhvr	السلسلة (أو) الـرقم	''	قيمة السلوك الافتراضية عند حدوث حدث النقر بزر الماوس الأيمن. يتم تجاوز هذه القيمة إذا كان العنصر يحتوي على السمة `data-*-bhvr` .
dropInvalidEvents	Boolean	خطأ	وضع علامة لإسقاط الأحداث التي لا تحتوي على بيانات نقر مفيدة.

IValueCallback

Name	نوع	Default	‏‏الوصف
pageName	الدالة	قيمة فارغة	دالة لتجاوز سلوك الالتقاط الافتراضي `pageName` .
pageActionPageTags	الدالة	قيمة فارغة	دالة رد اتصال لزيادة الإعداد الافتراضي `pageTags` الذي تم جمعه أثناء `pageAction` الحدث.
contentName	الدالة	قيمة فارغة	دالة رد اتصال لملء مخصصة `contentName`.

ICustomDataTags

Name	نوع	الإعداد الافتراضي	العلامة الافتراضية لاستخدامها في HTML	‏‏الوصف
useDefaultContentNameOrId	Boolean	خطأ	‏‫غير متوفر‬	إذا `true`، يجمع سمة `id` HTML القياسية عندما `contentName` لا يتم وضع علامة على عنصر معين ببادئة البيانات الافتراضية أو `customDataPrefix`. وإلا، لا يتم جمع سمة `id` HTML القياسية ل `contentName` .
customDataPrefix	السلسلة‬	`data-`	`data-*`	اسم محتوى الالتقاط التلقائي وقيمة العناصر التي تم تمييزها بالبادئة المتوفرة. على سبيل المثال، `data-*-id` و`data-<yourcustomattribute>` يمكن استخدامها في علامات HTML.
aiBlobAttributeTag	السلسلة‬	`ai-blob`	`data-ai-blob`	يدعم المكون الإضافي سمة كائن ثنائي كبير الحجم JSON بدلا من السمات الفردية `data-*` .
metaDataPrefix	السلسلة‬	قيمة فارغة	‏‫غير متوفر‬	الالتقاط التلقائي لاسم عنصر التعريف ل HTML Head والمحتوى مع البادئة المتوفرة عند التقاطها. على سبيل المثال، يمكن استخدام `custom-` في علامات HTML.
captureAllMetaDataContent	Boolean	خطأ	‏‫غير متوفر‬	الالتقاط التلقائي لجميع أسماء العناصر الوصفية الخاصة بـ HTML Head ومحتوياتها. الافتراضي خطأ. إذا تم تمكينه، فإنه يتجاوز المقدمة `metaDataPrefix`.
parentDataTag	السلسلة‬	قيمة فارغة	‏‫غير متوفر‬	`parentId` إحضار في السجلات عند `data-parentid` مواجهة أو `data-*-parentid` عدم مواجهتها. للكفاءة، يتوقف عن اجتياز DOM لالتقاط اسم المحتوى وقيمة العناصر عند `data-{parentDataTag}` مواجهة أو `customDataPrefix-{parentDataTag}` سمة. لمزيد من المعلومات، راجع مفتاح parentId.
dntDataTag	السلسلة‬	`ai-dnt`	`data-ai-dnt`	يتجاهل المكون الإضافي لالتقاط بيانات تتبع الاستخدام عناصر HTML بهذه السمة.

behaviorValidator

behaviorValidator تتحقق الدالات تلقائيا من أن السلوكيات ذات العلامات في التعليمات البرمجية تتوافق مع قائمة معرفة مسبقا. تضمن الوظائف أن السلوكيات ذات العلامات متسقة مع التصنيف الذي تم إنشاؤه في مؤسستك. ليس مطلوبا أو متوقعا أن يستخدم معظم عملاء Azure Monitor هذه الوظائف، ولكنها متوفرة للسيناريوهات المتقدمة. يمكن أن تساعد دوال behaviorValidator في الممارسات التي يمكن الوصول إليها بشكل أكبر.

تظهر السلوكيات في حقل customDimensions داخل جدول CustomEvents.

دالات رد الاتصال

يتم عرض ثلاث دالات مختلفة behaviorValidator لرد الاتصال كجزء من هذا الملحق. يمكنك أيضا استخدام وظائف رد الاتصال الخاصة بك إذا لم تحل الوظائف المكشوفة متطلباتك. الهدف هو إحضار بنية بيانات سلوكك. يستخدم المكون الإضافي دالة المدقق هذه أثناء استخراج السلوكيات من علامات البيانات.

Name	‏‏الوصف
BehaviorValueValidator	استخدم دالة رد الاتصال هذه إذا كانت بنية بيانات السلوك عبارة عن صفيف من السلاسل.
BehaviorMapValidator	استخدم دالة رد الاتصال هذه إذا كانت بنية بيانات السلوك عبارة عن قاموس.
BehaviorEnumValidator	استخدم دالة رد الاتصال هذه إذا كانت بنية بيانات السلوك عبارة عن قائمة تعداد.

تمرير قيم السلسلة مقابل القيم الرقمية

لتقليل وحدات البايت التي تمررها، مرر القيمة الرقمية بدلا من السلسلة النصية الكاملة. إذا لم تكن التكلفة مشكلة، يمكنك تمرير السلسلة النصية الكاملة (على سبيل المثال، NAVIGATIONBACK).

نموذج الاستخدام مع behaviorValidator

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

var clickPlugin = Microsoft.ApplicationInsights.ClickAnalyticsPlugin;
var clickPluginInstance = new clickPlugin();

// Behavior enum values
var behaviorMap = {
  UNDEFINED: 0, // default, Undefined

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Page Experience [1-19]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  NAVIGATIONBACK: 1, // Advancing to the previous index position within a webpage
  NAVIGATION: 2, // Advancing to a specific index position within a webpage
  NAVIGATIONFORWARD: 3, // Advancing to the next index position within a webpage
  APPLY: 4, // Applying filter(s) or making selections
  REMOVE: 5, // Applying filter(s) or removing selections
  SORT: 6, // Sorting content
  EXPAND: 7, // Expanding content or content container
  REDUCE: 8, // Sorting content
  CONTEXTMENU: 9, // Context menu
  TAB: 10, // Tab control
  COPY: 11, // Copy the contents of a page
  EXPERIMENTATION: 12, // Used to identify a third-party experimentation event
  PRINT: 13, // User printed page
  SHOW: 14, // Displaying an overlay
  HIDE: 15, // Hiding an overlay
  MAXIMIZE: 16, // Maximizing an overlay
  MINIMIZE: 17, // Minimizing an overlay
  BACKBUTTON: 18, // Clicking the back button

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Scenario Process [20-39]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  STARTPROCESS: 20, // Initiate a web process unique to adopter
  PROCESSCHECKPOINT: 21, // Represents a checkpoint in a web process unique to adopter
  COMPLETEPROCESS: 22, // Page Actions that complete a web process unique to adopter
  SCENARIOCANCEL: 23, // Actions resulting from cancelling a process/scenario

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Download [40-59]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  DOWNLOADCOMMIT: 40, // Initiating an unmeasurable off-network download
  DOWNLOAD: 41, // Initiating a download

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Search [60-79]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  SEARCHAUTOCOMPLETE: 60, // Auto-completing a search query during user input
  SEARCH: 61, // Submitting a search query
  SEARCHINITIATE: 62, // Initiating a search query
  TEXTBOXINPUT: 63, // Typing or entering text in the text box

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Commerce [80-99]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  VIEWCART: 82, // Viewing the cart
  ADDWISHLIST: 83, // Adding a physical or digital good or services to a wishlist
  FINDSTORE: 84, // Finding a physical store
  CHECKOUT: 85, // Before you fill in credit card info
  REMOVEFROMCART: 86, // Remove an item from the cart
  PURCHASECOMPLETE: 87, // Used to track the pageView event that happens when the CongratsPage or Thank You page loads after a successful purchase
  VIEWCHECKOUTPAGE: 88, // View the checkout page
  VIEWCARTPAGE: 89, // View the cart page
  VIEWPDP: 90, // View a PDP
  UPDATEITEMQUANTITY: 91, // Update an item's quantity
  INTENTTOBUY: 92, // User has the intent to buy an item
  PUSHTOINSTALL: 93, // User has selected the push to install option

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Authentication [100-119]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  SIGNIN: 100, // User sign-in
  SIGNOUT: 101, // User sign-out

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Social [120-139]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  SOCIALSHARE: 120, // "Sharing" content for a specific social channel
  SOCIALLIKE: 121, // "Liking" content for a specific social channel
  SOCIALREPLY: 122, // "Replying" content for a specific social channel
  CALL: 123, // Click on a "call" link
  EMAIL: 124, // Click on an "email" link
  COMMUNITY: 125, // Click on a "community" link

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Feedback [140-159]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  VOTE: 140, // Rating content or voting for content
  SURVEYCHECKPOINT: 145, // Reaching the survey page/form

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Registration, Contact [160-179]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  REGISTRATIONINITIATE: 161, // Initiating a registration process
  REGISTRATIONCOMPLETE: 162, // Completing a registration process
  CANCELSUBSCRIPTION: 163, // Canceling a subscription
  RENEWSUBSCRIPTION: 164, // Renewing a subscription
  CHANGESUBSCRIPTION: 165, // Changing a subscription
  REGISTRATIONCHECKPOINT: 166, // Reaching the registration page/form

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Chat [180-199]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  CHATINITIATE: 180, // Initiating a chat experience
  CHATEND: 181, // Ending a chat experience

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Trial [200-209]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  TRIALSIGNUP: 200, // Signing up for a trial
  TRIALINITIATE: 201, // Initiating a trial

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Signup [210-219]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  SIGNUP: 210, // Signing up for a notification or service
  FREESIGNUP: 211, // Signing up for a free service

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Referrals [220-229]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  PARTNERREFERRAL: 220, // Navigating to a partner's web property

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Intents [230-239]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  LEARNLOWFUNNEL: 230, // Engaging in learning behavior on a commerce page (for example, "Learn more click")
  LEARNHIGHFUNNEL: 231, // Engaging in learning behavior on a non-commerce page (for example, "Learn more click")
  SHOPPINGINTENT: 232, // Shopping behavior prior to landing on a commerce page

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Video [240-259]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  VIDEOSTART: 240, // Initiating a video
  VIDEOPAUSE: 241, // Pausing a video
  VIDEOCONTINUE: 242, // Pausing or resuming a video
  VIDEOCHECKPOINT: 243, // Capturing predetermined video percentage complete
  VIDEOJUMP: 244, // Jumping to a new video location
  VIDEOCOMPLETE: 245, // Completing a video (or % proxy)
  VIDEOBUFFERING: 246, // Capturing a video buffer event
  VIDEOERROR: 247, // Capturing a video error
  VIDEOMUTE: 248, // Muting a video
  VIDEOUNMUTE: 249, // Unmuting a video
  VIDEOFULLSCREEN: 250, // Making a video full screen
  VIDEOUNFULLSCREEN: 251, // Making a video return from full screen to original size
  VIDEOREPLAY: 252, // Making a video replay
  VIDEOPLAYERLOAD: 253, // Loading the video player
  VIDEOPLAYERCLICK: 254, // Click on a button within the interactive player
  VIDEOVOLUMECONTROL: 255, // Click on video volume control
  VIDEOAUDIOTRACKCONTROL: 256, // Click on audio control within a video
  VIDEOCLOSEDCAPTIONCONTROL: 257, // Click on the closed-caption control
  VIDEOCLOSEDCAPTIONSTYLE: 258, // Click to change closed-caption style
  VIDEORESOLUTIONCONTROL: 259, // Click to change resolution

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // 	Advertisement Engagement [280-299]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  ADBUFFERING: 283, // Ad is buffering
  ADERROR: 284, // Ad error
  ADSTART: 285, // Ad start
  ADCOMPLETE: 286, // Ad complete
  ADSKIP: 287, // Ad skipped
  ADTIMEOUT: 288, // Ad timed out
  OTHER: 300 // Other
};

// Application Insights Configuration
var configObj = {
  connectionString: "YOUR_CONNECTION_STRING", 
  // Alternatively, you can pass in the instrumentation key,
  // but support for instrumentation key ingestion will end on March 31, 2025. 
  // instrumentationKey: "YOUR INSTRUMENTATION KEY",
  extensions: [clickPluginInstance],
  extensionConfig: {
    [clickPluginInstance.identifier]: {
      behaviorValidator: Microsoft.ApplicationInsights.BehaviorMapValidator(behaviorMap),
      defaultRightClickBhvr: 9
    },
  },
};
var appInsights = new Microsoft.ApplicationInsights.ApplicationInsights({
  config: configObj
});
appInsights.loadAppInsights();

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

راجع تطبيق ويب بسيطا مع تمكين المكون الإضافي للتحليل التلقائي ل Click Analytics لمعرفة كيفية تنفيذ خصائص الحدث المخصصة مثل Name parentid والسلوك والمحتوى المخصصين. راجع نموذج التطبيق readme للحصول على معلومات حول مكان العثور على بيانات النقر.

أمثلة على `parentId` المفتاح

توضح الأمثلة التالية القيمة التي يتم إحضارها ك parentId لتكوينات مختلفة.

توضح الأمثلة كيف إذا تم parentDataTag تعريفه ولكن المكون الإضافي لا يمكنه العثور على هذه العلامة ضمن شجرة DOM، يستخدم id المكون الإضافي العنصر الأصل الأقرب إليه.

المثال 1

في المثال 1، لم يتم الإعلان عن parentDataTag أو data-parentid data-*-parentid لم يتم تعريفه في أي عنصر. يوضح هذا المثال تكوينا حيث لا يتم جمع قيمة ل parentId .

export const clickPluginConfigWithUseDefaultContentNameOrId = {
  dataTags : {
    customDataPrefix: "",
    parentDataTag: "",
    dntDataTag: "ai-dnt",
    captureAllMetaDataContent:false,
    useDefaultContentNameOrId: true,
    autoCapture: true
  },
}; 

<div className="test1" data-id="test1parent">
  <div>Test1</div>
  <div>with id, data-id, parent data-id defined</div>
  <Button id="id1" data-id="test1id" variant="info" onClick={trackEvent}>Test1</Button>
</div>

بالنسبة للعنصر <Button> الذي تم النقر فوقه، تكون قيمة parentId هي “not_specified”، لأنه لا يتم تعريف أي parentDataTag تفاصيل ولا يتم توفير معرف عنصر أصل داخل العنصر الحالي.

المثال 2

في المثال 2، parentDataTag يتم تعريف و data-parentid . يوضح هذا المثال كيفية تجميع تفاصيل المعرف الأصل.

export const clickPluginConfigWithParentDataTag = {
  dataTags : {
    customDataPrefix: "",
    parentDataTag: "group",
    ntDataTag: "ai-dnt",
    captureAllMetaDataContent:false,
    useDefaultContentNameOrId: false,
    autoCapture: true
  },
};

<div className="test2" data-group="buttongroup1" data-id="test2parent">
  <div>Test2</div>
  <div>with data-id, parentid, parent data-id defined</div>
  <Button data-id="test2id" data-parentid = "parentid2" variant="info" onClick={trackEvent}>Test2</Button>
</div>

بالنسبة للعنصر <Button>الذي تم النقر فوقه، تكون قيمة parentId هي parentid2. على الرغم من parentDataTag الإعلان، data-parentid يتم تعريف مباشرة داخل العنصر . لذلك، هذه القيمة لها الأسبقية على جميع المعرفات الأصلية الأخرى أو تفاصيل المعرف المحددة في عناصرها الأصلية.

المثال 3

في المثال 3، parentDataTag يتم الإعلان عنه ولم يتم تعريف السمة data-parentid أو data-*-parentid . يوضح هذا المثال كيف يمكن أن يكون الإعلان parentDataTag مفيدا لجمع قيمة للحالات parentId التي لا تحتوي فيها العناصر الديناميكية على id أو data-*-id.

export const clickPluginConfigWithParentDataTag = {
  dataTags : {
    customDataPrefix: "",
    parentDataTag: "group",
    dntDataTag: "ai-dnt",
    captureAllMetaDataContent:false,
    useDefaultContentNameOrId: false,
    autoCapture: true
  },
};

<div className="test6" data-group="buttongroup1" data-id="test6grandparent">
  <div>Test6</div>
  <div>with data-id, grandparent data-group defined, parent data-id defined</div>
  <div data-id="test6parent">
    <Button data-id="test6id" variant="info" onClick={trackEvent}>Test6</Button>
  </div>
</div>

بالنسبة للعنصر <Button>الذي تم النقر فوقه، فإن قيمة parentId هي test6parent، لأنه parentDataTag تم تعريفها. يسمح هذا الإعلان للمكون الإضافي باجتياز شجرة العنصر الحالية، وبالتالي سيتم استخدام معرف أقرب أصل له عندما لا يتم توفير تفاصيل المعرف الأصل مباشرة داخل العنصر الحالي. data-group="buttongroup1" مع المعرفة، يجد parentId المكون الإضافي أكثر كفاءة.

إذا قمت بإزالة السمة data-group="buttongroup1" ، فإن قيمة parentId لا تزال test6parent، لأنه parentDataTag لا يزال معلنا.

استكشاف الأخطاء وإصلاحها

راجع «dedicated troubleshooting article».

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

تأكد من تدفق البيانات.
راجع الوثائق المتعلقة باستخدام مصنف HEART لتحليلات المنتجات الموسعة.
راجع مستودع GitHub وحزمة npm ل Click Analytics Autocollection Plug-in.
استخدم Events Analysis في تجربة الاستخدام لتحليل النقرات العلوية والشرائح حسب الأبعاد المتوفرة.
راجع Log Analytics إذا لم تكن على دراية بعملية كتابة استعلام.
إنشاء مصنف أو تصديره إلى Power BI لإنشاء مرئيات مخصصة لبيانات النقر.

مشاركة عبر

تمكين المكون الإضافي Click Analytics Auto-Collection

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

ما هي البيانات التي يجمعها المكون الإضافي؟

خصائص الحدث المخصصة

الأبعاد المخصصة

القياسات المخصصة

إضافة المكون الإضافي Click Analytics

أضف التعليمات البرمجية

(اختياري) تعيين سياق المستخدم المصادق عليه

استخدام المكون الإضافي

تخزين بيانات تتبع الاستخدام

`name`

`contentName`

`parentId` مفتاح

`customDataPrefix`

إضافة تكوين متقدم

IValueCallback

ICustomDataTags

behaviorValidator

دالات رد الاتصال

تمرير قيم السلسلة مقابل القيم الرقمية

نموذج الاستخدام مع behaviorValidator

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

أمثلة على `parentId` المفتاح

المثال 1

المثال 2

المثال 3

استكشاف الأخطاء وإصلاحها

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

الملاحظات

الموارد الإضافية

مشاركة عبر

تمكين المكون الإضافي Click Analytics Auto-Collection

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

ما هي البيانات التي يجمعها المكون الإضافي؟

خصائص الحدث المخصصة

الأبعاد المخصصة

القياسات المخصصة

إضافة المكون الإضافي Click Analytics

أضف التعليمات البرمجية

(اختياري) تعيين سياق المستخدم المصادق عليه

استخدام المكون الإضافي

تخزين بيانات تتبع الاستخدام

name

contentName

parentId مفتاح

customDataPrefix

إضافة تكوين متقدم

IValueCallback

ICustomDataTags

behaviorValidator

دالات رد الاتصال

تمرير قيم السلسلة مقابل القيم الرقمية

نموذج الاستخدام مع behaviorValidator

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

أمثلة على parentId المفتاح

المثال 1

المثال 2

المثال 3

استكشاف الأخطاء وإصلاحها

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

الملاحظات

الموارد الإضافية

`name`

`contentName`

`parentId` مفتاح

`customDataPrefix`

أمثلة على `parentId` المفتاح