Marqo Pixel – Shopify Custom Pixel Integration Guide (Pixel Sandbox)

This guide shows you how to install and test the Marqo Pixel directly using Shopify's Custom Pixel feature (a.k.a. Pixel Sandbox). This method ensures tight integration with Shopify's native analytics.subscribe() events, secure handling of customer data, and compatibility with privacy controls.

---

Quick Setup

Step 0: Open the Shopify Pixel Editor

1. Go to your Shopify Admin → Settings → Customer Events
2. Click Create Custom Pixel
3. Name it "Marqo Pixel"
4. Paste the provided Marqo Pixel script (template version) into the editor from marqo_shopify_pixel.js
5. Click Save
6. Don't publish yet — follow the next steps to customize and test before going live.

---

Step 1: Customize Your Pixel Config

In the script, fill in your Marqo account details and cookie names:

window.mq_config = {
  customerId: '<FILL_IN_CUSTOMER_ID>',
  experimentId: '<FILL_IN_EXPERIMENT_ID>',
  apiKey: '<FILL_IN_API_KEY>',
  siteUserIdCookie: '<FILL_IN_USER_ID_COOKIE>',
  siteSessionIdCookie: '<FILL_IN_SESSION_ID_COOKIE>'
};

• Customer ID / Experiment ID / API Key: Provided by your Marqo representative
• Cookie Names: Used to extract persistent user/session IDs

How to Find Your Cookie Names

1. Visit your live storefront
2. Open DevTools → Application → Cookies
3. Look for cookies used for:
   • User identity (_shopify_y, bln-tid, etc.)
   • Session tracking (_shopify_s, auth_token, etc.)

These will be referenced in the pixel config.

---

Step 2: Understand Which Shopify Events Are Used

The Marqo Pixel automatically listens to the following Shopify Web Pixel events.

Shopify Event Name	Pixel Event Logged	Description
search_submitted	search	User submits a search query
product_viewed	click	User views or clicks a product
product_added_to_cart	cart	User adds product to cart
checkout_completed	purchase	User completes checkout/purchase

---

Step 3: Testing Your Pixel

1. Enable Shopify Pixel Sandbox Mode: The Pixel Sandbox allows you to test pixel behavior without affecting production analytics. Make changes and test events in the Shopify admin before publishing live.

2. Confirm Events Fire Properly: Perform each action on your storefront and ensure the corresponding pixel event triggers:

   Action	Expected Pixel Event	What to Verify
   Submit a search query	search	Pixel logs the search query data
   View/click a product	click	Pixel logs product ID, title, and referrer URL
   Add product to cart	cart	Pixel logs product details and quantity
   Complete checkout	purchase	Pixel logs purchase details for each line item

---

Step 4: Go Live

When testing is complete and you're confident the pixel fires correctly, publish the Custom Pixel in Shopify.

• Monitor initial traffic and event logging for accuracy.

---

Troubleshooting

Problem	Possible Cause	Solution
No events firing	Pixel script not saved or active	Confirm pixel saved and enabled in Shopify
Missing product data	Shopify event data missing or renamed	Verify Shopify event payload structure
Network requests failing	API key or customer ID incorrect	Check config values in the pixel script
Cookies not found	Cookie names incorrect or cookie blocked by browser	Verify cookie names and browser settings

---

Support

For further assistance, please contact your Marqo representative.