Google Tag Manager mit dem Braze SDK

Über Google Tag Manager für das Internet

Mit dem Google Tag Manager (GTM) können Sie per Fernzugriff Tags auf Ihrer Website hinzufügen, entfernen und bearbeiten, ohne dass eine Freigabe des Produktionscodes oder technische Ressourcen erforderlich sind. Braze bietet die folgenden Templates für das Internet-SDK an:

Tag-Sequenzierung für Braze-Aktions-Tags

Das Braze-Initialisierungs-Tag muss vor allen Tags ausgelöst werden, die Braze-SDK-Methoden aufrufen (wie braze.getUser(), braze.logCustomEvent() oder braze.logPurchase()). Wenn diese Methoden ausgelöst werden, bevor das SDK initialisiert ist, können Fehler wie Uncaught TypeError: Cannot read properties of undefined (reading 'getUser') auftreten.

So konfigurieren Sie die Tag-Sequenzierung im Google Tag Manager:

1. Öffnen Sie das Tag, das Braze-SDK-Methoden aufruft (z. B. ein Custom-HTML-Tag oder ein Braze-Aktions-Tag).
2. Gehen Sie zu Advanced Settings > Tag Sequencing.
3. Wählen Sie A tag that fires before [this tag] is fired.
4. Wählen Sie Ihr Braze Initialization-Tag aus.

Dadurch wird sichergestellt, dass das SDK vollständig geladen ist, bevor andere Tags versuchen, Braze-Methoden aufzurufen.

Weitere Informationen finden Sie unter Tag-Sequenzierung für angepasste Events überprüfen.

Käufe mit GTM protokollieren

In Braze-Aktions-Tags und Custom-HTML-Tags können Sie braze.logPurchase() aufrufen, um Umsätze zu erfassen. Der veraltete Namespace appboy.logPurchase() wird in aktuellen Internet-SDK-Integrationen nicht unterstützt.

E-Commerce-Events mit GTM protokollieren

Verwenden Sie den Tag-Typ Log eCommerce Event (New) im Braze-Aktions-Tag, um empfohlene E-Commerce-Events von Ihrem GTM-Data-Layer an Braze zu senden. Das Tag ruft braze.logEcommerceEvent() auf und erfordert Internet-SDK 6.8.0 oder höher. Stellen Sie sicher, dass Ihr Braze-Initialisierungs-Tag eine kompatible SDK-Version lädt.

Das Tag unterstützt die folgenden Events:

Um ecommerce.order_cancelled oder ecommerce.order_refunded zu protokollieren, verwenden Sie ein Custom HTML-Tag, das braze.logCustomEvent() aufruft. Beispiele finden Sie unter E-Commerce-Events protokollieren.

Hinweis

Die Tag-Typen Log Purchase (Legacy) und E-Commerce Purchase (Legacy) funktionieren weiterhin. Verwenden Sie Log eCommerce Event (New) für neue Integrationen.

Schritt 1: Event in den Data Layer pushen

Pushen Sie in Ihrem Website-Code das Event und sein ecommerce-Objekt in den Data Layer. Standardmäßig liest das Tag das Standard-GA4-E-Commerce-Data-Layer-Format. Um beispielsweise eine Bestellung zu protokollieren:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

dataLayer.push({
  event: "purchase",
  ecommerce: {
    transaction_id: "T_12345",
    value: 29.97,
    currency: "USD",
    items: [
      {
        item_id: "SKU_12345",
        item_name: "Stan and Friends Tee",
        item_variant: "green",
        price: 9.99,
        quantity: 3
      }
    ]
  }
});

Braze erwartet IDs wie item_id und transaction_id als Strings. Pushen Sie sie als Strings, auch wenn Ihre IDs numerisch sind.

Schritt 2: Trigger in GTM erstellen

1. Gehen Sie in Ihrem GTM-Container zu Triggers und erstellen Sie einen neuen Trigger.
2. Setzen Sie den Trigger Type auf Custom Event.
3. Setzen Sie den Event Name auf das Event, das Sie in den Data Layer gepusht haben (z. B. purchase).

Schritt 3: Braze-Aktions-Tag erstellen

1. Gehen Sie in GTM zu Tags und erstellen Sie ein neues Tag mit dem Tag-Typ Braze Actions Tag.
2. Setzen Sie den Tag Type auf Log eCommerce Event (New).
3. Wählen Sie einen eCommerce Event Type aus.
4. Geben Sie die Felder für diesen Event-Typ ein, wie in der folgenden Tabelle beschrieben.
5. (Optional) Fügen Sie Metadaten hinzu.
6. Wählen Sie unter Triggering den Trigger aus, den Sie in Schritt 2 erstellt haben.
7. Konfigurieren Sie die Tag-Sequenzierung, damit das Braze-Initialisierungs-Tag zuerst ausgelöst wird.
8. Speichern und veröffentlichen Sie Ihren Container.

