Why Custom Sites Require Manual Pixel Install

At Triple Whale, we want to ensure that we're constantly capturing all the data you need to make informed decisions that drive growth for your brand. That is why we encourage users to utilize our one-click Pixel Auto-Install method.

However, If you have a headless front-end built on top of your store, our Auto-Install method will not be able to add the Pixel script to those pages. Because those pages are technically hosted outside of your store (even though your site visitors may not notice it), Triple Whale does not have the permissions needed to write code to those pages.

In this article, we will show you how to manually install the Triple Pixel to your headless front-end store. We will also provide guidance how to record ‘Add to Cart’ events in the Triple Pixel, as well as record contact info events (these two are optional).

If you have a site manager on your team who is more comfortable dealing with Javascript code, we'd recommend sending him these instructions.

For installing the Triple Pixel on a third-party Landing Page, click here.

For installing the Triple Pixel on a front-end Headless store, click here.

For installing the Triple Pixel on a third-party Checkout, click here.

Step 1: Install the Base Tracking Snippet

The base tracking snippet can be found in the "headless installation" tab on on the Pixel Settings page.

Navigate to the “Headless Installation” tab and copy the base snippet.
Install the snippet in the <head> of all site pages

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

Testing Your Installation

Open any page where you have installed the pixel and open the developer console in your browser.
Enter 'TriplePixelData' into your console to validate that the TriplePixelData object is present
1. If you see undefined, please go back and ensure:
  1. The code was added within the <head> tags of the page
  2. Any cached HTML content is purged (this varies per platform and content delivery network - please consult with your technical team)

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:'madison@gmail.com', phone:'123-456-7891'});

When passing a ‘contact’ event, you must pass at least one of the fields ‘email’ or ‘phone’, or 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

Standard Events

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

Note: You should ensure that the Triple Pixel has successfully initialized before triggering any events.

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', //insert product ID
  q: 1, 
  v: '654321' //insert variant ID 
});

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

Checkout Events

We recommend implementing the following events to track the entire checkout funnel. While most fields are optional, passing more data improves tracking accuracy.

Checkout Started

TriplePixel('checkoutStarted', {
  eventId: 'n65N65', // Optional - should match the eventID used when sending the same event to other platforms to assist in event deduplication
  email: 'user@email.com',
  phone: '1234567',
  firstName: 'First',
  lastName: 'Name',
  orderId: 'order_0000',
  cotkn: '121212121212', // Additional token/data relevant to your system
  lineItems: ['3333333', '555555'], // The product IDs or SKUs
  address: {
    zip: '67676',
    city: 'Sterling',
    countryCode: 'US',
    provinceCode: 'KS'
  }
});

Contact Information Submitted

TriplePixel('contactSubmitted', {
  eventId: 'n65N65', // Optional - should match the eventID used when sending the same event to other platforms to assist in event deduplication
  email: 'user@email.com',
  phone: '1234567',
  firstName: 'First',
  lastName: 'Name',
  order_id: 'order_0000',
  cotkn: '121212121212', // Additional token/data relevant to your system
  lineItems: ['3333333', '555555'], // The product IDs or SKUs
  address: {
    zip: '67676',
    city: 'Sterling',
    countryCode: 'US',
    provinceCode: 'KS'
  }
});

Billing Address Submitted

TriplePixel('addressSubmitted', {
  eventId: 'n65N65', // Optional - should match the eventID used when sending the same event to other platforms to assist in event deduplication
  email: 'user@email.com',
  phone: '1234567',
  firstName: 'First',
  lastName: 'Name',
  order_id: 'order_0000',
  cotkn: '121212121212', // Additional token/data relevant to your system
  lineItems: ['3333333', '555555'], // The product IDs or SKUs
  address: {
    zip: '67676',
    city: 'Sterling',
    countryCode: 'US',
    provinceCode: 'KS'
  }
});

Shipping Address Submitted

TriplePixel('shippingSubmitted', {
  eventId: 'n65N65', // Optional - should match the eventID used when sending the same event to other platforms to assist in event deduplication
  email: 'user@email.com',
  phone: '1234567',
  firstName: 'First',
  lastName: 'Name',
  order_id: 'order_0000',
  cotkn: '121212121212', // Additional token/data relevant to your system
  lineItems: ['3333333', '555555'], // The product IDs or SKUs
  address: {
    zip: '67676',
    city: 'Sterling',
    countryCode: 'US',
    provinceCode: 'KS'
  }
});

Payment Submitted

TriplePixel('paymentSubmitted', {
  eventId: 'n65N65', // Optional - should match the eventID used when sending the same event to other platforms to assist in event deduplication
  email: 'user@email.com',
  phone: '1234567',
  firstName: 'First',
  lastName: 'Name',
  order_id: 'order_0000',
  cotkn: '121212121212', // Additional token/data relevant to your system
  lineItems: ['3333333', '555555'], // The product IDs or SKUs
  address: {
    zip: '67676',
    city: 'Sterling',
    countryCode: 'US',
    provinceCode: 'KS'
  }
});

Purchase (Required for Attribution)

TriplePixel('purchase', {
  eventId: 'n65N65', // Optional - should match the eventID used when sending the same event to other platforms to assist in event deduplication
  email: 'user@email.com',
  phone: '1234567',
  firstName: 'First',
  lastName: 'Name',
  order_id: 'order_0000',
  cotkn: '121212121212', // Additional token/data relevant to your system
  lineItems: ['3333333', '555555'], // The product IDs or SKUs
  address: {
    zip: '67676',
    city: 'Sterling',
    countryCode: 'US',
    provinceCode: 'KS'
  }
});

Subscription Events

If your business relies on subscription-based orders (for example, a membership or recurring billing model), you can capture these signups or orders in the Triple Whale Pixel. By sending a `NewSubscription` event to Triple Whale, you’ll see these events surfaced in the Triple Whale customer journey.

Below is an example of the code snippet you can fire once the user successfully signs up for a subscription:

TriplePixel('NewSubscription', {
  eventId: 'n65N65', // Optional - should match the eventID used when sending the same event to other platforms to assist in event deduplication
  email: 'user@email.com',
  phone: '1234567',
  firstName: 'First',
  lastName: 'Last',
  orderId: 'order_0000',
  subscriptionId: 'sub_0123',
  cotkn: '121212121212', // Additional token/data relevant to your system
  lineItems: ['3333333', '555555'], // The product IDs or SKUs
  address: {
    zip: '67676',
    city: 'Sterling',
    countryCode: 'US',
    provinceCode: 'KS'
  }
});

The parameters above are typical fields you may want to pass, but you can customize them based on your own data needs. The most important fields are the eventId (if you are capturing the same event data in another platform, so you can reference this event in other platforms) and any contact details (email or phone) that help Triple Whale attribute future actions to this specific subscriber.

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': 'john.doe@example.com',
'firstName': 'John',
'lastName': 'Doe',
'phone': '+1-555-123-4567'
});

Only the event name (scheduleDemo in the example) is required. All parameters/fields are optional and can be whatever you'd like to track with the event.

Custom Events can also be marked as ‘conversion events’ in your settings to enable attribution for these events.

For more information on setting up and tracking custom events, 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').

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.

How to Uninstall the Triple Pixel from a Shopify Store

Sonar Setup for Headless Shopify Stores

Sonar Setup for BigCommerce Shops (Beta)

Sonar Setup for WooCommerce Shops (Beta)

Adding the Triple Pixel to a Headless Store or Custom Website