إرسال البيانات إلى "إحصاءات Google"

يضيف السطر الأخير من مقتطف قياس JavaScript أمر send إلى قائمة انتظار الأوامر ga() لإرسال مشاهدة صفحة إلى "إحصاءات Google":

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

الكائن الذي يجري عملية الإرسال هو أداة التتبّع التي تمت جدولتها لإنشائها في السطر السابق من الرمز، والبيانات التي يتم إرسالها هي البيانات المخزّنة في أداة التتبّع هذه.

يصف هذا الدليل الطرق المختلفة لإرسال البيانات إلى "إحصاءات Google" ويوضح كيفية التحكّم في البيانات التي يتم إرسالها.

النتائج وأنواع النتائج وMeasurement Protocol

عندما تُرسل أداة التتبع بيانات إلى "إحصاءات Google" تُسمى إرسال نتيجة، يجب أن تكون لكل نتيجة نوع نتيجة. ترسل علامة "إحصاءات Google" نتيجة من النوع pageview. وتشمل أنواع النتائج الأخرى screenview وevent وtransaction وitem وsocial وexception وtiming. ويوضّح هذا الدليل المفاهيم والأساليب الشائعة في جميع أنواع النتائج. يمكن العثور على الأدلة الفردية لكل نوع نتيجة ضمن قسم قياس تفاعلات المستخدمين الشائعة في شريط التنقل الأيمن.

النتيجة هي طلب HTTP، ويتألف من أزواج الحقول والقيم المُشفّرة كسلسلة طلبات بحث، ويتم إرسالها إلى Measurement Protocol.

إذا كانت أدوات مطوّري البرامج في المتصفّح مفتوحة عند تحميل صفحة تستخدم analytics.js، يمكنك مشاهدة النتائج التي تم إرسالها في علامة التبويب "الشبكة". البحث عن طلبات تم إرسالها إلى google-analytics.com/collect.

البيانات التي يتم إرسالها

عند إرسال نتيجة إلى Measurement Protocol، تُرسل أدوات التتبّع جميع الحقول المخزّنة حاليًا والتي تكون معلّمات Measurement Protocol صالحة. على سبيل المثال، يتم إرسال الحقول مثل title وlocation ولكن لا يتم إرسال cookieDomain وhitCallback.

في بعض الحالات، قد تحتاج إلى إرسال حقول إلى "إحصاءات Google" للنتيجة الحالية ولكن ليس لأي نتائج لاحقة. ومن أمثلة ذلك نتيجة حدث حيث يكون الحقلان eventAction وeventLabel ملائمين للنتيجة الحالية فقط.

لإرسال الحقول بالنتيجة الحالية فقط، يمكنك تمريرها كوسيطات إلى طريقة send. لإرسال بيانات الحقول مع جميع النتائج اللاحقة، يجب تعديل أداة التتبُّع باستخدام طريقة set.

طريقة الإرسال

يمكن استدعاء أسلوب send في أداة التتبّع مباشرةً على كائن أداة التتبّع نفسها أو من خلال إضافة أمر send إلى قائمة انتظار الأوامر ga(). نظرًا لأنّه لا يتوفّر لديك في معظم الوقت مرجع لكائن أداة التتبُّع، فإن استخدام قائمة انتظار الأوامر ga() هو الطريقة المُقترَحة لإرسال بيانات أداة التتبُّع إلى "إحصاءات Google".

استخدام قائمة انتظار الأوامر ga()

في ما يلي توقيع إضافة الأمر send إلى قائمة انتظار الأوامر ga():

ga('[trackerName.]send', [hitType], [...fields], [fieldsObject]);

كما ورد أعلاه، يتم إرسال القيم المحدّدة في المعلّمات hitType و...fields وfieldsObject للنتيجة الحالية فقط. ولا يتم تخزينها على عنصر أداة التتبُّع، ولا يتم إرسالها مع النتائج اللاحقة.

إذا سبق ضبط أي من الحقول التي تم تمريرها باستخدام الأمر send على كائن برنامج التتبُّع، سيتم استخدام القيم التي تم تمريرها في الأمر بدلاً من القيم المخزَّنة في أداة التتبُّع.

