Overview

Triple Whale’s one-click Pixel Auto-Install is the recommended setup for standard Shopify storefronts.

If your store uses a headless front end, custom website, third-party landing page, or third-party checkout, Auto-Install may not be able to add the Pixel script to every page. These pages are hosted outside of your Shopify theme, so Triple Whale cannot automatically write code to them.

This article explains how to manually install the Triple Pixel, verify that it is working, and optionally track events such as Add to Cart, checkout steps, contact details, subscriptions, custom events, product context, search context, and consent changes.

This article also covers advanced compatibility settings that may be needed for custom or headless storefronts with stricter security requirements.

Before you begin

You may need help from a developer or site manager to complete this setup. The instructions require adding JavaScript to your site and triggering Pixel events from your storefront or checkout code.

Before starting, make sure you have:

Access to your Triple Whale Pixel Settings page
Access to edit your website or storefront code
Your Shopify product IDs and variant IDs, if you plan to track Add to Cart or product-page context
Developer console access for testing

What this article covers

This article walks through:

Installing the base Triple Pixel snippet
Testing whether the Pixel is present on your site
Using Eval Restriction when Triple Whale Support or Engineering instructs you to
Identifying visitors with contact information
Tracking page loads, Add to Cart events, checkout events, purchase events, subscription events, and custom events
Passing product and search context
Handling single page applications
Managing tracking consent
Installing the Pixel with a tag manager
Installing the Pixel on separate mobile websites

If your setup does not require every event type, use only the sections that apply to your storefront or checkout.

Step 1: Install the base tracking snippet

The base tracking snippet is available in the Headless Installation tab on the Pixel Settings page.

To install the base snippet:

Go to Settings.
Under Store Configurations click into Pixel Settings
Under the Pixel Installation tab ensure you have a "Shopify Headless" Store Setup saved.
Scroll down to the Recommended installation for your shop: section and copy the Headless Installation snippet
Add the snippet inside the <head> tag on every page where you want to track visitor activity.

The snippet loads the Triple Pixel javascript asynchronously so it won’t affect your page load speed.

Testing your installation

After installing the base snippet, verify that the Triple Pixel is present on your site.

To test the installation:

Open any page where you installed the pixel.
Open the developer console in your browser.
Enter TriplePixelData into the console.
Confirm that the TriplePixelData object appears.

If you see undefined, check the following:

The code was added inside the <head> tags of the page.
The pixel was added to the page you are testing, not only to another template or route.
Cached HTML content has been purged. This process varies by platform and content delivery network, so check with your technical team if needed.

Advanced setting: Eval Restriction

Eval Restriction is an advanced compatibility setting for custom or headless storefronts.

When enabled, the Triple Pixel runs in a more restricted mode. This can help websites with strict security settings that block certain types of JavaScript execution.

Most standard Shopify storefronts do not need this setting. In most cases, leave Eval Restriction disabled unless Triple Whale Support or Engineering asks you to enable it during troubleshooting.

To use this setting:

Click on Settings
Under Store Configurations click on Pixel Settings
Go to the Pixel Settings page.
Find Eval Restriction toggle under the Recommended installation for your shop: section and select the Headless Installation tab
1. Toggle is above to the far right of the Snippet
Turn ON the Eval Restriction toggle only if Triple Whale Support or Engineering has instructed you to do so.

Eval Restriction is an advanced compatibility setting for custom or headless storefronts with strict security settings. Leave this disabled unless Triple Whale Support or Engineering asks you to enable it during troubleshooting.

Step 2: Identify Visitors

To identify your visitors when they share personal information (from filling out a form, for instance), you can trigger a Triple Pixel ‘contact’ event and pass relevant identifying details.

TriplePixel('Contact', {
  email: '[email protected]',   // Required: email OR phone
  phone: '+1-555-123-4567'
});

When passing a contact event, you must pass at least one of the fields

email
phone

You can pass both if they are both provided.

Note: The Contact event does not appear as an event in the customer journey popup when drilling into data in the Attribution page.

Each time the Contact event is sent, we connect the customer's contact data to their other sessions and actions, so that future events can be tied to the same journey.

Step 3: Track Actions

By default, the Triple Pixel supports tracking a number of standard events.

Before triggering events, make sure the Triple Pixel has successfully initialized.

Page Load

The base tracking snippet captures a pageLoad automatically when loaded on a new page.

For single page applications (SPA) or to capture page views manually, you can trigger a pageLoad event:

TriplePixel('pageLoad')

For more information on implementing the Triple Pixel with Single Page Applications (SPA), see the section below called Instructions for Single Page Applications

