Setting up GTM to Capture SwitchLive Events

Prerequisites: GTM must already be installed on your site. If you're on Shopify, add the GTM head snippet immediately after <head> and the noscript snippet immediately after <body> in your layout/theme.liquid file.

How SwitchLive Works

The Locally widget fires a postMessage event to the parent page whenever a shopper interacts with it (views a store, selects a purchase option, completes an order, etc.). GTM needs a listener tag to catch this message and push it into the dataLayer, where the rest of your tags can act on it.

Important — individual fields vs. blob: The most common setup mistake is pushing the entire SwitchLive payload as a single object (switchLiveData: switchLiveEvent). This causes GA4 to receive a JavaScript object rather than scalar values, which shows up as [object Object] in reports. This guide maps each field to its own dataLayer key so every parameter is a clean string or number.

Step 1: Create the SwitchLive Event Listener Tag

This tag listens for the SwitchLive postMessage and pushes each field individually into the GTM dataLayer.

In GTM, go to Tags > New > Tag Configuration > Custom HTML.
Paste the following code (including the <script> tags):

<script>
window.addEventListener("message", function (e) {
  if (typeof e.data.message_type !== 'undefined' && e.data.message_type === 'switchlive') {
    var switchLiveEvent = e.data;
    console.log(switchLiveEvent, '<<< SWITCH LIVE EVENT');
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({
      event: 'SwitchLiveEvent',
      event_id: switchLiveEvent.id || '',
      event_type: switchLiveEvent.type || '',
      event_description: switchLiveEvent.description || '',
      scope: switchLiveEvent.scope || '',
      company_id: switchLiveEvent.company_id || '',
      locale_code: switchLiveEvent.locale_code || '',
      store_id: switchLiveEvent.store_id || '',
      store_name: switchLiveEvent.store_name || '',
      store_address: switchLiveEvent.store_address || '',
      product_id: switchLiveEvent.product_id || '',
      style: switchLiveEvent.style || '',
      upc: switchLiveEvent.upc || '',
      sale_type: switchLiveEvent.sale_type || '',
      cart_hash: switchLiveEvent.cart_hash || '',
      product_price: switchLiveEvent.product_price || '',
      vendor_id: switchLiveEvent.vendor_id || '',
      timestamp: switchLiveEvent.timestamp || '',
      url: switchLiveEvent.url || '',
      utm: switchLiveEvent.utm || ''
    });
    console.log("Event pushed to Data Layer:", window.dataLayer);
  }
});
</script>

Set the trigger to All Pages (Page View).
Name the tag SwitchLive Event Listener and save.

Step 2: Create Data Layer Variables (DLVs)

Create one Data Layer Variable for each SwitchLive field. These variables extract individual values from the dataLayer push above so they can be used as GA4 event parameters, trigger conditions, and ad platform values.

For each variable below:

Go to Variables > New > Variable Configuration > Data Layer Variable.
Set the Data Layer Variable Name exactly as shown.
Set Data Layer Version to Version 2.
Name and save the variable.

Variable Name (in GTM)	Data Layer Variable Name
SwitchLive - Event ID	`event_id`
SwitchLive - Event Type	`event_type`
SwitchLive - Description	`event_description`
SwitchLive - Scope	`scope`
SwitchLive - Company ID	`company_id`
SwitchLive - Locale Code	`locale_code`
SwitchLive - Store ID	`store_id`
SwitchLive - Store Name	`store_name`
SwitchLive - Store Address	`store_address`
SwitchLive - Product ID	`product_id`
SwitchLive - Style	`style`
SwitchLive - UPC	`upc`
SwitchLive - Sale Type	`sale_type`
SwitchLive - Cart Hash	`cart_hash`
SwitchLive - Product Price	`product_price`
SwitchLive - Vendor ID	`vendor_id`
SwitchLive - Timestamp	`timestamp`
SwitchLive - URL	`url`
SwitchLive - UTM	`utm`

Tip: Name all variables with the SwitchLive - prefix so they're easy to find in the variable picker when building tags.

Step 3: Create a Custom Event Trigger

This trigger fires any tag you assign it to whenever a SwitchLive event hits the dataLayer.

Go to Triggers > New > Trigger Configuration > Custom Event.
Set Event Name to SwitchLiveEvent (this must match the event value in the dataLayer push exactly).
Name the trigger SwitchLive - All Events and save.

