Monitoring API-Entwicklerleitfaden

Mit der Monitoring API können Sie Tools erstellen, mit denen Sie das Verhalten und die Leistung Ihrer Tags überwachen können. Dazu verwenden Sie die API-Methode addEventCallback für benutzerdefinierte Vorlagen. Mit dieser Methode können Sie einen Ereignis-Callback angeben, der am Ende eines Ereignisses ausgelöst wird. Dieser Callback erhält Informationen zum Ereignis, sodass Sie eigene Implementierungen zur Tag-Überwachung erstellen können. Sie können Ihren Tags auch Metadaten hinzufügen, um eine detailliertere Überwachung zu ermöglichen.

Die Monitoring API kann mehrere Monitoringanwendungsfälle wie Tag-Status, Ausführungszeiten und Metadaten unterstützen. Das Ziel dieser Monitoring-Pixel besteht darin, Daten an einen Endpunkt Ihrer Wahl zu senden. Auf Logs von diesem Endpunkt kann dann zugegriffen werden, um Monitoring-Daten zu erfassen. Diese Daten können dann in einem Dashboard angezeigt oder zum Auslösen eines Benachrichtigungssystems verwendet werden.

Tag-Status

Bei der in diesem Beispiel gezeigten Technik für den Tag-Status wird addEventCallback verwendet, um den Auslösestatus von Tags auf einer Seite zu ermitteln. Dadurch werden alle Tags durchlaufen, die für das Ereignis ausgelöst wurden, und die Anzahl der Tags gezählt, die erfolgreich waren, fehlgeschlagen sind, eine Ausnahme ausgelöst haben oder bei denen eine Zeitüberschreitung aufgetreten ist. Diese Summen werden dann der Monitoring-Pixel-URL als Suchparameter hinzugefügt. Das Monitoring-Pixel hat eine URL, die in etwa so aussieht:

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

Die Pixel-URL kann mit dem folgenden Codebeispiel eingerichtet werden:

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();

Ausführungszeiten

Bei diesem Verfahren wird addEventCallback verwendet, um Daten zu den Ausführungszeiten Ihrer Tags zu erheben. Für jedes Tag, das für dieses Ereignis ausgelöst wurde, wird der Pixel-URL ein Suchparameter hinzugefügt, der die ID des Tags und die Ausführungszeit enthält. Daraufhin wird ein Pixel gesendet, das in etwa so aussieht:

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

Die Pixel-URL kann mit dem folgenden Codebeispiel eingerichtet werden:

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();

Metadaten

Mit den von der Monitoring API bereitgestellten Basisdaten können Sie nützliche Dashboards erstellen. Es kann jedoch Fälle geben, in denen Sie nur einen Teil der Tags überwachen möchten. Geben Sie dazu im Bereich Tag-Metadaten in einer Tag-Definition beliebige Schlüssel/Wert-Paare an. Diese Werte werden bei einem Ereignis-Callback in das Ereignisdatenobjekt aufgenommen.

Beispiel: Ein Tag wird einem Container für eine neue Werbekampagne hinzugefügt. Der Container enthält viele Tags. Sie möchten aber nur dieses neue Tag im Blick behalten.

Fügen Sie dem Tag Metadaten hinzu, um dieses Tag bei einem Ereignis-Callback zu identifizieren:

1. Klicken Sie in der Tag-Definition auf Erweiterte Einstellungen > Zusätzliche Tag-Metadaten.
2. Klicken Sie auf Tag-Name einschließen, damit das Kästchen angeklickt ist.
3. Geben Sie unter Schlüssel für Tag-Name einen Wert ein. In diesem Beispiel wird „name“ als Wert verwendet. Dadurch wird der Tag-Name in die Ereignisdaten aufgenommen, wenn diese gesendet werden.
4. Klicken Sie auf + Metadaten hinzufügen und geben Sie ein Schlüssel-Wert-Paar ein. In diesem Beispiel wird ein Schlüssel namens „group“ und der Wert „Kampagne 2019“ verwendet.
5. Mit +Metadaten hinzufügen können Sie bei Bedarf weitere Zeilen mit Schlüssel/Wert-Paaren hinzufügen.

In einer benutzerdefinierten Vorlage kann der Entwickler dieses Tag identifizieren, indem er nach den in den Metadaten festgelegten Werten sucht:

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();

Dies führt zu einer Pixel-URL, die in etwa so aussieht:

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

Anschließend können Sie alle Tags der Gruppe „Kampagne 2019“ im Blick behalten:

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();

Dies würde zu einem Monitoring-Pixel ähnlich dem folgenden führen:

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