Server-Tag erstellen

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

In einem Servercontainer empfangen Tags eingehende Ereignisdaten von Ihren Clients, wandeln sie um und senden sie zur Erfassung und Analyse zurück. Mit Tags können Sie die Daten an einen beliebigen Ort senden. Solange das Ziel HTTP-Anfragen akzeptiert, können auch Daten von einem Servercontainer empfangen werden.

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

  • Google Analytics 4
  • Google Analytics: Universal Analytics
  • 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. In der Community-Galerie für Vorlagen finden Sie zusätzliche Tags. Sie können aber auch eigene Tags erstellen. In dieser Anleitung lernen Sie die Grundlagen zum Schreiben eigener Tags für einen Servercontainer kennen.

Zielsetzungen

  • Hier erfahren Sie, welche APIs zum Lesen von Ereignisdaten, Senden von HTTP-Anfragen und Setzen von Cookies im Browser verwendet werden müssen.
  • Hier finden Sie Best Practices zum Entwerfen der Konfigurationsoptionen für Ihr Tag.
  • Hier erfahren Sie mehr über den Unterschied zwischen benutzerdefinierten und automatisch erfassten Daten und darüber, warum diese Unterscheidung wichtig ist.
  • Hier erfahren Sie mehr über die Rolle eines Tags in einem Servercontainer. Verstehen Sie, was ein Tag tun sollte und was nicht.
  • In der Community-Galerie für Vorlagen erfahren Sie, wann Sie eine Tag-Vorlage einreichen sollten.

Voraussetzungen

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. Er hat folgende Parameter:

Parameter Beispiel Beschreibung
id BA-1234 Die ID Ihres Baz Analytics-Kontos.
en click Ereignisname
l https://www.google.com/search?q=sgtm Die URL der Seite, auf der das Ereignis aufgetreten ist.
u 2384294892 Die ID des Nutzers, der die Aktion ausführt. Damit werden mehrere Aktionen mit einem einzelnen Nutzer verknüpft.

Tag-Konfiguration

Als Erstes erstellen Sie die Tag-Vorlage. Wechseln Sie zum Bereich Vorlagen des Containers und klicken Sie unter Tag-Vorlagen auf Neu. Fügen Sie dem Tag einen Namen und eine Beschreibung hinzu.

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

  1. Konfiguration insgesamt: Fügen Sie für jeden Parameter ein Konfigurationsfeld hinzu. Nutzer müssen alles explizit festlegen.
  2. Keine Konfiguration: Sie haben keine Optionen, das Tag zu konfigurieren. Alle Daten werden direkt aus dem Ereignis entnommen.
  3. Eine bestimmte Konfiguration: Enthält Felder für einige Parameter und nicht für andere.

Felder für jeden Parameter sind sehr flexibel und geben dem Nutzer die volle Kontrolle über die Tag-Konfiguration. In der Praxis führt dies jedoch in der Regel zu vielen Duplizierungen. Insbesondere sind Elemente wie der l-Parameter von Baz Analytics, der die URL der Seite enthält, eindeutig und universell. Am besten ist es, wenn der Computer bei jeder Konfiguration des Tags dieselben, unveränderlichen Daten eingegeben hat.

Vielleicht besteht die Antwort darin, ein Tag zu haben, das nur Daten von einem Ereignis abruft. Dies ist das am einfachsten mögliche Tag, das ein Nutzer konfigurieren kann, da er nichts tun muss. Andererseits ist es auch die restriktivste und instabilste Option. Nutzer können das Verhalten des Tags selbst bei Bedarf nicht ändern. Beispielsweise kann ein Ereignis auf seiner Website und in Google Analytics purchase aufgerufen werden, Baz Analytics nennt es aber buy. Oder vielleicht stimmen die Annahmen, die das Tag über die Struktur der eingehenden Ereignisdaten trifft, nicht mit der Realität überein. In beiden Fällen bleibt der Nutzer hängen.

Wie so oft auch, liegt die Antwort irgendwo zwischen den beiden Extremen. Einige Daten sind sinnvoll, immer aus dem Ereignis zu nehmen. Andere Daten sollten vom Nutzenden konfiguriert werden. Wie entscheiden Sie, welche das ist? Um diese Frage zu beantworten, müssen wir uns die in den Container eingehenden Daten genauer ansehen.

Woher stammen die Daten?

Die über das Google Analytics 4-Tag in einen Servercontainer eingehenden Daten lassen sich grob in zwei Kategorien unterteilen: benutzerdefinierte Daten und automatisch erhobene Daten.

Benutzerdefinierte Daten sind alles, was ein Nutzer in einen gtag.js-event-Befehl eingibt. Beispiel:

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

Führt im Servercontainer zu folgenden Parametern:

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

Das ist einfach genug, aber aus Sicht des Tags ist es sehr schwierig, damit zu arbeiten. Da diese Daten vom Nutzer eingegeben werden, können sie beliebig sein. Wie oben erwähnt, sendet der Nutzer möglicherweise nur empfohlene Ereignisse und Parameter, muss dies aber nicht tun. Mit Ausnahme des Standorts (aber nicht des Werts) des event_name-Parameters gibt es keine Garantie bezüglich der Form oder Struktur der Nutzerdaten.

Glücklicherweise erhält der Container nicht nur vom Nutzer eingegebene Daten. Außerdem erhält es eine Reihe von Daten, die automatisch über das Google Analytics 4-Tag im Browser erfasst 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 Cookie-Daten des Browsers über die getCookieValue API verfügbar.

