Using Instant Audiences with a Shopify Headless Store

Instant has native integrations into Shopify and BigCommerce. Shopify Headless stores require a custom integration, with five steps:

Installing Instant's Identification Pixel
Connecting to the Shopify API
Installing Instant's Custom Pixel
Tracking Customer Events
Updating Event Properties

Please contact your customer success manager if you experience any issues. We are happy to guide you or your developers through this implementation if needed.

Step 1: Installing Instant's Identification Pixel

The first step of the integration process requires adding Instant's pixel to your site. This allows Instant to identify anonymous shoppers who visit your website.

Proceed to the Instant dashboard and go to Configuration > Select Shopify Headless. You will see instructions to complete your pixel setup under Step 1: Pixel Installation.
Follow these instructions and verify your integration.

Step 2: Connecting to Shopify's API

The second step of the integration process requires connecting to Shopify's API.

Proceed to the Instant dashboard and go to Configuration > Select Shopify Headless. You will see the instructions for connecting to Shopify's API under "Step 2".
Follow these instructions and verify your integration.

Step 3: Installing Instant's Custom Pixel

The third step of the integration process requires adding a custom pixel to your site. This ensures we are able to identify customers across all pages in your headless site.

Proceed to the Instant dashboard and go to Configuration > Select Shopify Headless. You will see a pixel under the section titled Step 3: Custom Pixel.
Add this pixel to the <head> tag of your website's HTML.

Step 4: Tracking Customer Events

Event triggers determine when Instant interaction events are sent and contain the payload data for Klaviyo.

Throughout your website, where you would be sending events to Klaviyo, also send them to Instant Audiences by copy pasting the following snippet just below. See examples below.

window.InstantJS.track("EVENT_TYPE", [{
    provider: "KLAVIYO",
    event: EVENT_DATA
}]);

Replace EVENT_TYPE with the type of event you wish to send.
Replace EVENT_DATA with the data you'd like to send to Audiences. Audiences will then send this data through to your marketing integrations such as Klaviyo. Please note that the structure of this event data payload does not matter. Audiences will simply forward this payload through to Klaviyo.

Note that the available events are as follows:

PAGE_VIEWED
COLLECTION_VIEWED
PRODUCT_VIEWED
ITEM_ADDED_TO_CART
CART_VIEWED
CHECKOUT_STARTED

Example: Checkout started events

To track when a customer starts the checkout flow, you'll need to execute the following JavaScript code as soon as someone visits the checkout page. The payload data serves as a placeholder to demonstrate the required data structure for Instant Audiences.

window.InstantJS.track("CHECKOUT_STARTED", [
  {
    provider: "KLAVIYO",
    event: {
      CheckoutURL: "",
      Items: [
        {
          ProductName: "",
          Quantity: "1",
          ItemPrice: "19.95",
          ImageURL:
            ""
        },
        {
          ProductName: "",
          Quantity: "1",
          ItemPrice: "221.95",
          ImageURL:
            ""
        },
      ],
    },
  },
]);

Example: Add to cart events

To track when a customer adds an item to their cart, you'll need to execute the following JavaScript code when the “Add to Cart” button is clicked.

One implementation method is to add an event listener to the "Add to Cart" button on relevant pages. When clicked, this will trigger the code shown below. The payload data serves as a placeholder to demonstrate the required data structure for Instant Audiences.

window.InstantJS.track("ITEM_ADDED_TO_CART", [
  {
    provider: "KLAVIYO",
    event: {
      CheckoutURL: "",
      Items: [
        {
          ProductName: "",
          Quantity: "1",
          ItemPrice: "19.95",
          ImageURL: "",
        },
        {
          ProductName: "",
          Quantity: "1",
          ItemPrice: "221.95",
          ImageURL: "",
        },
      ],
    },
  },
]);

Example: Product viewed events

To track product views, you'll need to execute the following JavaScript code whenever a customer lands on a product page.

One implementation method is to add the following code snippet to the source code of your product page template. This code will trigger when a customer visits the page. The payload data serves as a placeholder to demonstrate the required data structure for Instant Audiences.

window.InstantJS.track("PRODUCT_VIEWED", [
  {
    provider: "KLAVIYO",
    event: {
      ProductName: "",
      ItemPrice: "370.00",
      ImageURL: ""
    },
  },
]);

Step 5: Update Event Properties

In the code snippet above, the PRODUCT_VIEWED event has a structured event payload:

event: {
  ProductName: "",
  ItemPrice: "370.00",
  ImageURL: ""
}

The properties in this payload will need to match the properties used in your email templates. For example, if you use the property 'event.item_price' in your templates, you will need to change the 'ItemPrice' property to 'item_price'. Similarly, this must be done for any properties your email templates require that are not included in our payload.

Please ensure you are passing through all the necessary data required in your email templates.

If you make updates to your email templates without updating your integration, Klaviyo may receive incomplete data.

Once this is finalised, your integration with Instant Audiences is complete.

Please reach out to your customer success manager if you require any assistance.