Add to Carts

To track when a user adds an item to their cart, see the example below or use the Add to Cart script provided on the Pixel Settings page:

TriplePixel('AddToCart', { 
  item: '1234567',     // Product ID (Required)
  q: 1,                // Quantity (Required)
  v: '654321'          // Variant ID (Required)
});

Shopify note: You can find a product’s ID in the URL when editing that product in your Shopify dashboard.

Checkout Events

You can use checkout events to track checkout activity on custom or headless checkouts.

While many fields are optional, passing more data improves tracking accuracy.

Checkout Started

TriplePixel('checkoutStarted', {
  eventId: 'evt_sub_001',              // ID for cross-platform dedupe (Optional)
  email: '[email protected]',           // At least one of email or phone (Required)
  phone: '+1-555-123-4567',
  firstName: 'John',                   // Optional
  lastName: 'Doe',                     // Optional
  orderId: 'order_0000',               // System order ID (Optional)
  cotkn: '121212121212',               // Used for order<>journey matching (Optional)
  lineItems: [{
   i: '1234567',                       // Product ID (Required)                 
   q: 1,                               // Quantity (Required)             
   v: '654321'                	       // Variant ID (Required)             
  }],
  address: { zip: '67676', city: 'Sterling', countryCode: 'US', provinceCode: 'KS'}		// Required
});

Contact Information Submitted

TriplePixel('contactSubmitted', {
  eventId: 'evt_sub_001',              // ID for cross-platform dedupe (Optional)
  email: '[email protected]',           // At least one of email or phone (Required)
  phone: '+1-555-123-4567',
  firstName: 'John',                   // Optional
  lastName: 'Doe',                     // Optional
  orderId: 'order_0000',               // System order ID (Optional)
  cotkn: '121212121212',               // Used for order<>journey matching (Optional)
  lineItems: [{
   i: '1234567',                       // Product ID (Required)                 
   q: 1,                               // Quantity (Required)             
   v: '654321'                	       // Variant ID (Required)             
  }],
  address: { zip: '67676', city: 'Sterling', countryCode: 'US', provinceCode: 'KS'}		// Required
});

Billing Address Submitted

TriplePixel('addressSubmitted', {
  eventId: 'evt_sub_001',              // ID for cross-platform dedupe (Optional)
  email: '[email protected]',           // At least one of email or phone (Required)
  phone: '+1-555-123-4567',
  firstName: 'John',                   // Optional
  lastName: 'Doe',                     // Optional
  orderId: 'order_0000',               // System order ID (Optional)
  cotkn: '121212121212',               // Used for order<>journey matching (Optional)
  lineItems: [{
   i: '1234567',                       // Product ID (Required)                 
   q: 1,                               // Quantity (Required)             
   v: '654321'                	       // Variant ID (Required)              
  }],
  address: { zip: '67676', city: 'Sterling', countryCode: 'US', provinceCode: 'KS'}		// Required
});

Shipping Address Submitted

TriplePixel('shippingSubmitted', {
  eventId: 'evt_sub_001',              // ID for cross-platform dedupe (Optional)
  email: '[email protected]',           // At least one of email or phone (Required)
  phone: '+1-555-123-4567',
  firstName: 'John',                   // Optional
  lastName: 'Doe',                     // Optional
  orderId: 'order_0000',               // System order ID (Optional)
  cotkn: '121212121212',               // Used for order<>journey matching (Optional)
  lineItems: [{
   i: '1234567',                       // Product ID (Required)                 
   q: 1,                               // Quantity (Required)             
   v: '654321'                	       // Variant ID (Required)                
  }],
  address: { zip: '67676', city: 'Sterling', countryCode: 'US', provinceCode: 'KS'}		// Required
});

Payment Submitted

TriplePixel('paymentSubmitted', {
  eventId: 'evt_sub_001',              // ID for cross-platform dedupe (Optional)
  email: '[email protected]',           // At least one of email or phone (Required)
  phone: '+1-555-123-4567',
  firstName: 'John',                   // Optional
  lastName: 'Doe',                     // Optional
  orderId: 'order_0000',               // System order ID (Required)
  cotkn: '121212121212',               // Used for order<>journey matching (Optional)
  lineItems: [{
   i: '1234567',                       // Product ID (Required)                 
   q: 1,                               // Quantity (Required)             
   v: '654321'                	       // Variant ID (Required)                
  }],
  address: { zip: '67676', city: 'Sterling', countryCode: 'US', provinceCode: 'KS'}		// Required
});

Purchase (Required for Attribution)

