Skip to content

Google Tag Manager Implementation Guide for Marqo Pixel

This guide describes the implementation process for integrating Marqo Pixel with Google Tag Manager (GTM). Configuring GTM will enable access to search event data for analysis, model training, and index optimization within Marqo.

Prerequisites

  • Google Tag Manager account
  • Container already live on your website
  • Marqo account with API access
  • Your unique Marqo Pixel ID (format: mp-XXXXXXXX)

Set Up Steps

1. Import the Marqo Container into Google Tag Manager

  1. Sign into your Google Tag Manager account
  2. Select the proper container
  3. Select Admin → Import container
  4. Upload the Marqo container file (*.json) provided by your Marqo representative
  5. Select New Workspace, name it "Marqo Pixel"
  6. Select Merge and choose Rename conflicting tags, triggers, and variables

Note: The container import is the only supported installation method for Marqo Pixel.

2. Configure Core Marqo Credentials

  1. Go to Variables in the left sidebar
  2. Under User-Defined Variables, locate "Marqo Account ID"
  3. Click to edit and enter your Marqo Account ID (provided by Marqo)
  4. Save the variable
  5. Repeat for "Marqo Pixel ID" variable with your unique pixel identifier

3. Configure Marqo Tags and Triggers

The Marqo container adapts to your existing GTM implementation without requiring website code changes:

  1. Go to Tags in the left sidebar
  2. Locate the Marqo event tags (prefixed with "Marqo")
  3. For each tag:
  4. Edit the tag
  5. Review the "Notes" section in the provided container tags to understand the required data
  6. Under "Triggering" section, select appropriate triggers from your existing implementation
  7. Map your existing variables to Marqo's variables

4. Map Your Existing Data Variables

This step connects your site's existing data variables to the Marqo tracking system:

  1. Go to Variables in GTM
  2. Identify the tracking variables created by the Marqo container (prefixed with "Marqo")
  3. For each Marqo tracking variable (such as the Marqo search query or add-to-cart event, etc.):
  4. Edit the variable
  5. Change the data source to point to your corresponding existing variable or data layer path
  6. Save the change

Example: If your site pushes search queries as event.searchTerm, edit the Marqo search query variable to use that path instead of the default value.

5. A/B Testing with Marqo

How the A/B Testing Works

A/B testing is an optional implementation pattern. It allows you to segment users into different search variants and to access this information before executing a search.

  1. Variant Assignment: The Marqo container automatically assigns users to variants and stores this in a cookie.
  2. Variant Retrieval: Your code accesses the assigned variant using window.MqTrk.getTracker().getVariant().
  3. Search Implementation: Your code routes the search based on the variant.
  4. Tracking: The Marqo container includes variant information in all events sent to Marqo for performance analysis.

1. Setting Up A/B Test Variants in GTM

  1. Locate the "Marqo A/B Test Configuration" tag
  2. Edit the tag and define your test configuration:
  3. Test name (e.g., "Search Algorithm Test")
  4. Variant names (e.g., "control", "variant-a-index", "variant-b-index")
  5. Traffic allocation (e.g., 0.25 to each variant; must add up to 1.0)

2. Implementation Example: Client-side Search Routing

/**
 * Integrating Marqo A/B testing with your search functionality
 */

// Example search function that uses the Marqo variant
function searchWithMarqoVariant(query) {
  // 1. Get the variant assigned by the Marqo container
  const variant = window.MqTrk.getTracker().getVariant();
  console.log("User is in test variant:", variant);

  // 2. Determine which index to use based on variant
  let indexName;

  if (variant === 'b') {
    indexName = "variant-b-index";
  } else {
    // Default to variant-a-index for control or any other variant
    indexName = "variant-a-index";
  }

  // 3. Execute the search with the Marqo API format
  return executeSearch(query, indexName);
}

// Example function to execute search with Marqo API format
function executeSearch(query, indexName) {
  // This is where you'd call the Marqo search API
  const url = `https://api.marqo.ai/api/v2/indexes/${indexName}/search`;

  const searchOptions = {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      "q": query,
      "searchMethod": "HYBRID",
    })
  };

  return fetch(url, searchOptions)
    .then(response => response.json())
    .then(results => {
      // Display search results
      displaySearchResults(results);
      return results;
    });
}

// Attach to search form
document.getElementById('search-form').addEventListener('submit', function(e) {
  e.preventDefault();
  const query = document.getElementById('search-input').value;
  searchWithMarqoVariant(query);
});

Implementation Tips

  • Testing: Verify variant assignment by checking window.MqTrk.getTracker().getVariant() in the browser console.
  • Consistent Experience: Users remain in the same variant across sessions.
  • Error Handling: Add fallback logic: 
    function getAssignedVariant() {
  try {
    if (window.MqTrk && window.MqTrk.getTracker) {
      return window.MqTrk.getTracker().getVariant();
    }
  } catch (e) {
    console.error("Error accessing Marqo variant:", e);
  }
  return "control"; // Fallback to control
}
  • Debugging: Force a specific variant for testing: 
    // For development/testing only
