§ 01

Installation

Install the TrackLayer browser pixel on your store. Works with Shopify, WooCommerce, PrestaShop, or any custom frontend. One script tag, auto page_view, DOM click tracking, and sendBeacon resilience.

Installing the TrackLayer pixel

TrackLayer ships a 3.3 KB browser pixel that you drop into your site's <head>. It auto-fires page_view on load, listens for DOM events you mark with data-tl-event, and batches sends through navigator.sendBeacon with a fetch({keepalive:true}) fallback so events aren't lost on page unload.

1. Get your merchant ID

After creating an account at app.tracklayer.io, you'll find your merchant ID on the Onboarding · Step 2 page, or in Settings → Account. It's a UUID like 5353bbf0-07ad-4636-98c6-64861af1b8c9.

2. Drop the snippet

Add this to your site's <head> — ideally before any other analytics or ad-platform scripts, so the pixel is online when they need shared cookies.

<script
  src="https://tracklayer-ingestion.sublime.workers.dev/v1/pixel.js"
  data-merchant="YOUR_MERCHANT_ID"
  async
></script>

The pixel:

Reads data-merchant from its own script tag
Auto-fires page_view when the DOM is ready
Adds a global click listener for any element with data-tl-event="name"
Posts events to /v1/browser/events on the same origin as the pixel file
Uses navigator.sendBeacon for fire-and-forget with fetch({keepalive:true}) as fallback
Reads first-party cookies for identity stitching: _fbp, _fbc, _ga, _ttp, _rdt_uuid

3. Track events declaratively

The simplest way to track interactions — add data-tl-event to any element. The pixel's click listener handles the rest.

<button data-tl-event="add_to_cart" data-tl-props='{"value": 49.99, "currency": "USD"}'>
  Add to cart
</button>
 
<button data-tl-event="begin_checkout">Checkout</button>

data-tl-props (optional) takes a JSON-encoded object that's merged into the event payload. Pass value, currency, order_id, items, num_items, or any custom field.

4. Track events programmatically

For events that don't correspond to a DOM click — a purchase confirmation, a form submit, a scroll-depth trigger — call window.tl.track() directly.

<script>
  window.tl.track("purchase", {
    event_id: "order-12345",
    value: 129.99,
    currency: "USD",
    order_id: "12345",
    items: [
      { id: "SKU-A", quantity: 1, price: 129.99, name: "T-Shirt" }
    ],
    num_items: 1,
  });
</script>

The 32 canonical events

TrackLayer's classifier maps any event name you send to one of 32 canonical events. Common ones:

Event	When to fire
`page_view`	Automatic — every navigation
`view_item`	Product detail page loads
`add_to_cart`	User adds product to cart
`begin_checkout`	User starts checkout flow
`add_payment_info`	Payment method selected
`purchase`	Order confirmation page
`refund`	Refund processed
`sign_up` / `login`	Account events
`search`	Search result rendered

The full list and per-platform mappings are in the Events reference.

5. Verify the pixel is working

Open your dashboard at app.tracklayer.io/overview. The EVENTS · 24H KPI updates every few seconds. If you see it climb when you navigate your store, the pixel is live.

If no events are showing after a few minutes:

Open browser DevTools → Network. Filter on v1/browser/events. You should see 202 responses.
Check the Console for warnings prefixed [tracklayer].
Confirm your data-merchant value is the exact UUID from Settings — no spaces, no quotes.
Visit /v1/pixel.js directly — it should serve JavaScript, not HTML.

Next steps

Connect a CAPI platform — Meta, TikTok, Google Ads, GA4, and 8 more
Define routing rules — route specific events to specific platforms
Monitor event quality — see per-event validation + coverage