מדריך למפתחים בנושא Monitoring API

Monitoring API מאפשר לכם לבנות כלים למעקב אחרי ההתנהגות והביצועים של התגים. כדי לעשות את זה, משתמשים בשיטה addEventCallback Custom Template API (ה-API של תבניות בהתאמה אישית). השיטה הזו מאפשרת לציין קריאה חוזרת של אירוע שתופעל בסיום אירוע. הקריאה החוזרת תקבל מידע על האירוע, וכך תוכלו ליצור הטמעות משלכם למעקב אחר תגים. אפשר גם להוסיף לתגים מטא-נתונים כדי לאפשר מעקב מדויק יותר.

Monitoring API יכול לתמוך בכמה תרחישים לדוגמה למעקב, כמו סטטוס תג, זמני ביצוע ומטא-נתונים. המטרה הסופית של הפיקסלים למעקב האלה היא לשלוח נתונים לנקודת קצה (endpoint) לבחירתכם. לאחר מכן אפשר לגשת ליומנים מנקודת הקצה הזו כדי לאסוף נתוני מעקב. לאחר מכן ניתן להציג את הנתונים האלה במרכז בקרה או להשתמש בהם כדי להפעיל מערכת התראות.

סטטוס התג

השיטה 'סטטוס תג' שמוצגת בדוגמה הזו משתמשת ב-addEventCallback כדי לחשב את סטטוס ההפעלה של תגים בדף. הפעולה הזו תציג בלולא את כל התגים שהופעלו עבור האירוע, ותספור את מספר התגים שהצליחו, נכשלו, גרמו לחריגה או שתם הזמן הקצוב לתפוגה. לאחר מכן הסכומים הכוללים מתווספים לכתובת ה-URL של הפיקסל למעקב כפרמטרים של שאילתה. כתובת ה-URL של הפיקסל למעקב תהיה דומה לזו:

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

ניתן להגדיר כתובת URL של פיקסל לפי הקוד הבא:

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 של פיקסל לפי הקוד הבא:

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. עם זאת, ייתכנו מקרים שבהם תרצו לעקוב רק אחר קבוצת משנה של תגים. כדי לעשות זאת, משתמשים בקטע Tag Metadata (מטא-נתונים של תג) כדי לציין צמדי מפתח שרירותיים של ערכי מפתח בהגדרת תג. הערכים האלה ייכללו באובייקט של נתוני האירוע כשמתרחשת קריאה חוזרת (callback) של אירוע.

לדוגמה: תג נוסף למאגר תגים לקמפיין פרסום חדש. המאגר כולל הרבה תגים קיימים, אבל אתם רוצים לעקוב רק אחרי התג החדש הזה.

כדי לזהות את התג הזה באמצעות קריאה חוזרת של אירוע, יש להוסיף מטא-נתונים לתג:

1. בהגדרת התג, לוחצים על הגדרות מתקדמות > מטא-נתונים נוספים של תגים.
2. לוחצים על Include Tag Name (כלול שם תג) כדי שהוא יהיה מסומן.
3. בשדה Key for tag name, מזינים ערך. בדוגמה הזו נשתמש ב-'name' כערך. השם הזה יכלול את שם התג בנתוני האירוע ברגע שהוא יישלח.
4. לוחצים על +הוספת מטא-נתונים ומזינים צמד מפתח וערך. בדוגמה הזו נעשה שימוש במפתח בשם 'קבוצה' ואת הערך '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

אם תרצו, תוכלו לעקוב אחר כל התגים של 'Campaign 2019'. group:

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