المهام

يصف هذا الدليل المهام، وهي ميزة متقدّمة تُستخدم لتخصيص كيفية تحقّق analytics.js من صحة طلبات Measurement Protocol وإنشائها وإرسالها.

نظرة عامة

في كل مرة يتم فيها استدعاء الأمر send، ينفِّذ analytics.js سلسلة من المهام للتحقّق من صحة طلب Measurement Protocol وإنشائه وإرساله من متصفّح المستخدم إلى "إحصاءات Google". يصف الجدول التالي كل مهمة من هذه المهام، بالترتيب الذي يتم تنفيذها به:

اسم المهمة	الوصف
customTask	بشكل افتراضي، لا تفعل هذه المهمة أي شيء. يمكنك تجاوزها لتوفير سلوك مخصّص.
previewTask	يؤدي هذا الخيار إلى إلغاء الطلب إذا كان يتم عرض الصفحة فقط لإنشاء صورة مصغّرة "أهم المواقع الإلكترونية" في متصفّح Safari.
checkProtocolTask	يلغي الطلب إذا لم يكن بروتوكول الصفحة http أو https.
validationTask	يلغي الطلب إذا كانت الحقول المطلوبة غير متوفّرة أو غير صالحة.
checkStorageTask	يتم إلغاء الطلب في حال إعداد أداة التتبُّع لاستخدام ملفات تعريف الارتباط ولكن تم إيقاف ملفات تعريف الارتباط في متصفّح المستخدم.
historyImportTask	يتم استيراد المعلومات من ملفات تعريف الارتباط ga.js وurchin.js للاحتفاظ بسجلّ الزوّار عند نقل الموقع الإلكتروني إلى Universal Analytics.
samplerTask	يتم أخذ عينات من الزوّار استنادًا إلى إعدادات sampleRate في جهاز التتبُّع هذا.
buildHitTask	تنشئ سلسلة طلب Measurement Protocol وتخزنها في الحقل hitPayload.
sendHitTask	تُرسِل طلب Measurement Protocol المخزَّن في الحقل hitPayload إلى خوادم "إحصاءات Google".
timingTask	يتم تلقائيًا إنشاء نتيجة توقيت سرعة الموقع الإلكتروني استنادًا إلى إعدادات siteSpeedSampleRate في جهاز التتبُّع هذا.
displayFeaturesTask	يرسل نتيجة إضافية في حال تفعيل ميزات الشبكة الإعلانية ولم يتم إرسال نتيجة سابقة خلال فترة المهلة التي حدّدها ملف تعريف الارتباط لميزات الإعلانات (_gat).

يتم تنفيذ كل مهمة من هذه المهام كدالة JavaScript تأخذ معلَمة نموذج واحدة كإدخال. النموذج هو كائن بسيط يوفر إمكانية الوصول إلى أيٍّ من الحقول المحدّدة في مرجع حقل Analytics.js.

يمكن الوصول إلى "مهام Google" أو استبدالها باستخدام طريقة التتبُّع العادية get وset. باستخدام هذه الطرق، يمكنك استبدال المهام بدوالّك المخصّصة، أو زيادة الوظائف الحالية عن طريق سلسلة الدوال المخصّصة لتنفيذها قبل مهمة حالية أو بعدها.

التنفيذ

يوضِّح هذا القسم كيفية إضافة وظائف جديدة إلى المهام الحالية، أو استبدال دوال المهام المضمَّنة برمزك المخصَّص، أو إيقاف وظيفة مهمة بالكامل.

تجاوز مهمة

لإلغاء مهمة، يمكنك set قيمتها إلى دالة تؤدي إجراءً مختلفًا. من الأسباب الشائعة لإلغاء المهام اختبار الوظائف عند اختبار عمليات تنفيذ مقتطف analytics.js.

يستبدل الرمز التالي sendHitTask بدالة تُسجل حمولة النتيجة في وحدة التحكم:

ga('create', 'UA-XXXXX-Y', 'auto');
ga('set', 'sendHitTask', function(model) {
  console.log(model.get('hitPayload'));
});

ملاحظة: تستخدم مكتبة التتبّع التلقائي هذا الأسلوب عند اختبار مكوّناته الإضافية. على سبيل المثال، يلغي اختبار eventTracker sendHitTask من خلال رمز يتحقّق من إعداد حقول الأحداث الصحيحة.

الإضافة إلى مهمة

لإدراج وظيفة جديدة، يمكنك ربط دالة المهمة المخصّصة لتنفيذها قبل مهمة حالية أو بعدها. في المثال التالي، يتم استبدال sendHitTask بوظيفة مهام مخصّصة تستدعي أولاً دالة sendHitTask الأصلية لإرسال إشارة الطلب العادية إلى google-analytics.com/collection، ثم تنفيذ رمز مخصّص لإرسال نسخة من طلب Measurement Protocol إلى خادم محلي.

ga('create', 'UA-XXXXX-Y', 'auto');

ga(function(tracker) {

  // Grab a reference to the default sendHitTask function.
  var originalSendHitTask = tracker.get('sendHitTask');

  // Modifies sendHitTask to send a copy of the request to a local server after
  // sending the normal request to www.google-analytics.com/collect.
  tracker.set('sendHitTask', function(model) {
    originalSendHitTask(model);
    var xhr = new XMLHttpRequest();
    xhr.open('POST', '/localhits', true);
    xhr.send(model.get('hitPayload'));
  });
});

ga('send', 'pageview');

إلغاء معالجة المهام

يمكن أن تلغي المهمة معالجة المهام اللاحقة من خلال طرح استثناء. إذا تم تنفيذ مهمة طرح الاستثناء قبل sendHitTask، يؤدي ذلك إلى منع إرسال طلب Measurement Protocol إلى خوادم "إحصاءات Google". في المثال التالي، نلغي الطلب عندما يحتوي متصفّح المستخدم على ملف تعريف ارتباط باسم "اختبار" بالقيمة "صحيح".

ga('create', 'UA-XXXXX-Y', 'auto');

ga(function(tracker) {
  var originalBuildHitTask = tracker.get('buildHitTask');
  tracker.set('buildHitTask', function(model) {
    if (document.cookie.match(/testing=true/)) {
      throw 'Aborted tracking for test user.';
    }
    originalBuildHitTask(model);
  });
});

ga('send', 'pageview');

إيقاف مهمة

لإيقاف أي من دوال المهام المضمنة، استبدلها بقيمة خالية.

ga('create', 'UA-XXXXX-Y', 'auto');
ga('set', 'checkProtocolTask', null); // Disables file protocol checking.
ga('send', 'pageview');