localStorage.setItem('mqo_variant_override', 'semantic-search');

Appendix: Example Container Scripts

This container script will be provided to you in full, however here is a sample to understand the contents of the container before installation.

Metadata

{
  "exportFormatVersion": 2,
  "exportTime": "2025-03-26 10:00:00",
  "containerVersion": {
    "accountId": "1000000001",
    "containerId": "20000001",
    "container": {
      "name": "Marqo-Template-V1",
      "publicId": "GTM-MARQO1",
      "usageContext": ["WEB"]
    }
  }
}

Tags

{
  "tag": [
    {
      "tagId": "1",
      "name": "Marqo Pixel - Base",
      "type": "html",
      "notes": "Base configuration for Marqo tracking",
      "parameter": [
        {
          "type": "TEMPLATE",
          "key": "html",
          "value": "<script>\n(function(w,d,s,l,i,p){\n  w[l]=w[l]||[];\n  w[l].push({'mp.start': new Date().getTime(), event: 'mp.js'});\n  var f=d.getElementsByTagName(s)[0],\n  j=d.createElement(s);\n  j.async=true;\n  j.src='https://pixel.marqo.ai/mpixel.js?id='+i+'&px='+p;\n  f.parentNode.insertBefore(j,f);\n})(window,document,'script','dataLayer','{{Marqo Account ID}}','{{Marqo Pixel ID}}');\n</script>"
        }
      ],
      "firingTriggerId": ["2147483648"], // All Pages
      "tagFiringOption": "ONCE_PER_EVENT",
      "parentFolderId": "10"
    },
    {
      "tagId": "2",
      "name": "Marqo Search Event",
      "type": "html",
      "notes": "Maps your existing search events to Marqo's tracking API",
      "parameter": [
        {
          "type": "TEMPLATE",
          "key": "html",
          "value": "<script>\n// This tag maps your existing search event data to Marqo's tracking system\nwindow.MqTrk.getTracker().logEvent('search', 'view', {\n  query: {{Your Search Query Variable}},\n  results: {{Your Search Results Variable}},\n  pageUrl: window.location.href,\n  pageTitle: document.title\n});\n</script>"
        }
      ],
      "firingTriggerId": ["yourExistingSearchTrigger"], 
      "parentFolderId": "11"
    },
    {
      "tagId": "3",
      "name": "Marqo Click Event",
      "type": "html",
      "notes": "Maps your existing click events to Marqo's tracking API",
      "parameter": [
        {
          "type": "TEMPLATE",
          "key": "html",
          "value": "<script>\n// This tag maps your existing click event data to Marqo's tracking system\nwindow.MqTrk.getTracker().logEvent('click', 'product', {\n  docId: {{Your Product ID Variable}},\n  typeOfClick: 'product',\n  position: {{Your Result Position Variable}}\n});\n</script>"
        }
      ],
      "firingTriggerId": ["yourExistingClickTrigger"],
      "parentFolderId": "11"
    }
  ]
}

Variables

{
  "variable": [
    {
      "variableId": "1",
      "name": "Marqo Account ID",
      "type": "c",
      "notes": "Your unique Marqo account identifier",
      "parameter": [
        {
          "type": "TEMPLATE",
          "key": "value",
          "value": "marqo-demo-12345"
        }
      ],
      "parentFolderId": "12"
    },
    {
      "variableId": "2",
      "name": "Marqo Pixel ID",
      "type": "c",
      "notes": "Your unique Marqo Pixel identifier",
      "parameter": [
        {
          "type": "TEMPLATE",
          "key": "value",
          "value": "mp-XXXXXXXX"
        }
      ],
      "parentFolderId": "12"
    }
  ]
}

Folder

{
  "folder": [
    {
      "folderId": "10",
      "name": "Marqo Initialization"
    },
    {
      "folderId": "11",
      "name": "Marqo Events"
    },
    {
      "folderId": "12",
      "name": "Marqo Variables"
    }
  ]
}

Event Types & Troubleshooting

Supported Event Types

The Marqo container tracks these common e-commerce events: - Search events - Click events - Cart events (add/remove) - Purchase events - Widget interaction events

Common Issues

  1. Events not showing in Marqo dashboard
  2. Verify Marqo Pixel ID and Account ID
  3. Check browser console for errors
  4. Ensure base tag fires before event tags

  5. Confirm existing event triggers are firing correctly

  6. Tags not firing

  7. Check trigger mappings
  8. Verify base tag loads completely
  9. Use GTM Preview mode to debug

For additional support, contact support@marqo.ai