TriplePixel('Purchase', {
  eventId: 'evt_sub_001',              // ID for cross-platform dedupe (Optional)
  email: '[email protected]',           // At least one of email or phone (Required)
  phone: '+1-555-123-4567',
  firstName: 'John',                   // Optional
  lastName: 'Doe',                     // Optional
  orderId: 'order_0000',               // System order ID (Required)
  cotkn: '121212121212',               // Used for order<>journey matching (Optional)
  lineItems: [{
   i: '1234567',                       // Product ID (Required)                 
   q: 1,                               // Quantity (Required)             
   v: '654321'                	       // Variant ID (Required)           
  }],
  address: { zip: '67676', city: 'Sterling', countryCode: 'US', provinceCode: 'KS'}		// Required
});

Subscription Events

If your business relies on subscription-based orders, such as memberships or recurring billing, you can capture signups or orders in the Triple Whale Pixel.

Send a NewSubscription event when the user successfully signs up for a subscription.

TriplePixel('NewSubscription', {
  eventId: 'evt_sub_001',              // ID for cross-platform dedupe (Optional)
  email: '[email protected]',           // At least one of email or phone (Required)
  phone: '+1-555-123-4567',
  firstName: 'John',                   // Optional
  lastName: 'Doe',                     // Optional
  orderId: 'order_0000',               // System order ID (Required)
  subscriptionId: 'sub_0123',          // System subscription ID (required)
  cotkn: '121212121212',               // Used for order<>journey matching (Optional)
  lineItems: [{
   i: '1234567',                       // Product ID (Required)                 
   q: 1,                               // Quantity (Required)             
   v: '654321'                	       // Variant ID (Required)             
  }],
  address: { zip: '67676', city: 'Sterling', countryCode: 'US', provinceCode: 'KS'}		// Required
});

The most important fields are:

eventId, if you are capturing the same event data in another platform and want to reference the event across platforms
Contact details, such as email or phone, to help Triple Whale attribute future actions to the subscriber
subscriptionId, to identify the subscription in your system

Custom Events

With custom events, you can track any type of event that is relevant for your business.

Custom events can have whatever name you choose, and support passing any custom property that is relevant for that event.

TriplePixel('custom', 'scheduleDemo', {
  'action': 'booked_demo',
  'version': '1.0',
  'shop': 'example-shop.myshopify.com',
  'email': '[email protected]',
  'firstName': 'John',
  'lastName': 'Doe',
  'phone': '+1-555-123-4567'
});

Only the custom event name, such as scheduleDemo in the example above, is required. All other parameters are optional.

Custom events can also be marked as conversion events in your settings to enable attribution for those events.

For more information, see the Tracking Custom Events knowledge base article.

Step 4: Adding Page Context for Product Pages and Search Results

Certain types of pages call for passing additional context to the Triple Pixel:

Product Pages (Recommended): The TriplePixelData object should be updated with relevant product details to help fill in relevant product context for any on page actions (like Add to Cart events)

Search Results (Optional): The TriplePixelData object can also capture data about customer search terms to help in search related analysis.

Updating the TriplePixelData object on Product pages

To set product context for the Triple Pixel, you can dynamically update the TriplePixelData object in the base snippet with the relevant product details.

In the base tracking snippet:

