Server-Tag erstellen

Im Artikel Einführung in das serverseitige Tagging haben Sie einen Überblick über das serverseitige Tagging in Tag Manager erhalten. Sie haben gelernt, was Clients sind und was sie tun: Clients empfangen Ereignisdaten von den Geräten Ihrer Nutzer und passen sie für die Verwendung durch den Rest des Containers an. In diesem Artikel erfahren Sie, wie Sie diese Daten in serverseitigen Tags verarbeiten.

In einem Servercontainer empfangen Tags eingehende Ereignisdaten von Ihren Clients, transformieren sie und senden sie zur Erfassung und Analyse zurück. Über Tags können die Daten an beliebige Ziele gesendet werden. Solange das Ziel HTTP-Anfragen akzeptiert, kann es auch Daten von einem Servercontainer akzeptieren.

Servercontainer haben drei integrierte Tags, die ohne benutzerdefinierte Konfiguration verwendet werden können:

  • Google Analytics 4
  • HTTP-Anfrage

Wenn Sie Daten an einen anderen Ort als Google Analytics senden möchten oder mehr Funktionen benötigen, als das HTTP-Anfrage-Tag bietet, müssen Sie ein anderes Tag verwenden. Weitere Tags finden Sie in der Community-Galerie für Vorlagen. Sie können auch eigene Tags erstellen. In dieser Anleitung erfahren Sie die Grundlagen zum Erstellen eigener Tags für einen Servercontainer.

Zielsetzungen

  • Hier erfahren Sie, welche APIs Sie zum Lesen von Ereignisdaten, Senden von HTTP-Anfragen und Setzen von Cookies im Browser verwenden sollten.
  • Best Practices für die Konfigurationsoptionen von Tags
  • Sie lernen den Unterschied zwischen benutzerdefinierten und automatisch erfassten Daten kennen und erfahren, warum diese Unterscheidung wichtig ist.
  • Informationen zur Rolle eines Tags in einem Servercontainer Machen Sie sich damit vertraut, was ein Tag bewirken sollte und was nicht.
  • Hier erfahren Sie, wann Sie eine Tag-Vorlage in die Community-Galerie für Vorlagen einreichen sollten.

Vorbereitung

Das Baz Analytics-Tag

In dieser Anleitung erstellen Sie ein Tag, das Messdaten an einen Dienst namens Baz Analytics sendet.

Baz Analytics ist ein einfacher, hypothetischer Analysedienst, der Daten über HTTP-GET-Anfragen an https://example.com/baz_analytics aufnimmt. Sie hat die folgenden Parameter:

Parameter Beispiel Beschreibung
id BA-1234 Die ID Ihres Bazarketing-Analytics-Kontos.
de Klick Ereignisname
l https://www.google.com/search?q=sgtm URL der Seite, auf der das Ereignis aufgetreten ist.
u 2384294892 Die ID des Nutzers, der die Aktion ausgeführt hat. Wird verwendet, um mehrere Aktionen auf einen einzelnen Nutzer zurückzuführen.

Tag-Konfiguration

Erstellen Sie zuerst die Tag-Vorlage. Rufen Sie den Bereich Vorlagen des Containers auf und klicken Sie im Bereich Tag-Vorlagen auf Neu. Fügen Sie dem Tag einen Namen und eine Beschreibung hinzu.

Gehen Sie als Nächstes im Vorlageneditor zum Bereich Felder, um die verschiedenen Konfigurationsoptionen für Ihr Tag hinzuzufügen. Die nächste Frage lautet: Welche Optionen brauchen Sie? Es gibt drei Möglichkeiten, das Tag zu erstellen:

  1. Gesamtkonfiguration: Fügen Sie für jeden Parameter ein Konfigurationsfeld hinzu. Der Nutzer muss alles explizit festlegen.
  2. Keine Konfiguration: Das Tag kann nicht konfiguriert werden. Alle Daten stammen direkt aus dem Ereignis.
  3. Teilweise Konfiguration: Es gibt Felder für einige Parameter, aber nicht für andere.

