Tracking funnel events with the Polar Pixel

The Polar Pixel records the steps shoppers take on your store, from viewing a product to completing checkout. This article explains which funnel events are tracked automatically, what to check if events are missing, and how to track your own custom funnel events with the Polar Pixel SDK.

Standard funnel events

On a standard Shopify theme store, the Polar Pixel tracks these events automatically once it's installed. There's no code to write.

Missing events on the Funnel page?

1. Check that the Pixel is installed

Check your Pixel status in Polar. If it isn't installed, follow Using the Polar Pixel: Complete Installation & Tracking Setup Guide. As part of setup, make sure the Polar App Embed is turned on in your Shopify theme.

2. Check whether your store is headless

If your store doesn't use a Shopify theme (for example, it's built with Hydrogen, Next.js or another custom frontend), the Pixel can't fire events automatically. Your developer needs to send them with the Polar Pixel SDK. See Troubleshooting the Polar Pixel integration on Headless Stores.

3. Check for a third-party checkout

If you use a separate checkout or funnel tool, the Pixel needs to be added there as well to track checkout events. See How-To: Add the Polar Pixel to 3rd-Party Checkouts.

4. Check for an old Pixel version

Older versions of the Pixel may not send every funnel event. If you think you're on an older version, reach out through the in-app chat and we'll help you update it.

Track custom funnel events with the Polar SDK

If you want to track steps that aren't in the standard list, such as completing a product quiz, signing up for a newsletter, choosing a subscription, or seeing a specific A/B test variant, you can send custom funnel events with the Polar Pixel SDK. This works on both Shopify theme stores and headless stores.

Important: the Polar Pixel only listens to Shopify's standard events. Custom events that your theme, apps or A/B testing tools publish with Shopify.analytics.publish are not picked up automatically, and there is no setting in Polar that turns them on. They reach Polar only when they are sent with the SDK. On a Shopify theme store, the easiest way to do that is a Shopify Custom Pixel (see Option B below).

Before you start:

• Setting up custom events requires access to your website's code or your Shopify admin. These instructions are intended for your developer.

• The Polar Pixel endpoint is https://api-production.polaranalytics.com/pixel. Polar matches events to your store with your *.myshopify.com domain, so the endpoint is the same for every store.

Step 1: Send your custom events

Option A: Headless stores or your own site code

1. Install the SDK with npm install @polar-analytics/pixel-sdk. If your site can't use npm, load it with a <script> tag instead, as described in the SDK documentation.

2. Build the payload base with generatePayloadBase(). The SDK reads the page URL, referrer, UTM parameters and visitor ID for you.

3. Create the event with eventFactory.custom, giving it a clear, consistent name. The name becomes the key of your event.

4. Send the event with sendPixelEvent at the moment the shopper completes the step.

import { generatePayloadBase, sendPixelEvent, eventFactory } from "@polar-analytics/pixel-sdk";

const pixelEndpoint = "https://api-production.polaranalytics.com/pixel";
const payloadBase = await generatePayloadBase({});

const data = eventFactory.custom({
  shopifyEventName: "quiz_completed",   // the name of your custom event
  shopifyEventId: crypto.randomUUID(),  // unique for every event
  shopifyShopURL: "my-store.myshopify.com",
  shopifyEventData: { quizResult: "dry-skin" } // optional: any extra details, keep them flat
});

sendPixelEvent(pixelEndpoint, payloadBase, { data });

Option B: Shopify theme stores (forward events with a Custom Pixel)

If your theme or an app already publishes the event with Shopify.analytics.publish("my_event", { ... }), forward it to Polar from a Shopify Custom Pixel:

1. In Shopify, go to Settings > Customer events > Add custom pixel.

2. Paste the code below, replace the store domain and the event names, then Save and Connect.

const SHOP = "my-store.myshopify.com";
const ENDPOINT = "https://api-production.polaranalytics.com/pixel";

const sdk = new Promise((resolve, reject) => {
  const s = document.createElement("script");
  s.src = "https://unpkg.com/@polar-analytics/pixel-sdk@0.20.0/dist/index.global.js";
  s.onload = () => resolve(window.polarPixel);
  s.onerror = reject;
  document.head.appendChild(s);
});

function forward(event) {
  sdk.then(async ({ generatePayloadBase, sendPixelEvent, eventFactory }) => {
    const c = init.data.customer;
    const payloadBase = await generatePayloadBase({
      storage: browser.localStorage,
      document: event.context.document,
      navigator: event.context.navigator,
      customer: c ? { id: c.id, email: c.email } : null,
    });
    const data = eventFactory.custom({
      shopifyEventName: event.name,
      shopifyEventId: event.id,
      shopifyClientId: event.clientId,
      shopifyShopURL: SHOP,
      shopifyEventData: event.customData,
    });
    await sendPixelEvent(ENDPOINT, payloadBase, { data }, { useBeacon: false });
  });
}

// one line per custom event you publish from the theme
analytics.subscribe("quiz_completed", forward);

Tips for custom events:

• Use custom events only for non-standard steps. For standard events like add to cart or checkout started, use the matching standard SDK event instead. Sending them as custom events drops the event-specific data Polar needs.

• Use your *.myshopify.com domain for shopifyShopURL, not your customer-facing domain. Polar uses it to match events to your store.

• Keep event names consistent, for example always quiz_completed, so each step is reported as one event.

• Keep properties flat, for example { variant: "A" }, so each one can become a breakdown in Polar.

Step 2: Check that events are arriving

Open your browser's developer tools, go to the Network tab, and trigger the event. You should see a request to the Polar Pixel endpoint with a status of 200 or 204. For full setup details, including every event type and field, see the Polar Pixel SDK documentation.

Step 3: Make your custom events visible in Polar

Custom events aren't shown in Polar automatically, and there's no setting to switch on. Once your events are arriving, reach out to support through the in-app chat, or to your Customer Success Manager, with the names of your custom events and the properties you want to break down by (for example variant). We'll build the metrics and breakdowns in your account for you.

Example: tracking an A/B test variant

If your test shows different designs on the same URL (for example with Shopify Rollouts), Polar can't tell the variants apart on its own. Send two custom events, both carrying the same variant property:

1. A view event when the variant is shown, for example bf_variant_viewed with { variant: "A" }.

2. A conversion event when the shopper completes the variant's goal, for example bf_variant_converted with { variant: "A", type: "email_optin" } or { variant: "B", type: "account_created" }.

This gives you views, conversions and conversion rate per variant in Polar.

Polar does not link a Klaviyo sign-up or a Shopify account creation back to a variant on its own, so the conversion event is what makes the comparison reliable. If you also want to follow orders and revenue from shoppers who saw a variant, add a Shopify customer tag per variant (for example bf_variant_B) when the account is created, and break revenue down by customer tag.