Step 4: Create a GA4 Event Tag

Go to Tags > New > Tag Configuration > Google Analytics: GA4 Event.
Select your Measurement ID (or GA4 Configuration tag).
Set Event Name to switch_live_event.
Under Event Parameters, add one row for each variable:

Parameter Name	Value
`event_id`	`{{SwitchLive - Event ID}}`
`event_type`	`{{SwitchLive - Event Type}}`
`event_description`	`{{SwitchLive - Description}}`
`scope`	`{{SwitchLive - Scope}}`
`company_id`	`{{SwitchLive - Company ID}}`
`locale_code`	`{{SwitchLive - Locale Code}}`
`store_id`	`{{SwitchLive - Store ID}}`
`store_name`	`{{SwitchLive - Store Name}}`
`store_address`	`{{SwitchLive - Store Address}}`
`product_id`	`{{SwitchLive - Product ID}}`
`style`	`{{SwitchLive - Style}}`
`upc`	`{{SwitchLive - UPC}}`
`sale_type`	`{{SwitchLive - Sale Type}}`
`cart_hash`	`{{SwitchLive - Cart Hash}}`
`product_price`	`{{SwitchLive - Product Price}}`
`vendor_id`	`{{SwitchLive - Vendor ID}}`
`timestamp`	`{{SwitchLive - Timestamp}}`
`url`	`{{SwitchLive - URL}}`
`utm`	`{{SwitchLive - UTM}}`

Assign the SwitchLive - All Events trigger.
Name the tag SwitchLive - GA4 Event and save.

Step 5: Define Custom Dimensions in GA4

GA4 receives the event parameters above, but they won't appear as queryable dimensions in Explore reports until you register them. This is a commonly missed step.

In GA4, go to Admin > Data display > Custom definitions.
Click Create custom dimension.
For each parameter you want to report on, set:
- Dimension name: a human-readable label (e.g., "Store Name")
- Scope: Event
- Event parameter: the exact parameter name from your GA4 tag (e.g., store_name)
Save.

Repeat for each parameter. Custom dimension data takes 24–48 hours to begin populating in Explore.

Step 6: Test the Implementation

In GTM, click Preview to open Tag Assistant.
Navigate to your site and interact with the Locally widget (open it, select a store, etc.).
In Tag Assistant, click on the SwitchLiveEvent entry in the event stream.
Confirm:
- The SwitchLive Event Listener tag fired.
- The SwitchLive - GA4 Event tag fired.
- Under Data Layer, each individual field (event_id, store_name, etc.) appears as its own key — not nested inside a switchLiveData object.
In GA4, go to Reports > Realtime and confirm switch_live_event appears with individual parameter values visible.

Troubleshooting

Parameters show [object Object] in GA4

The dataLayer push is sending a nested object instead of individual scalar values. Check that you're using the listener script from Step 1 (which maps each field individually) and not an older version that pushes switchLiveData: switchLiveEvent. If you have an existing GA4 tag with a switch_live_data event parameter, delete that row and re-add parameters using the individual DLVs.

product_id is always empty

This is expected behavior. The product_id field only populates when the SwitchLive event fires on a Product Detail Page (PDP). On collection pages or store locator pages where no specific product context is loaded, product_id will be blank. For "Order Placed" events specifically, product_id will populate if the shopper navigated through a PDP before completing the order.

SwitchLive events not appearing in Tag Assistant

Verify your GTM container snippet is present in the page source (check both <head> and <body> sections). If you recently switched themes (Shopify), the new theme may not have GTM installed — add the snippets to the new theme's layout/theme.liquid. Open your browser console and paste the script below to confirm the widget is firing events at all:

window.addEventListener("message", function(e) {
  if (typeof e.data.message_type !== 'undefined' && e.data.message_type === 'switchlive') {
    console.log(e.data, '<<< SWITCH LIVE EVENT');
  }
});

Then interact with the widget. If nothing logs, the widget itself may not be configured — contact your Locally Implementation Manager.

Some clients have nested switchLiveData objects

If your SwitchLive events arrive with data nested under switchLiveData (e.g., switchLiveData.store_name instead of store_name), your DLV variable names should use dot notation: switchLiveData.store_name. Check the dataLayer output in Tag Assistant to confirm the structure before setting variable names.

For additional assistance, reach out to your Implementation Manager or CSM.