Skip to content

Marqo Pixel Integration: Server GTM Method

This guide walks you through implementing Marqo's server-side tracking pixel using a Google Tag Manager (GTM) Server container with a custom tracking subdomain. This setup enables durable, first-party data collection by routing pixel events through your own domain, improving attribution accuracy and bypassing browser limitations like Safari's ITP.

1. Initial Setup: Subdomain & Delegation

Before you begin with GTM, ensure the following foundational steps are complete:

  1. Create a subdomain
    → Example: analytics.yourdomain.com
  2. Delegate the subdomain via NS records
    → Set NS records for analytics.yourdomain.com to:
    ns1.yourdomain.marqo.ai
  3. Contact Marqo
    → Please reach out to the Marqo team to complete the subdomain delegation and provisioning. Marqo will:
  4. Provision DNS infrastructure and route tracking traffic
  5. Host the GTM Server container endpoint under your delegated subdomain

2. GTM Client-Side Preparation

  1. Update GTM Data Layer variable
    → In your GTM client-side container, create a variable called MQ Custom Endpoint with the value of your subdomain.
  2. Configure the remainder of the GTM Container
    → See the integration steps below for importing and customizing the container.

Marqo Pixel GTM Container – Integration Guide

Once your subdomain and server-side infrastructure are ready, follow these steps to complete the GTM integration for full Marqo attribution tracking.

🚀 Quick Setup

Step 0: Import the Container into GTM

  1. Sign in to Google Tag Manager.
  2. Use an existing container or create a new one for Marqo.
  3. Go to Admin → Import Container.
  4. Upload the (marqo_universal_gtm_container.json).
  5. Select your workspace and choose Merge → Overwrite conflicts.
  6. Click Confirm.
  7. Do not publish yet—run tests below first.

Constant Variables

Variable Name Update To
Marqo Customer ID Your Customer ID
Marqo API Key Your API Key
Marqo Experiment ID Your Experiment ID
MQ Custom Endpoint Your subdomain
Variable Name Example Value Purpose
Cookie User ID user_id Identifies the user (anonymous or signed in)
Cookie Session ID session_id Links all events during a single visit

Find your cookie names via DevTools → Application → Storage → Cookies.

Step 2: Update Data Layer Variables

Use DevTools or GTM Preview mode to inspect your site's dataLayer object and identify which keys map to the following fields.

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

Important: Ensure DL - Product ID is the variant SKU or unique ID per purchasable item.

Step 3: Update Event Triggers

Map Marqo tags to your site's event names.

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, orderCompleted

Use GTM Preview to capture actual event names from your site during interactions.

✅ Testing

1. Open GTM Preview (Tag Assistant)

  1. Click Preview in GTM.
  2. Enter your site URL and begin recording events.

2. Fire & Verify Core Events

Action Tag That Should Fire Key Variables to Validate
Perform a search MQ – Search Event MQ – Search Query
Click a product MQ – Product Click Event MQ – Product ID, MQ – Product Name
Add product to cart MQ – Add to Cart Event MQ – Product ID, MQ – Product Name
Complete a purchase MQ – Purchase Event MQ – Ecommerce (items, value, currency)

Check Tag Assistant → Variables tab for values. None should be undefined.

3. Confirm MrqTrk Collector Calls

  1. Open DevTools → Network tab.
  2. Filter by collect.
  3. Each event should fire a request returning 200 OK.
  4. No request should retry more than once. Ensure hasFatalError = false.

4. End-to-End Attribution Test

Run a full funnel test:
Search → Product Click → Add to Cart → Purchase

Ensure these appear on every event: - sessionId - userId - experimentVariant

5. Final Error Check

  • No console errors.
  • All GTM variables resolve properly.
  • All tracker calls return 200 OK.

Once all events fire correctly and values are populated, proceed to publish.

Step 6: Publish Container

  1. In GTM, click Submit.
  2. Name the version (e.g., "Marqo Pixel – Live").
  3. Click Publish to go live.

Common Issues & Solutions

Variables Showing "undefined"

  • Cause: Incorrect data layer mapping.
  • Fix: Double-check dataLayer keys vs. GTM variable names.

Events Not Firing

  • Cause: Mismatched event names in triggers.
  • Fix: Use GTM Preview to find the actual event names.

Missing Product Data

  • Cause: Product ID/title not present in ecommerce object.
  • Fix: Confirm correct structure in your site's dataLayer.

Attribution Breaks Between Pages

  • Cause: Search context not preserved.
  • Fix: Ensure search events fire before page navigation. Use sessionStorage.

API Errors (401 / 403)

  • Cause: Invalid or missing API key.
  • Fix: Confirm your key and permissions with your Marqo rep.

Support

For further help, contact your Marqo representative.