Google Sheets Lookup Variablen-Template für den Server Side GTM

Mit dem Google Sheets Lookup Variablen-Template kannst du ein Google Sheet als Lookup-Tabelle in deinem Server Side Google Tag Manager verwenden. Anhand eines Schlüsselwerts (z. B. einer Produkt-SKU) wird die passende Zeile im Sheet gesucht und der Wert aus einer anderen Spalte zurückgegeben — etwa eine Gewinnmarge oder eine Produktkategorie.

Voraussetzungen

Bevor du das Template nutzen kannst, brauchst du einen Google Service Account, der mit deinem SGTM Container verbunden ist. Der Service Account ermöglicht es dem Server Container, sich gegenüber der Google Sheets API zu authentifizieren.

Google Service Account in owntag einrichten

Wenn du owntag als Hosting für deinen Server Side GTM nutzt, kannst du den Google Service Account Key direkt in der owntag Console hochladen. Navigiere dazu zu deinem Container und wähle im Seitenmenü Google Service Account aus:

Google Service Account Upload in der owntag Console

Eine ausführliche Anleitung, wie du den Service Account in der Google Cloud Platform erstellst und welche Berechtigungen er benötigt, findest du in der owntag Dokumentation zum Google Service Account.

Sobald der Key hochgeladen ist, zeigt dir die owntag Console die Client Email des Service Accounts an. Diese E-Mail-Adresse brauchst du im nächsten Schritt.

Client Email des Service Accounts in der owntag Console

Google Sheet vorbereiten

Erstell ein Google Sheet mit mindestens zwei Spalten: eine für den Schlüssel, nach dem gesucht werden soll (z. B. eine Produkt-SKU), und eine für den Wert, der zurückgegeben werden soll (z. B. eine Gewinnmarge). Die erste Zeile sollte Spaltenüberschriften enthalten.

Hier ein Beispiel für ein einfaches Produkt-Sheet:

Beispiel-Google-Sheet mit SKU- und Profit-Spalten, annotiert mit Sheet ID, Spaltennummern und Sheet-Name

Notier dir folgende Werte — du brauchst sie gleich bei der Konfiguration der Variable:

Spreadsheet ID: Der lange String in der URL zwischen /d/ und /edit, z. B. 1KfxE7VtsY-ctpFA70g42DUtxow7NUPV5YtG-GDGeeAs
Sheet Name: Der Name des Tabs am unteren Rand des Spreadsheets, z. B. products
Key Column (Nummer): Die Spalte, die den Suchschlüssel enthält (1 = Spalte A, 2 = Spalte B, usw.)
Return Column (Nummer): Die Spalte, deren Wert zurückgegeben werden soll

Sheet für den Service Account freigeben

Das Google Sheet muss für deinen Service Account freigegeben werden — genauso, als wäre es ein echter Nutzer. Öffne die Freigabeeinstellungen deines Spreadsheets und füge die Client Email des Service Accounts (die in der owntag Console angezeigt wird) als Betrachter oder Bearbeiter hinzu.

Template importieren

Lade die Template-Datei (template.tpl) aus dem GitHub Repository herunter.

In deinem Google Tag Manager Server Side Container gehst du in den Bereich Vorlagen. Unter Variablenvorlagen klickst du auf Neu und importierst die heruntergeladene Datei.

Variable konfigurieren

Nachdem du das Template importiert hast, legst du im Bereich Variablen eine neue Variable an. Wähle als Variablentyp das owntag Google Sheets Lookup Template aus.

Trag die Werte ein, die du dir aus deinem Google Sheet notiert hast:

Spreadsheet ID: Die ID aus der Sheet-URL
Sheet Name: Der Tab-Name in deinem Spreadsheet
Lookup Value: Der Wert, nach dem in der Key Column gesucht werden soll — in der Regel eine GTM-Variable wie {{ecommerce.0.item_id}}, die zur Laufzeit die Produkt-SKU oder -ID enthält
Key Column (number): Die Spaltennummer, in der gesucht wird (z. B. 1 für Spalte A)
Return Column (number): Die Spaltennummer, deren Wert zurückgegeben werden soll (z. B. 2 für Spalte B)

Variablen-Konfiguration im GTM mit Spreadsheet ID, Sheet Name, Lookup Value, Key Column und Return Column

Im Screenshot oben ist die Variable so konfiguriert, dass der Wert abc-1 in Spalte 1 des Sheets products gesucht wird und der zugehörige Wert aus Spalte 2 zurückgegeben wird. Die Konsole unten bestätigt, dass ein Treffer in Zeile 1 gefunden wurde und der Profit-Wert 4.38 zurückgegeben wird.

In der Praxis würdest du statt eines fest eingetragenen Werts natürlich eine GTM-Variable verwenden, die dynamisch die SKU oder ID des Produkts liefert, z. B. {{ecommerce.0.item_id}}.

Return Type

Standardmäßig gibt die Variable einen String zurück. Wenn du einen numerischen Wert brauchst (z. B. um den Profit-Wert in Berechnungen zu verwenden oder als numerischen Event-Parameter weiterzugeben), stell den Return type auf Number um.

Caching

Um die Anzahl der API-Aufrufe an Google Sheets zu reduzieren, kannst du Caching aktivieren. Dabei werden die Sheet-Daten einmalig abgerufen und für eine konfigurierbare Dauer zwischengespeichert (Standard: 5 Minuten). Alle weiteren Lookups in diesem Zeitraum greifen auf die gecachten Daten zurück, ohne zusätzliche API-Aufrufe.

Für den Produktivbetrieb ist das empfehlenswert, besonders wenn sich deine Sheet-Daten nicht ständig ändern. Die Cache-Dauer kannst du je nach Aktualisierungshäufigkeit deiner Daten anpassen.

Troubleshooting

Falls die Variable keinen Wert zurückgibt, obwohl du einen erwartest, prüf folgende Punkte:

Service Account Key: Stell sicher, dass ein gültiger Google Service Account Key in der owntag Console hinterlegt ist (bzw. in deiner SGTM-Umgebung konfiguriert ist)
Sheet-Freigabe: Überprüfe, ob das Google Sheet für die E-Mail-Adresse des Service Accounts freigegeben ist
Spreadsheet ID: Vergleiche die ID in deiner Variablen-Konfiguration mit der in der Sheet-URL
Sheet Name: Der Sheet-Name muss exakt übereinstimmen (Groß-/Kleinschreibung beachten)
Spaltennummern: Spalten werden ab 1 gezählt (Spalte A = 1, Spalte B = 2)
Preview Mode: Nutze den Vorschaumodus im Server Side GTM, um die Konsolenausgaben der Variable zu sehen — dort wird der Lookup-Prozess Schritt für Schritt protokolliert, inklusive eventueller Fehler

Google Sheets Lookup