Felder für jeden Parameter sind sehr flexibel und geben dem Nutzer die volle Kontrolle über seine Tag-Konfiguration. In der Praxis führt dies jedoch in der Regel zu viel doppelter Arbeit. Insbesondere der Baz Analytics-Parameter l, der die URL der Seite enthält, ist eindeutig und universell. Die Eingabe derselben, unveränderten Daten bei jeder Tag-Konfiguration sollte dem Computer am besten überlassen werden.

Vielleicht ist die Lösung ein Tag, das nur Daten aus einem Ereignis verwendet. Dies ist das einfachste Tag, das ein Nutzer konfigurieren kann, da er nichts weiter tun muss. Andererseits ist es auch die restriktivste und empfindlichste Option. Nutzer können das Verhalten des Tags nicht ändern, auch wenn dies erforderlich ist. Angenommen, ein Unternehmen nennt ein Ereignis auf seiner Website und in Google Analytics purchase, in Baz Analytics aber buy. Möglicherweise stimmen die Annahmen des Tags zur Struktur der eingehenden Ereignisdaten nicht mit der Realität überein. In beiden Fällen ist der Nutzer blockiert.

Wie bei vielen Dingen liegt die Antwort irgendwo zwischen den beiden Extremen. Einige Daten sollten immer aus dem Ereignis erfasst werden. Andere Daten sollten vom Nutzer konfiguriert werden. Wie entscheiden Sie, welche das ist? Um diese Frage zu beantworten, müssen wir uns die Daten genauer ansehen, die in den Container eingehen.

Woher stammen die Daten?

Die Daten, die über das Google Analytics 4-Tag an einen Servercontainer gesendet werden, lassen sich grob in zwei Kategorien unterteilen: nutzerspezifische Daten und automatisch erhobene Daten.

Von Nutzern angegebene Daten sind alle Daten, die ein Nutzer in einen gtag.js-event-Befehl eingibt. Beispiel:

gtag('event', 'search', {
  search_term: 'beets',
});

Dies führt zu den folgenden Parametern im Servercontainer:

{
  event_name: 'search',
  search_term: 'beets',
}

Das ist ganz einfach, aber aus Sicht des Tags ist es sehr schwierig, damit zu arbeiten. Da diese Daten vom Nutzer eingegeben werden, kann es sich um alles handeln. Möglicherweise sendet der Nutzer wie oben nur empfohlene Ereignisse und Parameter, aber das ist keine Voraussetzung. Mit der wichtigen Ausnahme des Speicherorts (aber nicht des Werts!) des Parameters event_name gibt es keine Garantien für das Format oder die Struktur der Nutzerdaten.

Glücklicherweise erhält der Container nicht nur von Nutzern eingegebene Daten. Außerdem werden eine Reihe von Daten erfasst, die automatisch vom Google Analytics 4-Tag im Browser erhoben werden. Das betrifft Folgendes:

  • ip_override
  • language
  • page_location
  • page_referrer
  • page_title
  • screen_resolution
  • user_agent

Wenn die Serveranfrage von einem Webbrowser stammt, sind möglicherweise auch Browser-Cookie-Daten über die getCookieValue API verfügbar.

Zusammen bilden sie die oben erwähnten automatisch erhobenen Daten. Im Allgemeinen besteht sie aus Daten, die universell und semantisch eindeutig sind. Wenn eine Anfrage von einem GA4-Tag im Browser eingeht, sind diese Daten immer verfügbar und haben immer dasselbe Format. Weitere Informationen zu diesen Parametern finden Sie in der Referenz zu Ereignissen.

Diese Klassifizierung ist ein nützliches Tool, um zu entscheiden, welche Daten vom Nutzer konfiguriert und welche im Tag angegeben werden sollten. Automatisch erfasste Daten können sicher direkt aus dem Ereignis gelesen werden. Alles andere sollte vom Nutzer konfiguriert werden.

Sehen wir uns die Parameter für das Baz Analytics-Tag noch einmal an.

  • Mess-ID, id:Da dieser Wert nicht automatisch erfasst wird, ist er ein gutes Beispiel für einen Wert, der vom Nutzer bei der Konfiguration des Tags eingegeben werden sollte.
  • Ereignisname en:Wie oben erwähnt, kann der Ereignisname immer direkt aus dem Parameter event_name entnommen werden. Da der Wert jedoch vom Nutzer definiert wird, empfiehlt es sich, die Möglichkeit zum Überschreiben des Namens anzubieten.
  • Seiten-URL, l:Dieser Wert kann aus dem Parameter page_location abgerufen werden, der bei jedem Ereignis automatisch vom Google Analytics 4-Browser-Tag erfasst wird. Daher sollten Sie den Nutzer nicht dazu zwingen, einen Wert manuell einzugeben.
  • Nutzer-ID, u:Im Baz Analytics-Server-Tag wird der Parameter u weder vom Nutzer angegeben noch automatisch vom Tag auf der Seite erfasst. Stattdessen wird er in einem Browser-Cookie gespeichert, damit Nutzer bei mehreren Besuchen der Website identifiziert werden können. Wie Sie in der Implementierung unten sehen, wird das Cookie über das Baz Analytics-Server-Tag mithilfe der setCookie API gesetzt. Das bedeutet, dass nur das Baz analytics-Tag weiß, wo und wie das Cookie gespeichert wird. Wie l sollte auch der Parameter u automatisch erfasst werden.

Nachdem Sie die Tag-Konfiguration abgeschlossen haben, sollte sie in etwa so aussehen:

Snapshot der Tag-Konfiguration für das Baz Analytics-Tag.

Tag-Implementierung

Nachdem die Konfiguration des Tags abgeschlossen ist, können Sie mit der Implementierung des Verhaltens in JavaScript in einer Sandbox fortfahren.

Das Tag muss vier Aufgaben erfüllen:

  1. Rufen Sie den Ereignisnamen aus der Tag-Konfiguration ab.
  2. Rufe die Seiten-URL aus der Property page_location des Ereignisses ab.
  3. Nutzer-ID berechnen Das Tag sucht nach der Nutzer-ID in einem Cookie namens _bauid. Wenn dieses Cookie nicht vorhanden ist, wird im Tag ein neuer Wert berechnet und für spätere Anfragen gespeichert.
  4. Erstellen Sie eine URL und senden Sie eine Anfrage an den Baz Analytics-Erfassungsserver.

Überlegen Sie auch, wie das Tag in den Container insgesamt passt. Unterschiedliche Containerkomponenten haben unterschiedliche Rollen. Daher gibt es auch Dinge, die das Tag nicht oder nicht tun sollte.

  • Sollte das Ereignis nicht prüfen, um festzustellen, ob es ausgeführt werden soll. Dafür gibt es einen Trigger.
  • Der Container sollte nicht mit der runContainer API ausgeführt werden. Das ist Aufgabe des Kunden.
  • Mit der wichtigen Ausnahme von Cookies sollte nicht versucht werden, direkt mit der Anfrage oder Antwort zu interagieren. Das ist auch die Aufgabe des Kunden.

Wenn Sie eine Tag-Vorlage schreiben, die eines dieser Ziele erfüllt, führt dies zu einem verwirrenden Verhalten der Nutzer Ihres Tags. Ein Tag, das beispielsweise eine Antwort auf die eingehende Anfrage sendet, würde den Client daran hindern, dasselbe zu tun. Das würde die Erwartungen der Nutzer an das Verhalten des Containers enttäuschen.

Vor diesem Hintergrund finden Sie im Folgenden eine annotierte Implementierung des Tags in JavaScript in einer Sandbox.

const encodeUriComponent = require('encodeUriComponent');
const generateRandom = require('generateRandom');
const getCookieValues = require('getCookieValues');
const getEventData = require('getEventData');
const logToConsole = require('logToConsole');
const makeString = require('makeString');
const sendHttpGet = require('sendHttpGet');
const setCookie = require('setCookie');

