دليل مطوِّري واجهة برمجة التطبيقات للمراقبة

تسمح لك Monitoring API بإنشاء أدوات لمراقبة سلوك علاماتك وأدائها. ويتم ذلك من خلال طريقة addEventCallback Custom Template API. وتتيح لك هذه الطريقة تحديد معاودة الاتصال بالحدث التي سيتم استدعاؤها في نهاية الحدث. سيتلقى معاودة الاتصال معلومات حول الحدث، ما يتيح لك إنشاء عمليات تنفيذ مراقبة العلامة الخاصة بك. يمكنك أيضًا إضافة بيانات وصفية إلى علاماتك للسماح بإجراء عمليات مراقبة أكثر دقة.

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

حالة العلامة

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

https://www.example.com/monitoring?ctid=GTM-XXXXXX&success=4&failure=1&exception=1&timeout=0

يمكن إعداد عنوان URL لـ Pixel باستخدام مثال الرمز التالي:

const addEventCallback = require('addEventCallback');
const sendPixel = require('sendPixel');

addEventCallback(function(containerId, eventData) {
  let successCount = 0;
  let failureCount = 0;
  let exceptionCount = 0;
  let timeoutCount = 0;

  const tagData = eventData['tags'];
  const timingData = [];
  for (let i in tagData) {
    let entry  = tagData[i];
    switch (entry.status) {
      case 'success':
        successCount++;
        continue;
      case 'failure':
        failureCount++;
        continue;
      case 'exception':
        exceptionCount++;
        continue;
      case 'timeout':
        timeoutCount++;
        continue;
    }
  }
  let url = 'https://www.example.com/monitoring?ctid=' + containerId +
      '&success=' + successCount +
      '&failure=' + failureCount +
      '&exception=' + exceptionCount +
      '&timeout=' + timeoutCount;
  sendPixel(url);
});
data.gtmOnSuccess();

أوقات التنفيذ

يستخدِم هذا الأسلوب addEventCallback لمساعدتك في جمع بيانات عن مُدد تنفيذ العلامات. وبالنسبة إلى كلّ علامة يتمّ تنشيطها لهذا الحدث، تتمّ إضافة مَعلمة طلب بحث إلى عنوان URL لوحدة البكسل الذي يتضمّن رقم تعريف العلامة ووقت التنفيذ. يؤدي هذا إلى إرسال وحدة بكسل تشبه ما يلي:

https://www.example.com/monitoring?ctid=GTM-XXXXXX&tag12=1200&tag50=400&tag1=6000

يمكن إعداد عنوان URL لـ Pixel باستخدام مثال الرمز التالي:

const addEventCallback = require('addEventCallback');
const sendPixel = require('sendPixel');

addEventCallback(function(containerId, eventData) {
  let url = 'https://www.example.com/monitoring?ctid=' + containerId;
  const tagData = eventData['tags'];
  const timingData = [];
  for (let i in tagData) {
    let entry = tagData[i];
    timingData.push('&tag' + entry['id'] + '=' + entry['executionTime']);
  }
  url += timingData.join('');
  sendPixel(url);
});
data.gtmOnSuccess();

البيانات الوصفية

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

على سبيل المثال: تتم إضافة علامة إلى حاوية لحملة إعلانية جديدة. تحتوي الحاوية على العديد من العلامات الحالية، ولكنك تهتم فقط بمراقبة هذه العلامة الجديدة.

لتحديد هذه العلامة من معاودة الاتصال لحدث، أضِف بيانات وصفية إلى العلامة:

1. في تعريف العلامة، انقر على الإعدادات المتقدمة > البيانات الوصفية الإضافية للعلامة.
2. انقر على تضمين اسم العلامة بحيث يتم وضع علامة فيه.
3. في مفتاح اسم العلامة، أدخِل قيمة. يستخدم هذا المثال "name" كقيمة. وسيشمل ذلك اسم العلامة في بيانات الحدث عند إرسالها.
4. انقر على +إضافة بيانات وصفية وأدخِل زوجَي المفتاح والقيمة. يستخدم هذا المثال مفتاحًا باسم "group" وقيمة "Campaign 2019".
5. استخدِم الخيار +إضافة بيانات وصفية لإضافة صفوف أخرى من أزواج المفتاح/القيمة، كما هو مطلوب.

في نموذج مخصَّص، يمكن لمطوّر البرامج التعرُّف على هذه العلامة من خلال البحث عن القيم المحدَّدة في البيانات الوصفية:

const addEventCallback = require('addEventCallback');
const sendPixel = require('sendPixel');

addEventCallback(function(containerId, eventData) {
  let url = 'https://www.example.com/monitoring/campaignPixel?ctid=' + containerId;
  const tagData = eventData['tags'];
  for (let i in tagData) {
    let entry = tagData[i];
    if (entry['name'] === 'Conversion Pixel 2019') {
      url += '&status=' + entry['status'];
      break;
    }
  }
  sendPixel(url);
});
data.gtmOnSuccess();

ينتج عن ذلك عنوان URL لبكسل يشبه ما يلي:

https://www.example.com/monitoring/campaignPixel?ctid=GTM-XXXXXX&status=success

يمكنك بعد ذلك مراقبة جميع العلامات الخاصة بمجموعة "حملة 2019" إذا أردت ذلك:

const addEventCallback = require('addEventCallback');
const encode = require('encodeUriComponent');
const sendPixel = require('sendPixel');

addEventCallback(function(containerId, eventData) {
  let url = 'https://www.example.com/monitoring/campaign2019?ctid=' + containerId;
  const tagData = eventData['tags'];
  for (let i in tagData) {
    let entry = tagData[i];
    if (entry['group'] === 'Campaign 2019') {
      url += '&' + encode(entry['name']) + '=' + entry['status'];
      break;
    }
  }
  sendPixel(url);
});
data.gtmOnSuccess();

سينتج عن ذلك استخدام وحدة بكسل مراقبة مشابهة لما يلي:

https://www.example.com/monitoring/campaign2019?ctid=GTM-XXXXXX&Conversion%20Pixel%202019=failure