Skip to content

Marqo Pixel GTM Container – General Integration Guide

This GTM container template provides complete Marqo attribution tracking. Follow this guide to customize it for your specific site.

🚀 Quick Setup

Step 0: Import the Container into GTM

  1. Sign in to Google Tag Manager and choose an Account.
  2. Use an existing container or create a new container dedicated to Marqo.
  3. Click Admin → Import Container.
  4. Upload the Marqo GTM container (marqo_universal_gtm_container.json), select the workspace, and choose Merge → Overwrite conflicts.
  5. Click Confirm – GTM will add all Marqo tags, triggers and variables.
  6. Publish now or continue editing in your workspace.

Note: Stay in the workspace — run the tests below and then publish the container.

Update these Constant Variables with your Marqo account details provided to you by your Marqo representative and specify the cookie names your site uses to persist user & session IDs.

Variable Name Update To
Marqo Customer ID Your Customer ID
Marqo API Key Your API Key
Marqo Experiment ID Your Experiment ID
Variable Name Example Value Purpose
Cookie User ID bln-tid Cookie that uniquely identifies the signed-in shopper
Cookie Session ID bln-auth-token Short-lived cookie that ties events together into a session

How to find your cookie names: Open DevTools → Application → Storage → Cookies, refresh your storefront, then look for the cookies that hold user / session identifiers used by your back-end or analytics platform.

Step 2: Update Data Layer Variables

Map these variables to your site's data layer structure.

How to discover your variable names

  1. Open your site and press Cmd ⌘ + Option ⌥ + I (Mac) or F12 (Windows) to open DevTools.
  2. In the Console type dataLayer and hit Enter – expand the most-recent object to see the keys available.
  3. Alternatively, with GTM Preview (Tag Assistant) open, click an event in the left column and inspect the Variables tab – this shows the exact key/value pairs GTM sees for that event.
  4. Copy those keys into the table below.

Important: The DL - Product ID (sent to Marqo as docId) should contain the product variant SKU or another identifier that is unique for every purchasable variant, not just the parent product ID.

Core Variables

Variable Name Example Mapping Common Alternatives
DL - Product ID contentIds.0 ecommerce.items.0.item_id
product.id
gtm.productId
DL - Product Name ecommerce.items.0.item_name product.name
gtm.productName
DL - Search Query search_term search.query
searchQuery
q
DL - Ecommerce ecommerce Usually stays ecommerce

Step 3: Update Event Triggers

Update these Custom Event triggers to match your site's events:

Trigger Name Example Event Common Alternatives
Add to Cart Trigger add_to_cart addToCart
gtm.add_to_cart
Product Click Trigger view_item productClick
gtm.view_item
Search Event Trigger search site_search
gtm.search
Purchase Trigger purchase ecommerce_purchase
gtm.purchase
orderCompleted

How to discover your event names

  1. With Tag Assistant Preview connected, perform the interaction (search, product click, add-to-cart, etc.).
  2. In the left-hand event stream note the value shown for Event Name (it's the _event key in the dataLayer push).
  3. Use that exact string in the Custom Event Trigger configuration inside GTM.
  4. Repeat for each interaction you need (search, product click, add-to-cart, purchase).

Testing

1. Open GTM Preview (Tag Assistant)

  1. In GTM click Preview and enter your site URL.
  2. Keep Tag Assistant open in a separate tab while you run the tests below.

2. Fire & Verify Core Events

Action GTM Tag that should fire Key variables to validate*
Perform a search MQ – Search Event MQ – Search Query
Click a product from the results MQ – Product Click Event MQ – Product ID, MQ – Product Name
Add that product to the cart MQ – Add to Cart Event MQ – Product ID, MQ – Product Name
Complete a purchase (optional) MQ – Purchase Event MQ – Ecommerce (items, value, currency)

Open the event in Tag Assistant → Variables*. None of these values should be undefined—they are forwarded to MrqTrk.logEvent and must be present for correct analytics.

Variables worth double-checking in every event:

  • Built-In: Event, Page Hostname, Page Path, Page URL, Referrer
  • User-Defined:
  • MQ – Ecommerce
  • MQ – Product ID
  • MQ – Product Name
  • MQ – Purchase Products
  • MQ – Search Query
  • MQ Cookie User ID
  • MQ Cookie Session ID

(You can ignore static constants such as Cache Buster, MQ API Key, MQ Customer ID, and MQ Experiment ID—they are automatically populated and do not change per event.)

3. Confirm MrqTrk Collector Calls

Use DevTools → Network and filter for collect:

  • Each event above should trigger a request that returns 200 OK.
  • No request should retry more than once; the collector must report hasFatalError = false.

4. End-to-End Attribution Test

  1. Search → Product Click → Add to Cart → Purchase.
  2. Verify sessionId, userId, and experimentVariant appear on every event.

5. Final Error Check

  • No console errors.
  • All GTM variables resolve (nothing shows "undefined").
  • All tracker calls return 200.

Once every row in the table fires correctly and the attribution test passes, you're ready to publish the container (see Step 6 below).

Step 6: Publish Container

  1. In GTM click Submit.
  2. Add a version name like "Marqo Pixel – Live".
  3. Click Publish to push the tags live on your site.

Common Issues & Solutions

"undefined" in GTM Preview

Problem: Variables showing "undefined"
Solution: Check your data layer variable mappings match your site's structure

Events Not Firing

Problem: Tags not triggering
Solution: Verify event names in triggers match your site's data layer events

Missing Product Data

Problem: docId or title empty
Solution: Confirm ecommerce data structure matches expected format

Attribution Not Working

Problem: Search context lost
Solution: Ensure search events fire before navigation, check sessionStorage

API Errors

Problem: 401/403 errors
Solution: Verify API key is correct and has proper permissions

Support

For additional help, please contact your Marqo representative.