إرسال البيانات إلى "إحصاءات 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 Analytics للنتيجة الحالية ولكن ليس لأي نتائج لاحقة. مثال على ذلك هو نتيجة حدث يكون فيها الحقلان 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 أعلاه لنوع نتيجة "الحدث" على النحو التالي:

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

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

استخدام جهاز تتبُّع يحمل اسمًا

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

سيتم استدعاء الأمر 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. يوضّح الدليل التالي كيفية استخدام مكوّنات analytics.js الإضافية مع قائمة انتظار الأوامر ga().