يجب أن تحدّد الطلبات إلى الأمر send hitType وقد يلزم أيضًا تنفيذ مَعلمات أخرى، استنادًا إلى النوع المحدّد. اطّلِع على الأدلة الفردية لقياس تفاعلات المستخدمين الشائعة في شريط التنقّل الأيمن.

إنّ أبسط طريقة لاستخدام الأمر send تناسب جميع أنواع النتائج هي تمرير جميع الحقول باستخدام المعلَمة fieldsObject. مثلاً:

ga('send', {
  hitType: 'event',
  eventCategory: 'Video',
  eventAction: 'play',
  eventLabel: 'cats.mp4'
});

لتسهيل الأمر، تسمح أنواع معيّنة من النتائج بتمرير الحقول الشائعة الاستخدام مباشرةً كوسيطات إلى الأمر send. على سبيل المثال، يمكن إعادة كتابة أمر send أعلاه لنوع النتيجة "event" إعادة الصياغة على النحو التالي:

ga('send', 'event', 'Video', 'play', 'cats.mp4');

للحصول على قائمة كاملة بالحقول التي يمكن تمريرها كوسيطات لأنواع النتائج المختلفة، راجع قسم "معلّمات المعلَمات&quot؛ في مرجع طريقة الإرسال.

استخدام أداة تتبّع ذات اسم

إذا كنت تستخدم أداة تتبّع مُسمّاة بدلاً من أداة التتبّع التلقائية، يمكنك تمرير اسمها في سلسلة الأوامر.

سيتم استدعاء الأمر send التالي في أداة التتبّع باسم &"myTracker":

ga('myTracker.send', 'event', 'Video', 'play', 'cats.mp4');

على عنصر أداة التتبّع نفسه

إذا كان لديك مرجع لكائن أداة التتبّع، يمكنك استدعاء طريقة send الخاصة بهذه الأداة مباشرةً:

ga(function(tracker) {
  tracker.send('event', 'Video', 'play', 'cats.mp4');
});

معرفة وقت إرسال النتيجة

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

ومن أمثلة ذلك ما إذا كنت تريد إرسال حدث إلى "إحصاءات Google" لتسجيل نقر مستخدم على زر إرسال نموذج. في معظم الحالات، سيبدأ النقر على زر الإرسال في تحميل الصفحة التالية على الفور، ولن يتم تشغيل أي أوامر من ga('send', ...).

الحل لهذا هو اعتراض الحدث لإيقاف تحميل الصفحة. يمكنك بعد ذلك إرسال نتائجك إلى "إحصاءات Google" كالمعتاد، وبعد الانتهاء من إرسال النتيجة، يمكنك إعادة إرسال النموذج آليًا.

hitCallback

لتلقّي إشعار عند الانتهاء من إرسال نتيجة، يمكنك ضبط الحقل hitCallback. hitCallback هي دالة يتم استدعاءها فور إرسال النتيجة بنجاح.

يوضّح المثال التالي كيفية إلغاء إجراء الإرسال التلقائي للنموذج وإرسال نتيجة إلى"إحصاءات Google"ثم إعادة إرسال النموذج باستخدام الدالة hitCallback:

// Gets a reference to the form element, assuming
// it contains the id attribute "signup-form".
var form = document.getElementById('signup-form');

// Adds a listener for the "submit" event.
form.addEventListener('submit', function(event) {

  // Prevents the browser from submitting the form
  // and thus unloading the current page.
  event.preventDefault();

  // Sends the event to Google Analytics and
  // resubmits the form once the hit is done.
  ga('send', 'event', 'Signup Form', 'submit', {
    hitCallback: function() {
      form.submit();
    }
  });
});

انتهاء مهلة المناولة

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

وعندما تضع وظيفة موقع مهمة داخل دالة hitCallback، يجب دائمًا استخدام دالة المهلة للتعامل مع الحالات التي يتعذر فيها تحميل مكتبة analytics.js.

ويوضّح المثال التالي الرمز أعلاه لاستخدام مهلة. إذا مرّت ثانية واحدة بعد أن ينقر المستخدم على زر "الإرسال" ولم يتم تشغيل hitCallback، ستتم إعادة إرسال النموذج على أي حال.

