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

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

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

סטטוס התג

השיטה של סטטוס התג שמוצגת בדוגמה הזו משתמשת ב-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) של אירוע.

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

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

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