Server-Tag erstellen

In der Einführung zum serverseitigen Tagging, haben Sie einen Überblick über das serverseitige Tagging in Tag Manager erhalten. Sie haben erfahren, was Clients sind und was sie tun: Clients empfangen Ereignisdaten von den Geräten Ihrer Nutzer und passen sie für die Verwendung durch die übrigen Containerkomponenten an. In diesem Artikel wird beschrieben, 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. Tags können die Daten an jeden beliebigen Ort senden. 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
• HTTP-Anfrage

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

Ziele

• Sie erfahren, welche APIs Sie verwenden können, um Ereignisdaten zu lesen, HTTP-Anfragen zu senden und Cookies im Browser zu setzen.
• Sie lernen Best Practices für das Design der Konfigurationsoptionen Ihres Tags kennen.
• Sie erfahren mehr über den Unterschied zwischen von Nutzern angegebenen und automatisch erfassten Daten und warum diese Unterscheidung wichtig ist.
• Sie lernen die Rolle eines Tags in einem Servercontainer kennen. Sie erfahren, was ein Tag tun sollte und was nicht.
• Sie erfahren, wann Sie eine Tag-Vorlage an die Community-Galerie für Vorlagen senden sollten.

Vorbereitung

• Ein bereitgestellter Servercontainer
• Kenntnisse in Tag Manager, Server containern und den zugehörigen grundlegenden Konzepten wie Clients, Tags, Triggern und Variablen
• Kenntnisse der Grundlagen zum Erstellen von Vorlagen für Tags und Variablen

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 die folgenden Parameter:

Tag-Konfiguration

Als Erstes müssen Sie die Tag-Vorlage erstellen. Rufen Sie den Bereich Vorlagen Ihres Containers auf und klicken Sie im Bereich Tag-Vorlagen auf Neu. Fügen Sie Ihrem Tag einen Namen und eine Beschreibung hinzu.

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

1. Vollständige Konfiguration: Fügen Sie für jeden Parameter ein Konfigurationsfeld hinzu. Der Nutzer muss alles explizit festlegen.
2. Keine Konfiguration: Es gibt keine Optionen zum Konfigurieren des Tags. Alle Daten werden direkt aus dem Ereignis übernommen.
3. Teilweise Konfiguration: Es gibt Felder für einige Parameter, aber nicht für alle.

Felder für jeden Parameter bieten viel Flexibilität und geben dem Nutzer die vollständige Kontrolle über die Tag-Konfiguration. In der Praxis führt dies jedoch in der Regel zu viel doppelter Arbeit. Insbesondere Dinge wie der Baz Analytics-Parameter l, der die URL der Seite enthält, sind eindeutig und universell. Das Eingeben derselben unveränderlichen Daten bei jeder Konfiguration des Tags sollte dem Computer überlassen werden.

Vielleicht ist es besser, ein Tag zu verwenden, das nur Daten aus einem Ereignis übernimmt. Dies ist das einfachste Tag, das ein Nutzer konfigurieren kann, da er nichts tun muss. Andererseits ist es auch die restriktivste und anfälligste Option. Nutzer können das Verhalten des Tags nicht ändern, auch wenn es erforderlich ist. Vielleicht rufen sie beispielsweise ein Ereignis purchase auf ihrer Website und in Google Analytics auf, aber Baz Analytics nennt es buy. Oder die Annahmen, die das Tag über die Struktur der eingehenden Ereignisdaten trifft, stimmen nicht mit der Realität überein. In beiden Fällen ist der Nutzer eingeschränkt.

Wie so oft liegt die Antwort irgendwo zwischen den beiden Extremen. Bei einigen Daten ist es sinnvoll, sie immer aus dem Ereignis zu übernehmen. Andere Daten sollten vom Nutzer konfiguriert werden. Wie entscheiden Sie, welche Daten in welche Kategorie fallen? 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-Tag in einen Servercontainer eingehen, lassen sich grob in zwei Kategorien unterteilen: von Nutzern angegebene Daten und automatisch erfasste Daten.

Von Nutzern angegebene Daten sind alle Daten, die ein Nutzer in einen event-Befehl von gtag.js 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 einfach genug, aber aus Sicht des Tags ist es sehr schwierig, damit zu arbeiten. Da diese Daten vom Nutzer eingegeben werden, können sie alles sein. Vielleicht sendet der Nutzer wie oben nur empfohlene Ereignisse und Parameter, aber es gibt keine Anforderung, dass er dies tut. Mit der wichtigen Ausnahme des Ortes (aber nicht des Werts!) des event_name Parameters gibt es keine Garantien hinsichtlich der Form oder Struktur der Daten des Nutzers.

