Google Tag Manager with the Braze SDK

About Google Tag Manager for Web

Google Tag Manager (GTM) lets you remotely add, remove, and edit tags on your website without requiring a production code release or engineering resources. Braze offers the following templates for the Web SDK:

Tag sequencing for Braze action tags

The Braze Initialization tag must fire before any tags that call Braze SDK methods (such as braze.getUser(), braze.logCustomEvent(), or braze.logPurchase()). If these methods fire before the SDK is initialized, you may encounter errors like Uncaught TypeError: Cannot read properties of undefined (reading 'getUser').

To configure tag sequencing in Google Tag Manager:

1. Open the tag that calls Braze SDK methods (such as a Custom HTML tag or Braze action tag).
2. Go to Advanced Settings > Tag Sequencing.
3. Select A tag that fires before [this tag] is fired.
4. Choose your Braze Initialization tag.

This ensures the SDK is fully loaded before any other tags attempt to call Braze methods.

For more detail, see Verify tag sequencing for custom events.

Log purchases with GTM

In Braze action tags and Custom HTML tags, call braze.logPurchase() to record revenue. The legacy appboy.logPurchase() namespace is not supported in current Web SDK integrations.

Log eCommerce events with GTM

Use the Log eCommerce Event (New) tag type in the Braze Actions tag to send eCommerce recommended events to Braze from your GTM data layer. The tag calls braze.logEcommerceEvent() and requires Web SDK 6.8.0 or later. Make sure your Braze Initialization tag loads a compatible SDK version.

The tag supports the following events:

To log ecommerce.order_cancelled or ecommerce.order_refunded, use a Custom HTML tag that calls braze.logCustomEvent(). For examples, see Log eCommerce events.

note

The Log Purchase (Legacy) and E-Commerce Purchase (Legacy) tag types continue to work. Use Log eCommerce Event (New) for new integrations.

Step 1: Push the event to the data layer

In your site’s code, push the event and its ecommerce object to the data layer. By default, the tag reads the standard GA4 eCommerce data layer format. For example, to log an order:

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 requires IDs such as item_id and transaction_id to be strings. Push them as strings, even if your IDs are numeric.

Step 2: Create a trigger in GTM

1. In your GTM container, go to Triggers and create a new trigger.
2. Set the Trigger Type to Custom Event.
3. Set the Event Name to the event you pushed to the data layer (for example, purchase).

Step 3: Create the Braze Actions tag

1. In GTM, go to Tags and create a new tag with the Braze Actions Tag type.
2. Set Tag Type to Log eCommerce Event (New).
3. Select an eCommerce Event Type.
4. Enter the fields for that event type, as described in the following table.
5. (Optional) Add metadata.
6. Under Triggering, select the trigger you created in step 2.
7. Configure tag sequencing so the Braze Initialization tag fires first.
8. Save and publish your container.

If ecommerce.currency is not set, the tag uses the currency field of the first item. The tag sets the event source to google_tag_manager_web.

Data layer mapping

When Automatically parse e-commerce event from the data layer is selected (the default), the tag maps data layer values to the Braze event properties as follows:

Enter event values manually

If your site uses a custom eCommerce data layer format, clear Automatically parse e-commerce event from the data layer. Then enter the event values in the tag. You can use GTM variables in any of these fields.

eCommerce event metadata

Add metadata to send additional key-value pairs with the event. Braze sends event metadata in the metadata object of the event, and product metadata in the metadata object of each product.

Event metadata

Use the eCommerce Event Metadata table to add event-level metadata. This table is available whether or not automatic parsing is turned on. For each row, enter a Metadata property key and a Metadata property value. You can use a GTM variable as the value. The tag skips rows that have an empty key or an empty value.

Some event types support recognized metadata keys. For example, use checkout_url for Checkout started and order_status_url for Order placed. For the full list, see Event schemas.

Product metadata

Use the Product Metadata (JSON) column of the Products table to add metadata to an individual product. Enter a JSON object, such as {"color": "green", "size": "M"}. Product metadata has the following limitations:

• Product metadata is only available when you clear Automatically parse e-commerce event from the data layer.
• The tag sends product metadata for Cart Updated, Checkout started, and Order placed events. It does not send product metadata for Product Viewed, because that event has no products array. Use the eCommerce Event Metadata table for Product Viewed instead.
• If the JSON is not a valid object, the tag ignores it.

Verify eCommerce events

The Braze Web SDK validates every eCommerce event. If a value is invalid, the SDK doesn’t log the event and writes an error to the browser console. GTM still shows the tag as fired. To troubleshoot a missing event:

1. Select Enable GTM Tag Debugging in the tag. The tag then logs a message to the browser console when it can’t read a data layer value, finds no products, or ignores invalid product metadata.
2. Open your browser’s developer console and look for errors from the Braze Web SDK.
3. Check the required fields for your event type. Confirm that IDs are strings, that price and total_value are valid numbers, and that quantity is a whole number.

For event schemas and ingestion validation, see Log eCommerce events and Event validation and troubleshooting.

Logging custom events with GTM

You can log custom events using a Custom HTML tag in GTM. This approach uses the GTM data layer to pass event data from your site to a GTM tag that calls the Braze Web SDK.

Step 1: Push the event to the data layer

In your site’s code, push an event to the data layer wherever you want to trigger the custom event. For example, to log a custom event when a button is clicked:

1

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

Step 2: Create a trigger in GTM

1. In your GTM container, go to Triggers and create a new trigger.
2. Set the Trigger Type to Custom Event.
3. Set the Event Name to the same value you pushed to the data layer (for example, my_custom_event).
4. Choose when the trigger should fire (for example, All Custom Events).

Step 3: Create a Custom HTML tag

1. In GTM, go to Tags and create a new tag.
2. Set the Tag Type to Custom HTML.

3. In the HTML field, add the following:

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

4. Under Triggering, select the trigger you created in step 2.
5. Save and publish your container.

To include event properties, pass them as the second argument:

1
2
3

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

Strict CSP (nonce-based) environments

The Braze Initialization tag does not currently support passing contentSecurityNonce to braze.initialize(). If your site enforces a strict nonce-based CSP, use a Custom HTML tag instead of the Braze Initialization tag.

1. Pause or remove the Braze Initialization tag from your GTM container if you have already set it up.

2. Push your server-generated nonce to dataLayer before the GTM snippet in your site HTML:

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

3. In GTM, create a Data Layer Variable mapped to cspNonce (for example, DLV - cspNonce).

4. Create a Custom HTML tag with the trigger set to Initialization - All Pages:

   Customize the following template for your environment.

   
   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. For the Braze Actions tag or any Custom HTML tags that call Braze methods, configure tag sequencing to fire after this Custom HTML tag.

Google’s EU User Consent Policy

important

Google is updating its EU User Consent Policy in response to changes to the Digital Markets Act (DMA), which is in effect as of March 6, 2024. This new change requires advertisers to disclose certain information to their EEA and UK end users, as well as obtain necessary consents from them. Review the following documentation to learn more.

As part of Google’s EU User Consent Policy, the following boolean custom attributes need to be logged to user profiles:

• $google_ad_user_data
• $google_ad_personalization

If setting these via the GTM integration, custom attributes require creating a custom HTML tag. The following is an example of how to log these values as boolean data types (not as strings):

1
2
3

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

For more information, refer to Audience Sync to Google.