Diese bilden zusammen die automatisch erfassten Daten, die wir oben erwähnt haben. Im Allgemeinen besteht sie aus universellen und semantisch eindeutigen Daten. Wenn eine Anfrage über ein 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 Ereignisreferenz.

Diese Klassifizierung ist ein nützliches Tool, mit dem wir entscheiden können, welche Daten vom Nutzer konfiguriert und welche im Tag angegeben werden sollen. Automatisch erhobene Daten können bedenkenlos direkt aus dem Ereignis gelesen werden. Alle anderen Elemente müssen vom Nutzer konfiguriert werden.

Sehen Sie sich vor diesem Hintergrund noch einmal die Parameter für das Baz Analytics-Tag an.

  • Mess-ID, id:Da sie nicht automatisch erfasst wird, ist dies ein klares Beispiel für einen Wert, den der Nutzer beim Konfigurieren des Tags eingeben sollte.
  • Ereignisname en:Wie bereits oben erwähnt, kann der Ereignisname immer direkt aus dem Parameter event_name übernommen werden. Da sein Wert jedoch vom Nutzer definiert ist, empfiehlt es sich, bei Bedarf die Möglichkeit anzubieten, den Namen zu überschreiben.
  • Seiten-URL l:Dieser Wert kann dem Parameter page_location entnommen werden, der über das GA4-Browser-Tag von Google Analytics automatisch bei jedem Ereignis erfasst wird. Daher sollte der Nutzer keinen Wert manuell eingeben müssen.
  • User-ID, u:Im Baz Analytics-Server-Tag wird der Parameter u vom Tag auf der Seite weder vom Nutzer angegeben noch automatisch erfasst. Stattdessen werden sie in einem Browser-Cookie gespeichert, damit Nutzer bei mehreren Besuchen auf der Website identifiziert werden können. Wie Sie in der Implementierung unten sehen, ist es das Baz Analytics-Server-Tag, das die setCookie API verwendet, um das Cookie zu setzen. Das bedeutet, dass nur das Baz Analytics-Tag weiß, wo und wie das Cookie gespeichert wird. Wie bei l sollte auch der Parameter u automatisch erfasst werden.

Sobald Sie die Tag-Konfiguration eingerichtet haben, sollte sie in etwa so aussehen:

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

Tag-Implementierung

Die Tag-Konfiguration ist jetzt abgeschlossen und Sie können die Funktionsweise in JavaScript in einer Sandbox implementieren.

Das Tag muss vier Dinge tun:

  1. Rufen Sie den Ereignisnamen aus der Tag-Konfiguration ab.
  2. Rufen Sie die Seiten-URL aus der page_location-Eigenschaft des Ereignisses ab.
  3. Berechnen Sie eine User-ID. Das Tag sucht in einem Cookie mit dem Namen _bauid nach der User-ID. Wenn dieses Cookie nicht vorhanden ist, berechnet das Tag einen neuen Wert und speichert ihn für spätere Anfragen.
  4. Erstellen Sie eine URL und senden Sie eine Anfrage an den Baz Analytics-Datenerfassungsserver.

Sie sollten sich auch einen Moment Zeit nehmen, um darüber nachzudenken, wie das Tag in den gesamten Container passt. Unterschiedliche Containerkomponenten spielen unterschiedliche Rollen. Daher gibt es auch Dinge, die das Tag nicht erfüllt oder nicht tun sollte. Ihr Tag:

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

Das Erstellen einer Tag-Vorlage, die eine dieser Dinge erfüllt, würde zu einem verwirrenden Verhalten für Nutzer Ihres Tags führen. Beispielsweise würde ein Tag, das eine Antwort auf die eingehende Anfrage sendet, verhindern, dass der Client dies ebenfalls tut. Das würde die Erwartungen der Nutzer in Bezug auf das Verhalten des Containers verletzen.

Vor diesem Hintergrund finden Sie unten eine kommentierte Implementierung des Tags in JS, das in einer Sandbox ausgeführt wird.

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 seine API-Berechtigungen richtig festlegen. Gehen Sie zum Tab Berechtigungen des Vorlageneditors und geben Sie die folgenden Berechtigungen an:

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

Sie sollten auch Tests für Ihr Tag schreiben. Weitere Informationen zum Testen von Vorlagen finden Sie im Entwicklerleitfaden für Vorlagen im Abschnitt "Tests".

Vergessen Sie nicht, das Tag mindestens einmal über die Schaltfläche Code ausführen auszuführen. Dadurch wird verhindert, dass viele einfache Fehler auf Ihrem Server auftreten.

Da Sie die gesamte Arbeit zum Erstellen, Testen und Bereitstellen eines neuen Tags ausgeführt 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 dieser Anleitung haben Sie die Grundlagen zum Schreiben eines Tags für einen Servercontainer kennengelernt. Sie haben Folgendes gelernt:

  • Welche APIs verwendet werden, um Ereignisdaten zu lesen, HTTP-Anfragen zu senden und Cookies im Browser zu setzen?
  • Best Practices für die Gestaltung der Konfigurationsoptionen für Tags
  • Der Unterschied zwischen benutzerdefinierten und automatisch erfassten Daten und die Bedeutung dieser Unterscheidung.
  • Die Rolle eines Tags im Container im Klaren darüber, was es tun sollte und was nicht.
  • Wann und wie Sie Tag-Vorlagen in der Community-Galerie für Vorlagen einreichen