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
- Sign in to Google Tag Manager and choose an Account.
- Use an existing container or create a new container dedicated to Marqo.
- Click Admin → Import Container.
- Upload the Marqo GTM container (
marqo_universal_gtm_container.json
), select the workspace, and choose Merge → Overwrite conflicts. - Click Confirm – GTM will add all Marqo tags, triggers and variables.
- 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 Data Layer Variables
Map these variables to your site's data layer structure.
How to discover your variable names
- Open your site and press Cmd ⌘ + Option ⌥ + I (Mac) or F12 (Windows) to open DevTools.
- In the Console type
dataLayer
and hit Enter – expand the most-recent object to see the keys available. - 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.
- Copy those keys into the table below.
Important: The
DL - Product ID
(sent to Marqo asdocId
) 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
- With Tag Assistant Preview connected, perform the interaction (search, product click, add-to-cart, etc.).
- In the left-hand event stream note the value shown for
Event Name
(it's the_event
key in the dataLayer push). - Use that exact string in the Custom Event Trigger configuration inside GTM.
- Repeat for each interaction you need (search, product click, add-to-cart, purchase).
Testing
1. Open GTM Preview (Tag Assistant)
- In GTM click Preview and enter your site URL.
- 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
- Search → Product Click → Add to Cart → Purchase.
- Verify
sessionId
,userId
, andexperimentVariant
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
- In GTM click Submit.
- Add a version name like "Marqo Pixel – Live".
- 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.