Wenn ecommerce.currency nicht gesetzt ist, verwendet das Tag das Feld currency des ersten Elements. Das Tag setzt die Event-source auf google_tag_manager_web.

Data-Layer-Zuordnung

Wenn Automatically parse e-commerce event from the data layer ausgewählt ist (Standard), ordnet das Tag Data-Layer-Werte den Braze-Event-Eigenschaften wie folgt zu:

Event-Werte manuell eingeben

Wenn Ihre Website ein benutzerdefiniertes E-Commerce-Data-Layer-Format verwendet, deaktivieren Sie Automatically parse e-commerce event from the data layer. Geben Sie dann die Event-Werte im Tag ein. Sie können GTM-Variablen in jedem dieser Felder verwenden.

E-Commerce-Event-Metadaten

Fügen Sie Metadaten hinzu, um zusätzliche Schlüssel-Wert-Paare mit dem Event zu senden. Braze sendet Event-Metadaten im metadata-Objekt des Events und Produkt-Metadaten im metadata-Objekt jedes Produkts.

Event-Metadaten

Verwenden Sie die Tabelle eCommerce Event Metadata, um Metadaten auf Event-Ebene hinzuzufügen. Diese Tabelle ist verfügbar, unabhängig davon, ob das automatische Parsing aktiviert ist oder nicht. Geben Sie für jede Zeile einen Metadata property key und einen Metadata property value ein. Sie können eine GTM-Variable als Wert verwenden. Das Tag überspringt Zeilen mit leerem Schlüssel oder leerem Wert.

Einige Event-Typen unterstützen anerkannte Metadaten-Schlüssel. Verwenden Sie beispielsweise checkout_url für Checkout started und order_status_url für Order placed. Die vollständige Liste finden Sie unter Event-Schemas.

Produkt-Metadaten

Verwenden Sie die Spalte Product Metadata (JSON) der Tabelle Products, um Metadaten zu einem einzelnen Produkt hinzuzufügen. Geben Sie ein JSON-Objekt ein, z. B. {"color": "green", "size": "M"}. Produkt-Metadaten unterliegen den folgenden Einschränkungen:

• Produkt-Metadaten sind nur verfügbar, wenn Sie Automatically parse e-commerce event from the data layer deaktivieren.
• Das Tag sendet Produkt-Metadaten für Events vom Typ Cart Updated, Checkout started und Order placed. Für Product Viewed werden keine Produkt-Metadaten gesendet, da dieses Event kein Produkt-Array hat. Verwenden Sie stattdessen die Tabelle eCommerce Event Metadata für Product Viewed.
• Wenn das JSON kein gültiges Objekt ist, wird es vom Tag ignoriert.

E-Commerce-Events überprüfen

Das Braze Internet-SDK validiert jedes E-Commerce-Event. Wenn ein Wert ungültig ist, protokolliert das SDK das Event nicht und schreibt einen Fehler in die Browser-Konsole. GTM zeigt das Tag trotzdem als ausgelöst an. So beheben Sie ein fehlendes Event:

1. Wählen Sie im Tag Enable GTM Tag Debugging aus. Das Tag protokolliert dann eine Nachricht in der Browser-Konsole, wenn es einen Data-Layer-Wert nicht lesen kann, keine Produkte findet oder ungültige Produkt-Metadaten ignoriert.
2. Öffnen Sie die Entwicklerkonsole Ihres Browsers und suchen Sie nach Fehlern des Braze Internet-SDK.
3. Prüfen Sie die erforderlichen Felder für Ihren Event-Typ. Stellen Sie sicher, dass IDs Strings sind, dass price und total_value gültige Zahlen sind und dass quantity eine ganze Zahl ist.

Informationen zu Event-Schemas und Ingestion-Validierung finden Sie unter E-Commerce-Events protokollieren und Event-Validierung und Fehlerbehebung.

Angepasste Events mit GTM protokollieren

Sie können angepasste Events mit einem Custom HTML-Tag in GTM protokollieren. Dieser Ansatz verwendet den GTM-Data Layer, um Event-Daten von Ihrer Website an ein GTM-Tag zu übergeben, das das Braze Internet-SDK aufruft.

Schritt 1: Event in den Data Layer pushen

Pushen Sie in Ihrem Website-Code überall dort, wo Sie das angepasste Event triggern möchten, ein Event in den Data Layer. Um beispielsweise ein angepasstes Event beim Klicken eines Buttons zu protokollieren:

1

<button onclick="dataLayer.push({'event': 'my_custom_event'});">Track Event</button>

Schritt 2: Trigger in GTM erstellen

1. Gehen Sie in Ihrem GTM-Container zu Triggers und erstellen Sie einen neuen Trigger.
2. Setzen Sie den Trigger Type auf Custom Event.
3. Setzen Sie den Event Name auf denselben Wert, den Sie in den Data Layer gepusht haben (z. B. my_custom_event).
4. Wählen Sie aus, wann der Trigger ausgelöst werden soll (z. B. All Custom Events).

Schritt 3: Custom-HTML-Tag erstellen

1. Gehen Sie in GTM zu Tags und erstellen Sie ein neues Tag.
2. Setzen Sie den Tag Type auf Custom HTML.

3. Fügen Sie im HTML-Feld Folgendes hinzu:

   
   1
   2
   3
   
    <script>
    window.braze.logCustomEvent("my_custom_event");
    </script>
   
   

4. Wählen Sie unter Triggering den Trigger aus, den Sie in Schritt 2 erstellt haben.
5. Speichern und veröffentlichen Sie Ihren Container.

Um Event-Eigenschaften einzuschließen, übergeben Sie sie als zweites Argument:

1
2
3

<script>
window.braze.logCustomEvent("my_custom_event", {"property_key": "property_value"});
</script>

Strikte CSP (nonce-basierte) Umgebungen

Das Braze-Initialisierungs-Tag unterstützt derzeit nicht die Übergabe von contentSecurityNonce an braze.initialize(). Wenn Ihre Website eine strikte nonce-basierte CSP erzwingt, verwenden Sie anstelle des Braze-Initialisierungs-Tags ein Custom HTML-Tag.

1. Pausieren oder entfernen Sie das Braze-Initialisierungs-Tag aus Ihrem GTM-Container, wenn Sie es bereits eingerichtet haben.

2. Pushen Sie Ihre serverseitig generierte Nonce vor dem GTM-Snippet in Ihrem Website-HTML in den dataLayer:

   
   1
   2
   3
   4
   
    <script nonce="SERVER_GENERATED_NONCE">
      dataLayer = window.dataLayer || [];
      dataLayer.push({ cspNonce: 'SERVER_GENERATED_NONCE' });
    </script>
   
   

3. Erstellen Sie im GTM eine Data Layer Variable, die auf cspNonce gemappt ist (z. B. DLV - cspNonce).

4. Erstellen Sie ein Custom HTML-Tag mit dem Trigger Initialization - All Pages:

   Passen Sie das folgende Template an Ihre Umgebung an.

   
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   
    <script nonce="{{DLV - cspNonce}}">
      var s = document.createElement('script');
      s.src = 'https://js.appboycdn.com/web-sdk/YOUR_SDK_VERSION/braze.min.js';
      s.setAttribute('nonce', '{{DLV - cspNonce}}');
      s.onload = function() {
        braze.initialize('YOUR_API_KEY', {
          baseUrl: 'YOUR_SDK_ENDPOINT',
          contentSecurityNonce: '{{DLV - cspNonce}}'
        });
        braze.openSession();
      };
      document.head.appendChild(s);
    </script>
   
   

5. Konfigurieren Sie für das Braze-Aktions-Tag oder alle Custom HTML-Tags, die Braze-Methoden aufrufen, die Tag-Sequenzierung, damit sie nach diesem Custom HTML-Tag ausgelöst werden.

Googles EU-Richtlinie zur Nutzer:innen-Einwilligung

Wichtig

Google aktualisiert seine EU-Richtlinie zur Nutzer:innen-Einwilligung als Reaktion auf Änderungen des Digital Markets Act (DMA), der seit dem 6. März 2024 in Kraft ist. Diese Änderung verpflichtet Werbetreibende, ihren Endnutzer:innen im EWR und in Großbritannien bestimmte Informationen offenzulegen und die erforderlichen Einwilligungen einzuholen. Lesen Sie die folgende Dokumentation, um mehr zu erfahren.

Im Rahmen der EU-Richtlinie zur Nutzer:innen-Einwilligung von Google müssen die folgenden booleschen angepassten Attribute in den Nutzerprofilen protokolliert werden:

• $google_ad_user_data
• $google_ad_personalization

Wenn Sie diese über die GTM-Integration festlegen, erfordern angepasste Attribute die Erstellung eines Custom-HTML-Tags. Das folgende Beispiel zeigt, wie Sie diese Werte als boolesche Datentypen (nicht als Strings) protokollieren:

1
2
3

<script>
window.braze.getUser().setCustomUserAttribute("$google_ad_personalization", true);
</script>

Weitere Informationen finden Sie unter Zielgruppensynchronisierung mit Google.