Auf Basis meines Beitrags “Der Client im Google Tag Manager-Server” möchte ich nun näher auf die runContainer API eingehen.

runContainer

Auf Basis eines Events führt runContainer die komplette Container-Logik aus. Die Container-Logik besteht dabei aus den definierten Tags, Triggern und Variablen. Als Bindeglied zwischen dem Event-Daten-Objekt und den Tags sorgt runContainer dafür, dass die Event-Daten an die Tags übergeben werden.

Beispiel und Syntax

runContainer nimmt 3 Parameter entgegen:

runContainer(event, onComplete, onStart);

Zur Erklärung:

• event: Nimmt die Event-Parameter als Objekt entgegen.
• onComplete: Ist eine Callback-Funktion und wird ausgeführt, sobald alle Tags gefeuert wurden.
• onStart: Ist eine Callback-Funktion und wird ausgeführt, bevor die Tags anfangen zu feuern.

Nachfolgend ein Beispiel. Zunächst ein Basis-Client, der nur die entsprechenden APIs importiert, den Request beansprucht und ein Event-Daten-Objekt daraus macht:

const claimRequest = require('claimRequest');
const getPathFromRequest = require('getRequestPath');
const getQueryParams = require('getRequestQueryParameters');
const returnResponse = require('returnResponse');
const runContainer = require('runContainer');
const setResponseBody = require('setResponseBody');
const setResponseStatus = require('setResponseStatus');
 
if (getPathFromRequest() === '/hit/') {
  claimRequest();
 
  const event = {
    event_name: getQueryParams().en,
    client_id: getQueryParams().cid,
    language: getQueryParams().lg
  };
 
}


Nun wird der Code um die runContainer API erweitert:

const claimRequest = require('claimRequest');
const getPathFromRequest = require('getRequestPath');
const getQueryParams = require('getRequestQueryParameters');
const returnResponse = require('returnResponse');
const runContainer = require('runContainer');
const setResponseBody = require('setResponseBody');
const setResponseStatus = require('setResponseStatus');
 
if (getPathFromRequest() === '/hit/') {
  claimRequest();
 
  const event = {
    event_name: getQueryParams().en,
    client_id: getQueryParams().cid,
    language: getQueryParams().lg
  };
 
runContainer(event, () => {
  setResponseStatus(200);
  setResponseBody('Request successfully claimed.');
  returnResponse();
  });
}


Hier sieht man, dass der erste Parameter eine Variable “event” entgegennimmt. Dabei handelt es sich um das Objekt der Event-Parameter. Der zweite Parameter ist eine Funktion, die ausgeführt wird, sobald alle Tags gefeuert wurden (onComplete). Hier wird der entsprechende Status Code, Body und der Response zurückgeliefert.

runContainer API im Detail erklärt

Gehen wir den Ablauf nochmal im Detail durch. Grundsätzlich kommt zunächst ein Request rein – entweder vom Browser über die gtm.js-Bibliothek oder über das Measurement Protocol:

Im Server-Container hält ein Client Ausschau nach eingehenden Request:

Sobald der Request bestimmten Bedingungen entspricht, beansprucht der Client den Request für sich (claimRequest API). Das passiert z.B. über folgende Zeile im Client:

if (getPathFromRequest() === '/hit/') {
  claimRequest();
};

Der Client beansprucht also den Request für sich:

Im Anschluss wird das Ereignisobjekt “gebaut”:

Dieses Ereignisobjekt wird dann an die runContainer API übergeben. Über diese API wird das Event (bzw. Event-Objekt) an die Tags übergeben. Im Preview-Modus des Server-Containers ist das Ergebnis im Tab “Event Data” zu sehen. Diese Struktur kann man sich so ähnlich wie einen dataLayer vorstellen. Entspricht aber nicht dem dataLayer! Es ist eher ein virtueller Container, der erstellt wird. Diesen brauchen die Tags im Server-Container, damit sie auf Basis von Triggern ausgelöst werden können. Die Tags werten diesen virtuellen Container also aus, um darauf über die Trigger zu reagieren bzw. auszulösen.

Somit hätten wir folgendes Bild:

runContainer wandelt also das nachfolgende Objekt um. Aus…:

const event = {
  event_name: getQueryParams().en,
  client_id: getQueryParams().cid,
  language: getQueryParams().lg
};

…wird dann:

const event = {
  event_name: page_view,
  client_id: 12345,
  language: en_us
};

Wenn wir davon ausgehen, dass der eingehende Request als “cid=12345&en=page_view&lg=en_us” reinkommt (siehe im Beitrag “Der Client im Google Tag Manager-Server” ausführlich beschrieben), dann ist das Endergebnis, womit dann auch die Tags und Trigger arbeiten können, im Preview-Modus im Tab “Event Data” zu finden: