إرسال البيانات إلى "إحصاءات Google" باستخدام gtag.js

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

إرسال البيانات باستخدام الأمر event

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

gtag('event', 'login', {'method': 'Google'});

مزيد من المعلومات حول الأمر event في مرجع واجهة برمجة التطبيقات

توجيه البيانات إلى المجموعات والمواقع

يمكنك إرسال مجموعة واحدة من معلومات القياس إلى رقم تعريف موقع واحد أو أكثر في "إحصاءات Google"، ومجموعة أخرى من المعلومات إلى أرقام تعريف مواقع أخرى. يمكنك تنظيم المواقع في مجموعات وتوجيه البيانات إليها.

على سبيل المثال، يوضِّح مثال الرمز التالي كيفية توجيه حدث sign_in إلى مجموعة "وكالة" تتضمّن موقعَين على "إحصاءات Google".

// Configure a target
gtag('config', 'GA_MEASUREMENT_ID_1');
gtag('config', 'GA_MEASUREMENT_ID_2', { 'groups': 'agency' });
gtag('config', 'GA_MEASUREMENT_ID_3', { 'groups': 'agency' });

// Route this sign_in event to Analytics IDs in the 'agency' group:
gtag('event', 'sign_in', { 'send_to': 'agency' });

مزيد من المعلومات حول كيفية تجميع البيانات وتوجيهها

معرفة وقت إرسال الحدث

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

على سبيل المثال، يمكنك إرسال حدث إلى "إحصاءات Google" لتسجيل أنّ المستخدِم قد نقر على زر إرسال النموذج. في معظم الحالات، سيؤدي النقر على زر الإرسال إلى بدء تحميل الصفحة التالية على الفور قبل أن تتوفَّر فرصة لتنفيذ أي أوامر event.

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

تنفيذ وظائف معاودة الاتصال بالأحداث

يمكنك تنفيذ دالة استدعاء الحدث التي يتم استدعاؤها فور إرسال الحدث بنجاح.

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

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

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

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

  // Send the event to Google Analytics and
  // resubmit the form once the hit is done.
  gtag('event', 'signup_form_complete', {
    'event_callback': function() {
      form.submit();
    }
  });
});

التعامل مع المدد المحدَّدة لمهلة معيّنة

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

عندما تضع وظائف الموقع الإلكتروني المهمة في دالة معاودة الاتصال بالحدث، عليك دائمًا استخدام دالة المهلة للتعامل مع الحالات التي يتعذّر فيها تحميل مكتبة gtag.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();

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

  // Monitors whether or not the form has been submitted.
  // This prevents the form from being submitted twice in cases
  // where the event callback function 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.
  gtag('event', 'signup_form_complete', {
    'event_callback': submitForm
  });
});

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

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

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

والآن، يمكنك إنهاء جميع دوال استدعاء الأحداث بمهلة لضمان عمل موقعك الإلكتروني على النحو المتوقّع، حتى في الحالات التي يتعذّر فيها إرسال الأحداث أو لا يتم تحميل مكتبة gtag.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.
  gtag('event', 'signup_form', { 'event_callback': {
    createFunctionWithTimeout(function() {
      form.submit();
    })
  }});
});

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

تختار gtag.js تلقائيًا طريقة HTTPS وآلية النقل التي يتم من خلالها إرسال النتائج على النحو الأمثل. الخيارات الثلاثة هي:

  • 'image' (باستخدام عنصر Image)
  • "xhr" (باستخدام كائن XMLHttpRequest)
  • 'مرشد' (باستخدام طريقة navigator.sendBeacon)

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

يضبط الرمز التالي آلية النقل على 'beacon' في المتصفّحات المتوافقة معه:

gtag('config', 'GA_MEASUREMENT_ID', { 'transport_type': 'beacon'});