const USER_ID_COOKIE = '_bauid';
const MAX_USER_ID = 1000000000;

// The event name is taken from either the tag's configuration or from the
// event. Configuration data comes into the sandboxed code as a predefined
// variable called 'data'.
const eventName = data.eventName || getEventData('event_name');

// page_location is automatically collected by the Google Analytics 4 tag.
// Therefore, it's safe to take it directly from event data rather than require
// the user to specify it. Use the getEventData API to retrieve a single data
// point from the event. There's also a getAllEventData API that returns the
// entire event.
const pageLocation = getEventData('page_location');
const userId = getUserId();

const url = 'https://www.example.com/baz_analytics?' +
    'id=' + encodeUriComponent(data.measurementId) +
    'en=' + encodeUriComponent(eventName) +
    (pageLocation ? 'l=' + encodeUriComponent(pageLocation) : '') +
    'u=' + userId;

// The sendHttpGet API takes a URL and returns a promise that resolves with the
// result once the request completes. You must call data.gtmOnSuccess() or
// data.gtmOnFailure() so that the container knows when the tag has finished
// executing.
sendHttpGet(url).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
});

// The user ID is taken from a cookie, if present. If it's not present, a new ID
// is randomly generated and stored for later use.
//
// Generally speaking, tags should not interact directly with the request or
// response. This prevents different tags from conflicting with each other.
// Cookies, however, are an exception. Tags are the only container entities that
// know which cookies they need to read or write. Therefore, it's okay for tags
// to interact with them directly.
function getUserId() {
  const userId = getCookieValues(USER_ID_COOKIE)[0] || generateRandom(0, MAX_USER_ID);
  // The setCookie API adds a value to the 'cookie' header on the response.
  setCookie(USER_ID_COOKIE, makeString(userId), {
    'max-age': 3600 * 24 * 365 * 2,
    domain: 'auto',
    path: '/',
    httpOnly: true,
    secure: true,
  });

  return userId;
}

Damit ist das Tag implementiert. Bevor Sie das Tag verwenden können, müssen Sie die API-Berechtigungen richtig festlegen. Gehen Sie im Vorlageneditor zum Tab Berechtigungen und geben Sie die folgenden Berechtigungen an:

  • Liest Cookie-Werte: _bauid
  • Ereignisdaten lesen: event_name und page_location
  • Sendet HTTP-Anfragen: https://www.example.com/*
  • Setzt ein Cookie: _bauid

Sie sollten auch Tests für Ihr Tag schreiben. Weitere Informationen zu Vorlagentests finden Sie im Abschnitt Tests des Entwicklerhandbuchs für Vorlagen.

Denken Sie daran, das Tag mindestens einmal mit der Schaltfläche Code ausführen auszuführen. So lassen sich viele einfache Fehler vermeiden, die auf Ihren Server gelangen könnten.

Da Sie die ganze Arbeit zum Erstellen, Testen und Bereitstellen eines neuen Tags durchlaufen haben, gibt es keinen Grund, es für sich zu behalten. Wenn Sie der Meinung sind, dass Ihr neues Tag auch für andere Nutzer nützlich sein könnte, können Sie es in der Community-Galerie für Vorlagen einreichen.

Fazit

In diesem Tutorial haben Sie die Grundlagen zum Erstellen eines Tags für einen Servercontainer kennengelernt. Sie haben Folgendes gelernt:

  • Welche APIs verwendet werden sollen, um Ereignisdaten zu lesen, HTTP-Anfragen zu senden und Cookies im Browser zu setzen?
  • Best Practices für die Konfigurationsoptionen eines Tags
  • Der Unterschied zwischen benutzerdefinierten Daten und automatisch erfassten Daten und warum diese Unterscheidung wichtig ist.
  • Die Rolle eines Tags im Container; was es tun soll und was nicht
  • Wann und wie Sie Tag-Vorlagen in der Community-Galerie für Vorlagen einreichen können.