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.
   • Use an existing container or create a new container dedicated to Marqo.
2. Click Admin → Import Container.
3. Upload the Marqo GTM container (marqo_universal_gtm_container.json), select the workspace, and choose Merge → Overwrite conflicts.
4. Click Confirm – GTM will add all Marqo tags, triggers and variables.
5. Publish now or continue editing in your workspace.

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

Step 1: Update Constants & Cookie Names

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

Cookie Constants

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 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). For example, a product click could show a view_item event.
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).

Step 3: 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 (i.e. view_item) and inspect the Variables or Datalayer tab – this shows the exact key/value pairs GTM sees for that event.
4. Copy those keys into the table below.

Important: The MQ - 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
MQ - Product ID	contentIds.0	ecommerce.items.0.item_id product.id gtm.productId
MQ - Product Name	ecommerce.items.0.item_name	product.name gtm.productName
MQ - Search Query	search_term	search.query searchQuery q or you can parse using the pageUrl as the container does
MQ - Collection ID	collection_id	collection_handle collection_name or you can parse using the pageUrl as the container does

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	(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 – Product ID (Click) and MQ – Product ID (ATC)
  • MQ – Product Name (Click) and MQ – Product ID (ATC)
  • MQ – Purchase Products
  • MQ – Search Query
  • MQ – CollectionId
  • 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.