Glücklicherweise sind vom Nutzer eingegebene Daten nicht die einzigen Daten, die der Container empfängt. Er erhält auch eine Reihe von Daten, die automatisch vom Google Analytics-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 Browser-Cookie-Daten über die getCookieValue-API verfügbar.

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

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

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

• Mess-ID, id: Da sie nicht automatisch erfasst wird, ist sie ein klares 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 event_name Parameter übernommen werden. Da der Wert jedoch vom Nutzer definiert wird, ist es eine gute Idee, die Möglichkeit zu bieten, den Namen bei Bedarf zu überschreiben.
• Seiten-URL, l: Dieser Wert kann aus dem page_location Parameter übernommen werden, der bei jedem Ereignis automatisch vom Google Analytics-Browser Tag erfasst wird. Daher sollten Sie den Nutzer nicht dazu auffordern, 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 vom Baz Analytics-Server-Tag mit der setCookie API gesetzt. Das bedeutet, dass nur das Baz Analytics-Tag weiß, wo und wie das Cookie gespeichert wird. Wie l, der u Parameter sollte automatisch erfasst werden.

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

Tag-Implementierung

Nachdem die Konfiguration des Tags abgeschlossen ist, können Sie sein Verhalten in Sandboxed JavaScript implementieren.

Das Tag muss vier Dinge tun:

1. Den Ereignisnamen aus der Konfiguration des Tags abrufen.
2. Die Seiten-URL aus dem Attribut page_location des Ereignisses abrufen.
3. Eine Nutzer-ID berechnen. Das Tag sucht nach der Nutzer-ID in einem Cookie namens _bauid. Wenn dieses Cookie nicht vorhanden ist, berechnet das Tag einen neuen Wert und speichert ihn für spätere Anfragen.
4. Eine URL erstellen und eine Anfrage an den Baz Analytics-Erfassungsserver senden.

Nehmen Sie sich auch einen Moment Zeit, um darüber nachzudenken, wie das Tag in den Container als Ganzes passt. Verschiedene Containerkomponenten haben unterschiedliche Rollen. Daher gibt es auch Dinge, die das Tag nicht tut oder nicht tun sollte. Ihr Tag:

• Sollte das Ereignis nicht untersuchen, um herauszufinden, ob es ausgeführt werden soll. Dafür ist ein Trigger vorgesehen.
• Sollte den Container nicht mit der runContainer-API ausführen. Das ist die Aufgabe des Clients.
• Mit der wichtigen Ausnahme von Cookies sollte es nicht versuchen, direkt mit der Anfrage oder Antwort zu interagieren. Das ist auch die Aufgabe des Clients.

Wenn Sie eine Tag-Vorlage erstellen, die eine dieser Aktionen ausführt, führt dies zu verwirrendem Verhalten für die Nutzer Ihres Tags. Ein Tag, das beispielsweise eine Antwort auf die eingehende Anfrage sendet, verhindert, dass der Client dasselbe tut. Das würde die Erwartungen der Nutzer an das Verhalten des Containers enttäuschen.

Vor diesem Hintergrund finden Sie unten eine kommentierte Implementierung des Tags in Sandboxed JavaScript.

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 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. Wechseln Sie im Vorlageneditor zum Tab Berechtigungen 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/*
• Cookie setzen: _bauid

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

Vergessen Sie nicht, Ihr Tag mindestens einmal mit der Schaltfläche Code ausführen auszuführen. So können Sie viele einfache Fehler vermeiden, die sonst auf Ihrem Server landen.

Tag an die Community-Galerie für Vorlagen senden

Da Sie sich die Mühe gemacht haben, ein neues Tag zu erstellen, zu testen und bereitzustellen, gibt es keinen Grund, es für sich zu behalten. Wenn Sie der Meinung sind, dass Ihr neues Tag für andere Nutzer nützlich sein könnte, ziehen Sie in Betracht, esan die Community-Galerie für Vorlagen zu senden.

Fazit

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

• Welche APIs Sie verwenden können, um Ereignisdaten zu lesen, HTTP-Anfragen zu senden und Cookies im Browser zu setzen.
• Best Practices für das Design der Konfigurationsoptionen für ein Tag.
• Den Unterschied zwischen von Nutzern angegebenen und automatisch erfassten Daten und warum diese Unterscheidung wichtig ist.
• Die Rolle eines Tags im Container und was es tun sollte und was nicht.
• Wann und wie Sie Tag-Vorlagen an die Community-Galerie für Vorlagen senden.