Skip to content

Marqo Pixel Installation Guide

Overview

The Marqo Pixel is a lightweight JavaScript client for tracking user interactions on ecommerce websites. It logs key events such as searches, clicks, add-to-cart actions, and purchases. These events are collected and sent to Marqo, where they are made available for model training and index optimization.

Features

  • A/B Testing Support: Assign users to different search variants for experimentation.
  • Event Logging: Track user actions such as searches, clicks, add-to-cart, and purchases.
  • Session and User Tracking: Persists session and user identifiers across visits.

High Level Installation

There are a few main steps to configuring the Marqo Pixel:

  1. Copy the Universal Pixel Snippet (below) into your site's HTML header.
  2. Customize your unique customerID and experimentID.

  3. [Optional] If running an A/B experiment, define the proportions for each experiment class in the Universal Pixel Snippet parameter abTestConfig — this will enable access to the collector.getSearchVariant(); which will assign site visitors to different experiment classes. You will paste this right before executing a search.

  4. For every event you'd like to track, copy and paste the proper JavaScript function on your site where the event is called (enumerated below).

Prerequisites

  1. Reach out to the Marqo team for access to your customerID and experimentID.
  2. Locate your API Key from the Marqo Cloud Console.

Prepare the Universal Pixel Snippet

Gather Variables

The Universal Pixel Snippet will be pasted onto your site's HTML page. This will load in the Marqo Pixel from the Content Delivery Network (CDN) and provide access to the event tracking functions. There are a few parameters in the snippet for you to change:

Parameter Type Default Description
experimentId string null Unique identifier for the experiment
apiKey string null API key for authentication
customerID string null Unique identifier for customer
abTestConfig Dict {control: 1.0} Distribution percentages for A/B test groups. Defaults to sending all search requests through a single search provider.

abTestConfig [Optional]

The abTestConfig object is used for assigning users to different experiment classes, which can either be different search providers you are intending to A/B test, or different instances of Marqo indexes you are intending to A/B test.

{
  "abTestConfig": {
    "control": 0.2,
    "my-index-variant-a": 0.4,
    "my-index-variant-b": 0.4
  }
}
  • The total proportions must sum to 1.0
  • There can be no more than 5 experiment classes.
  • The default of {control: 1.0} will send all users through one search provider, which acts as setting this as a basic metrics client.
  • If running an A/B test, it is highly encouraged to assign equal weights to the two experiment classes, as this improves the statistical power of the experiment.

Customize the Universal Pixel Snippet

  1. Copy the script below
  2. Paste it into the <head> section of your site HTML
  3. Customize the variables
<script>
  window.mq_config = {
    customerId: 'YOUR_CUSTOMER_ID',
    experimentId: 'YOUR_EXPERIMENT_ID',
    apiKey: 'YOUR_API_KEY',
    abTestConfig: {
      "control": 0.2,
      "my-index-variant-a": 0.4,
      "my-index-variant-b": 0.4
    }
  };
</script>
<script src="https://storage.googleapis.com/pixel-marqo-metrics-client-staging/pixel.js" async></script>

Configuring A/B Tests: Example

If you're testing multiple search solutions, or multiple Marqo instances, you'll be able to utilize the Marqo Pixel to assign users to search groups on the fly. This will assign the correct proportion of site users to each of the groups as defined in the abTestConfig object.

An example implementation might look like the following:

// Map variants to search providers
const searchProviders = {
  'control': 'my-index-control',
  'variant-a': 'my-index-variant-a',
  'variant-b': 'my-index-variant-b'
};

function performSearch(query) {
  // Get the user variant
  const variant = collector.getSearchVariant();

  // Get the index name for this variant (or use default)
  const indexName = variantIndexes[variant] || variantIndexes['control'];

  // Track the search event
  window.MqTrk.getTracker().trackEvent('search', { query, variant, indexName });

  // Use Marqo's client to search the appropriate index
  return mq.index(indexName).search({
    q: query,
    limit: 10
  })
  .then(data => {
    // Track search results
    window.MqTrk.getTracker().trackEvent('search_results', {
      variant,
      indexName,
      resultCount: data.hits?.length || 0
    });
    return data;
  });
}

Event Logging Snippets

For the events you would like to track, copy and paste the snippets below in the relevant locations on your site code. The relevant locations are generally after the event executes. Then replace the parameters with the proper ones tracked on your site.

Search Event

Tracks when a user performs a search. 

await collector.logSearchEvent({
  query: "red sneakers",
  results: ["id-101", "id-102"],
  limit: 10,
});

Add to Cart Event

Tracks when a user adds an item to the shopping cart. 

await collector.logAddToCartEvent({
  docId: "12345",
  quantity: 1,
  price: 10.99,
});

Click Event

Tracks when a user clicks on a product, category, or search result. 

await collector.logClickEvent({
  docId: "12345",
  typeOfClick: "product",
});

Purchase Event

Tracks when a user completes a purchase. 

await collector.logPurchaseEvent({
  docId: "12345",
  quantity: 1,
  price: 10.99,
});