Install

Shopify checkout

Shopify runs no theme scripts on checkout, so checkout events come through a custom pixel.

Shopify does not run theme scripts on its checkout pages. Its checkout events are available only through Shopify's Web Pixels API, as a custom pixel pasted into the Shopify admin. The pixel runs in Shopify's own sandbox, not on your pages, and forwards Shopify's events to Parlox.

Keep the pinned tag in your theme as well: it is what detects browser agents on your storefront. The pixel shares the tag's session id, so checkout events land in the same visit.

Add the pixel

  1. In the Shopify admin, go to Settings → Customer events → Add custom pixel, and name it Parlox.
  2. Set the permission to Analytics, and data sale to Data collected does not qualify as data sale: nothing in it identifies a person.
  3. Paste the code below, with your site's public key in place of pk_….
  4. Save, then Connect.
Parlox custom pixel
const KEY = 'pk_…';
const ENDPOINT = 'https://gateway.parlox.io/v1/b';
const MAP = {
  product_viewed: 'view_item', product_added_to_cart: 'add_to_cart', product_removed_from_cart: 'remove_from_cart',
  cart_viewed: 'view_cart', checkout_started: 'begin_checkout', checkout_contact_info_submitted: 'checkout_step',
  checkout_address_info_submitted: 'checkout_step', checkout_shipping_info_submitted: 'add_shipping_info',
  payment_info_submitted: 'add_payment_info', checkout_completed: 'purchase', search_submitted: 'search', page_viewed: 'page_view'
};
async function sessionId() {
  try {
    const saved = JSON.parse((await browser.sessionStorage.getItem('_plx')) || 'null');
    if (saved && saved.id && Date.now() - saved.t < 30 * 60 * 1000) return saved.id;
  } catch (e) {}
  const id = Array.from(crypto.getRandomValues(new Uint8Array(12)), (b) => b.toString(16).padStart(2, '0')).join('');
  try { await browser.sessionStorage.setItem('_plx', JSON.stringify({ id, t: Date.now(), pv: 0 })); } catch (e) {}
  return id;
}
// Checkout and order URLs carry capability tokens: only the shape of the path is sent, and of the referrer only its origin.
function pathShape(href) {
  return href.replace(/(\/checkouts\/(?:[a-z]{1,3}\/)?)[^/?#]+/, '$1:token').replace(/(\/orders\/)[^/?#]+/, '$1:token').replace(/[?#].*$/, '');
}
function originOf(href) { try { return new URL(href).origin + '/'; } catch (e) { return null; } }
analytics.subscribe('all_standard_events', async (event) => {
  const name = MAP[event.name];
  if (!name) return;
  const doc = (event.context && event.context.document) || {};
  const rawHref = (doc.location && doc.location.href) || '';
  // The theme's browser part counts storefront pages; the pixel covers checkout, where theme scripts cannot run.
  if (name === 'page_view' && !/\/checkouts\//.test(rawHref)) return;
  const props = { via: 'shopify_pixel' };
  const d = event.data || {};
  if (d.checkout) {
    props.value = Number(d.checkout.totalPrice && d.checkout.totalPrice.amount);
    props.currency = d.checkout.currencyCode;
    props.items = (d.checkout.lineItems || []).length;
    if (d.checkout.order && d.checkout.order.id) props.order_id = String(d.checkout.order.id);
  }
  if (d.cartLine) {
    props.value = Number(d.cartLine.cost && d.cartLine.cost.totalAmount && d.cartLine.cost.totalAmount.amount);
    props.currency = d.cartLine.cost && d.cartLine.cost.totalAmount && d.cartLine.cost.totalAmount.currencyCode;
    props.items = d.cartLine.quantity;
    props.item_id = String((d.cartLine.merchandise && d.cartLine.merchandise.product && d.cartLine.merchandise.product.id) || '');
  }
  if (event.name === 'checkout_contact_info_submitted') props.step = 'contact';
  if (event.name === 'checkout_address_info_submitted') props.step = 'address';
  const body = { k: KEY, pixel: 1, sid: await sessionId(), url: pathShape(rawHref), ref: doc.referrer ? originOf(doc.referrer) : null,
                 events: [{ eid: crypto.randomUUID(), ev: name, t: 0, props }] };
  fetch(ENDPOINT, { method: 'POST', body: JSON.stringify(body), keepalive: true, mode: 'no-cors' }).catch(() => {});
});

What it sends

Shopify eventSent to Parlox as
product_viewedview_item
product_added_to_cartadd_to_cart
product_removed_from_cartremove_from_cart
cart_viewedview_cart
checkout_startedbegin_checkout
checkout_contact_info_submitted, checkout_address_info_submittedcheckout_step (step: contact, address)
checkout_shipping_info_submittedadd_shipping_info
payment_info_submittedadd_payment_info
checkout_completedpurchase, with Shopify's order id
search_submittedsearch
page_viewedpage_view, on checkout pages only (the theme's tag counts the storefront)

Each event carries only the visit's session id, the total, the currency, the number of items, a product or order id and the checkout step. Checkout and order addresses carry capability tokens, so only the shape of the path is sent (/checkouts/:token), and of the referrer only its origin.

Trust

Events from the pixel are marked shopify_pixel, and a purchase from the pixel moves the visit to "purchased", as one from your server does. The pixel sends with your site's public key, like the tag; an order posted from your server with a send key is the one no one else can send.

The pixel's requests come from Shopify's sandbox, so the gateway accepts a Shopify origin for them, and still requires the page address to be on your site's domain.

Check it

Add a product to the cart and start a checkout in a normal browser, then open that visit in the dashboard's Visits view. Its timeline shows the steps with their source, "Shopify".