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:

Copy the Universal Pixel Snippet (below) into your site's HTML header.
Customize your unique customerID and experimentID.
[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.
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

Reach out to the Marqo team for access to your customerID and experimentID.
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

Copy the script below
Paste it into the <head> section of your site HTML
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,
});

Marqo Data Collection Policy

Overview

Marqo is committed to protecting and ensuring the privacy and security of our customers and their site users. We believe in transparency regarding how we collect and use data to improve our services. When Marqo Pixel is installed on your site, we collect limited user interaction data. This data is exclusively used for, fine-tuning our base models, optimizing index settings, enhancing search relevance and accuracy, providing better overall search experiences for your users. This data is not sold to third parties and is retained in our system for a default period of 2 years. Marqo has robust mechanisms to delete and remove this data upon request from our customers.

Data Collection Details

Marqo collects various types of data through Pixel. The exact data collection scope is subject to the specific configuration chosen by the customer, but typically includes:

User Interaction Events

Search Activity
- Search queries
- Filter selections
- Search refinements
- Results viewed
E-commerce Interactions
- Add-to-cart actions
- Purchase completions
- Product views
- Checkout processes
Site Engagement
- Button clicks
- Page navigation
- Content interaction
- Session duration

Technical Information

Browser type and version
Device information (desktop, mobile, tablet)
Operating system
Date and time of interactions
HTTP information: protocol, version, and response code

Data Security and Compliance

All collected data is processed in compliance with relevant data protection regulations and accessible only to authorized personnel

Data Usage Benefits

The data collected through Marqo Pixel directly contributes to: - More accurate search results for your users - Personalized search experiences - Improved product recommendations - Enhanced analytics and insights - Continuous improvement of the Marqo platform For additional information or to discuss specific data collection requirements, please contact our team at support@marqo.ai.