Tracker SDK

Lightweight JavaScript snippet that captures visitor behavior on your Shopify storefront.

The Pique tracker is a lightweight JavaScript snippet that runs on your Shopify storefront. It automatically captures visitor behavior and sends events to Pique for analysis.

Installation

Add this script tag to your Shopify theme (typically in theme.liquid before the closing </body> tag). Replace YOUR_API_KEY with your project API key from Settings.

<script src="https://your-pique-domain.com/api/tracker.js?key=YOUR_API_KEY"></script>

The script is served from your Pique instance via the /api/tracker.js endpoint. It initializes automatically — no additional setup code is needed.

Auto-tracked events

The tracker detects Shopify page structure and fires the following events without any configuration:

Event	Trigger
page_viewed	Every page load
product_viewed	URL contains /products/ — extracts title, price, and image from Open Graph meta tags
collection_viewed	URL contains /collections/
add_to_cart	Intercepts fetch() and form submissions to /cart/add
purchase	Detected on Shopify /thank_you pages via window.Shopify.checkout
identify	Auto-captured from purchase email or ShopifyAnalytics traits
heartbeat	Fires every 30s while the tab is visible — used for session windowing
session_end	Sent on beforeunload via sendBeacon

Manual tracking

The tracker exposes a global window.pique object. You can send custom events from anywhere:

window.pique.track("custom_event", {
  key: "value",
  anotherKey: 42
});

Manual identification

If you capture the visitor's email before checkout (e.g., a newsletter signup or login), call identify to associate the anonymous visitor ID with a known email:

window.pique.identify("customer@example.com", "Jane Doe");

Identification is deduplicated — only the first call per page load takes effect.

Purchase tracking

Purchases are auto-detected on Shopify /thank_you pages using window.Shopify.checkout. The tracker extracts the order ID, total, currency, and item count, and deduplicates by order ID in localStorage.

For non-Shopify checkout flows or headless setups, track purchases manually:

window.pique.track("purchase", {
  orderId: "1234",
  orderTotal: 89.99,
  currency: "USD",
  itemCount: 3
});

Visitor ID

The tracker generates a UUID and stores it in localStorage under the key pq_vid. This persists across sessions on the same browser. You can read it with:

window.pique.vid

Event batching

Events are queued in memory and flushed to POST /api/v1/track/batch every 2 seconds, or immediately when the queue reaches 10 events. On page unload, remaining events are flushed with sendBeacon to avoid data loss.