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

المكوّنات الإضافية هي نصوص برمجية تُحسِّن وظائف analytics.js للمساعدة في قياس تفاعل المستخدِم. ترتبط المكوّنات الإضافية عادةً بمجموعة من الميزات التي قد لا يطلبها جميع مستخدمي "إحصاءات Google"، مثل ecommerce أو القياس على جميع النطاقات، وبالتالي لا يتم تضمينها في analytics.js تلقائيًا.

يشرح هذا الدليل كيفية طلب مكوّنات analytics.js الإضافية واستخدامها.

طلب المكوّنات الإضافية

يأخذ الأمر require اسم المكوِّن الإضافي ويسجّله لاستخدامه مع قائمة انتظار الأوامر ga(). إذا قبل المكوّن الإضافي خيارات الضبط، يمكن تمرير هذه الخيارات كوسيطة أخيرة إلى الأمر require.

في ما يلي التوقيع الكامل لأمر require:

ga('[trackerName.]require', pluginName, [pluginOptions]);

على سبيل المثال، إليك كيفية طلب استخدام المكوّن الإضافي التجارة الإلكترونية المحسَّنة مع أداة التتبُّع التلقائية:

ga('require', 'ec');

في ما يلي خطوات طلب المكوّن الإضافي الميزات الإعلانية لجهاز تتبُّع يحمل اسم "myTracker" وتمرير خيار إعداد يلغي قيمة اسم ملف تعريف الارتباط التلقائية:

ga('myTracker.require', 'displayfeatures', {
  cookieName: 'display_features_cookie'
});

تحميل رمز المكون الإضافي

يؤدي الأمر require إلى تهيئة طرق المكون الإضافي للاستخدام مع قائمة انتظار الأوامر ga()، ولكنه لا يحمِّل النص البرمجي للمكوّن الإضافي نفسه. إذا كنت تستخدم مكوّنًا إضافيًا تابعًا لجهة خارجية أو كتابة مكوّن إضافي بنفسك، فستحتاج إلى إضافة رمز المكوّن الإضافي يدويًا إلى الصفحة.

والطريقة المقترَحة لإضافة رمز المكوّن الإضافي إلى الصفحة هي من خلال استخدام علامة <script> مع ضبط السمة async لضمان عدم حظر تحميل الميزات الأخرى على موقعك الإلكتروني.

يتطلب الرمز التالي مكوّنًا إضافيًا لتتبّع الرابط الافتراضي ويحمّله:

<script>
ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'linkTracker');
ga('send', 'pageview');
</script>

<!--Note: plugin scripts must be included after the tracking snippet. -->
<script async src="/path/to/link-tracker-plugin.js"></script>

ملاحظة: يتم تحميل مكوّنات "إحصاءات Google" الإضافية الرسمية لبرنامج analytics.js تلقائيًا عندما تكون مطلوبة، ولا تحتاج إلى إضافة علامات نصوص برمجية لها. يمكن العثور على القائمة الكاملة لمكوّنات analytics.js الإضافية الرسمية ضمن قسم المكوّنات الإضافية الرسمية في شريط التنقّل الأيمن.

في انتظار تحميل المكوّنات الإضافية

نظرًا لتحميل كلّ من مكتبة analytics.js ومكوّنات analytics.js الإضافية بشكلٍ غير متزامن، قد يصعُب معرفة وقت تحميل المكوّنات الإضافية بالكامل وعندما تكون جاهزة للاستخدام.

تحل مكتبة analytics.js هذه المشكلة عن طريق إيقاف تنفيذ قائمة انتظار الأوامر عندما تواجه أمر require لمكوّن إضافي لم يتم تحميله بعد. بعد تحميل المكوّن الإضافي، تستمر عملية تنفيذ قائمة الانتظار كالمعتاد.

نتيجة لذلك، من المهم للغاية أن تختبر المكوّنات الإضافية التي تستخدمها للتأكد من تحميلها وتشغيلها بشكل صحيح. إذا تعذّر تحميل أحد المكوّنات الإضافية أو كان به خطأ، سيمنع تنفيذ جميع أوامر analytics.js اللاحقة.

طرق مكوّنات إضافية للاتصال

بعد طلب مكوّن إضافي، تصبح هذه الطرق متاحة للاستخدام مع قائمة انتظار الأوامر ga(). إليك توقيع الأوامر لاستدعاء طرق المكون الإضافي:

ga('[trackerName.][pluginName:]methodName', ...args);

على سبيل المثال، يمكن استدعاء طريقة addProduct للمكوّن الإضافي التجارة الإلكترونية المحسَّنة على النحو التالي:

ga('ec:addProduct', {
  'id': 'P12345',
  'quantity': 1
});

أو على جهاز تتبُّع معيّن من خلال إضافة اسم جهاز التتبُّع إلى سلسلة الأوامر:

ga('myTracker.ec:addProduct', {
  'id': 'P12345',
  'quantity': 1
});

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

إذا كنت قد قرأت جميع الأدلة في هذا القسم، من المفترض أن تكون على دراية بمعظم ميزات analytics.js. يوضّح الدليل التالي كيفية تصحيح أخطاء عمليات تنفيذ مقتطف analytics.js لاكتشاف الأخطاء بسهولة أكبر ومعرفة ما يفعله الرمز بالضبط.