Locate the line that contains TriplePixelData [the one that starts with window.TriplePixelData
- In the product variable, dynamically insert the product details for the current page
- It should be an object with the following fields: id, name, price, variant. For example, the populated product object should look like the following:

{
  id: '48269676624115',
  name: 'Top Knot Messy Bun Ponytail Holder',
  price: '42.99',
  variant: '8218652206806'
}

Updating the TriplePixelData object with user search details

When a user submits a search query, you can dynamically update the search variable in the TriplePixelData object to capture search context:

In the search variable, insert the query string (search term) of the user’s search
It should be a simple string containing the search string term. For example:

search: 'Ponytail Holder'

The product and search fields are optional. They should be configured to dynamically populate in scenarios where these values are present (on product pages, or after a user searches the website).

You can only pass one value for product per page and one value for search per page.

Example TriplePixel Data Objects

With product and search context:

{
  TripleName: 'shop.myshopify.com',
  isHeadless: true,
  plat: 'SHOPIFY',
  product: {
    id: '48269676624115',
    name: 'Top Knot Messy Bun Ponytail Holder',
    price: '42.99',
    variant: '8218652206806'
  },
  search: 'Ponytail Holder',
  ver: '2.16'
}

For pages without a product and/or search scope, the object properties can be left blank, like the following example:

{
  TripleName: 'shop.myshopify.com',
  isHeadless: true,
  plat: 'SHOPIFY',
  product: {
     id: '',
     name: '',
     price: '',
     variant: ''
   },
  search: '',
  ver: '2.16'
}

Additional Instructions for Single Page Applications (SPAs)

For Single Page Applications (SPAs), you need to configure additional page view events manually and ensure the correct context is set for each event.

Capturing Standard Page Views After the Initial Page

After the visitor navigates to a new page in your SPA, you need to trigger an additional, manual TriplePixel(‘pageLoad’) event.

TriplePixel('pageLoad')

Updating Page Context for Product Pages and User Searches

For pages with product context or user search context, you must dynamically update the Triple PixelData object with the relevant details.

Choose from the following methods to ensure proper tracking in your SPA.

Option 1: Send Context with Manually Triggered Page View Events

When a visitor navigates to a new "page" in your SPA:

Instead of simply calling TriplePixel('pageLoad'), pass the relevant context data along with the event.

TriplePixel('pageLoad', {
  product: {
     id: '123456', 
     name: 'Top Knot Messy Bun Ponytail Holder', 
     price: '29.80', 
     variant: '098765345' 
    }, 
  search: 'braids', 
  collection: '012345678' 
});

This ensures that each page load event in your SPA includes any updated product, search, or collection context.

Option 2: Update the window.TriplePixelData Object Before Firing Additional Page Views

When a visitor views a new page in your SPA:

Update the window.TriplePixelData object with the relevant context (e.g., product or search details).
Trigger the page view event by calling TriplePixel('pageLoad').
Reset window.TriplePixelData after firing the event so outdated information is not passed to future page views.

window.TriplePixelData.product = { 
  id: '48269676624115', 
  name: 'Top Knot Messy Bun Ponytail Holder', 
  price: '42.99', 
  variant: '8218652206806' 
};

TriplePixel('pageLoad');

Important: After firing the pageLoad event, ensure that you reset window.TriplePixelData to avoid passing outdated information.

Managing Tracking Consent

If a visitor to your shop or landing page opts out of tracking, you can send an event to Triple Whale so that we do not try to track the user's journey and attribute their future order to any source.

To disable tracking:

When you receive an opt-out from the user, call this event once:

TriplePixel('trackingConsent', false)

To allow tracking:

If a user opts in to tracking, you can reinitiate the Triple Pixel by firing the following event:

TriplePixel('trackingConsent', true)

Installing Using a Tag Manager

Although we recommend adding the Pixel directly to your website's <head> tags, the Pixel will work in most tag management and tag container solutions.

For specific advice on implementing the Pixel using your tag manager, please refer to your tag manager's documentation, and then verify it as described above.

Mobile Websites

If your mobile website is separate from your desktop website, you should add the Pixel to both sites. This will allow you to easily re-market to your mobile visitors, exclude them, or create lookalike audiences.

Alternative: Automated Installation with the AI Pixel CLI

If you prefer to skip the manual setup steps above, you can use our AI-powered CLI tool to automate the entire Triple Whale pixel installation for your headless or custom store.

The @triplewhale/pixel-cli analyzes your codebase and injects the correct pixel snippet and event tracking code into the right files.

Supported Frameworks

Framework	Status
Shopify Hydrogen (Remix-based)	Full Support
Next.js	Full Support
Gatsby	Full Support
Custom React (Vite/Webpack)	Full Support
Vue/Nuxt	Full Support

Quick Start

See the package on npm: https://www.npmjs.com/package/@triplewhale/pixel-cli

Frequently Asked Questions

Why does my Online Store section in Pixel Settings show "Not Installed" even though I manually installed the Pixel?

This status check looks specifically for the Shopify Theme App Embed. Headless installations do not use the theme app embed, so the system cannot detect the pixel in this section — even if it’s firing correctly.

Does this mean my pixel isn't working?

Not necessarily. If you see sessions and purchases tracking in Triple, that’s a strong indicator that your headless pixel installation is firing properly and collecting data as expected.

When should I be concerned?

You should only be concerned if:

You’re not seeing sessions or purchases in Triple Whale after installing using the instructions above.
Events are missing across all pages

If data is flowing normally, there’s no action needed.

Should I turn on Eval Restriction?

Most stores should leave Eval Restriction turned off.

Eval Restriction is an advanced compatibility setting for custom or headless storefronts with strict security settings. Turn it on only if Triple Whale Support or Engineering asks you to during troubleshooting.

For more help with Triple Pixel setup, see these related articles:

How to add the Triple Pixel to a headless store or custom website