// Gets a reference to the form element, assuming
// it contains the id attribute "signup-form".
var form = document.getElementById('signup-form');

// Adds a listener for the "submit" event.
form.addEventListener('submit', function(event) {

  // Prevents the browser from submitting the form
  // and thus unloading the current page.
  event.preventDefault();

  // Creates a timeout to call `submitForm` after one second.
  setTimeout(submitForm, 1000);

  // Keeps track of whether or not the form has been submitted.
  // This prevents the form from being submitted twice in cases
  // where `hitCallback` fires normally.
  var formSubmitted = false;

  function submitForm() {
    if (!formSubmitted) {
      formSubmitted = true;
      form.submit();
    }
  }

  // Sends the event to Google Analytics and
  // resubmits the form once the hit is done.
  ga('send', 'event', 'Signup Form', 'submit', {
    hitCallback: submitForm
  });
});

إذا كنت تستخدم النمط أعلاه في أماكن متعددة على موقعك الإلكتروني، قد يكون من الأسهل إنشاء دالة خدمات للتعامل مع المهلات.

تقبل دالة المرافق التالية الدالة كإدخال وتعرض دالة جديدة. إذا تم استدعاء الدالة المعروضة قبل فترة المهلة (المهلة التلقائية ثانية واحدة)، ستعمل على محو المهلة وتستدعي دالة الإدخال. إذا لم يتم استدعاء الدالة المعروضة قبل فترة المهلة، يتم استدعاء دالة الإدخال بغض النظر عن ذلك.

function createFunctionWithTimeout(callback, opt_timeout) {
  var called = false;
  function fn() {
    if (!called) {
      called = true;
      callback();
    }
  }
  setTimeout(fn, opt_timeout || 1000);
  return fn;
}

يمكنك الآن بسهولة تضمين جميع دوال hitCallback بمهلة لضمان عمل موقعك الإلكتروني على النحو المتوقع حتى في الحالات التي يتعذّر فيها إرسال نتائجك أو عدم تحميل مكتبة analytics.js مطلقًا.

// Gets a reference to the form element, assuming
// it contains the id attribute "signup-form".
var form = document.getElementById('signup-form');

// Adds a listener for the "submit" event.
form.addEventListener('submit', function(event) {

  // Prevents the browser from submitting the form
  // and thus unloading the current page.
  event.preventDefault();

  // Sends the event to Google Analytics and
  // resubmits the form once the hit is done.
  ga('send', 'event', 'Signup Form', 'submit', {
    hitCallback: createFunctionWithTimeout(function() {
      form.submit();
    })
  });
});

تحديد آليات نقل مختلفة

تختار analytics.js تلقائيًا طريقة HTTP وآلية النقل التي يمكن استخدامها لإرسال النتائج على النحو الأمثل. الخيارات الثلاثة هي 'image' (باستخدام عنصر Image) أو 'xhr' (باستخدام عنصر XMLHttpRequest) أو 'beacon' باستخدام طريقة navigator.sendBeacon الجديدة.

تشارك الطريقتين السابقتان المشكلة الموضحة في القسم السابق (حيث لا يتم إرسال النتائج في كثير من الأحيان عند إلغاء تحميل الصفحة). والطريقة navigator.sendBeacon هي ميزة HTML جديدة تم إنشاؤها لحلّ هذه المشكلة.

إذا كان متصفّح المستخدم يتيح استخدام navigator.sendBeacon، يمكنك تحديد 'beacon' كآلية transport وعدم القلق بشأن إعداد استدعاء نتيجة.

يحدِّد الرمز التالي آلية النقل على 'beacon' في المتصفّحات المتوافقة.

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

// Updates the tracker to use `navigator.sendBeacon` if available.
ga('set', 'transport', 'beacon');

تستخدم analytics.js حاليًا navigator.sendBeacon فقط إذا تم ضبط آلية النقل على 'beacon'. وفي المستقبل، من المرجّح أن ينتقل analytics.js إلى استخدام 'beacon' كآلية تلقائية في المتصفّحات التي تتوافق معه.

الخطوات اللاحقة

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