Skip to main content

Pixel integration

What the pixel does​

The Sumeru pixel is a first-party JavaScript SDK that runs on your storefront. It captures:

  • Page views (PDP, collection, search, cart, checkout)
  • Product interactions (add to cart, remove, view)
  • Custom events (your code emits them)
  • Identity (when customer is identified — login, opt-in)

These feed into Customer 360, power segments, trigger journeys, and drive multi-touch attribution.

Install — Liquid theme​

Add to theme.liquid just before </head>:

<script src="https://pixel.sumeru.systems/v1/p.js"
        data-shop="{{ shop.permanent_domain }}"
        async></script>

That's it. The pixel auto-tracks page views, product views, and add-to-cart events without further config.

Install — Shopify Pixel API (cleanest)​

For Plus stores, register via Shopify's Pixel API for sandboxed loading + better performance:

// In your custom Shopify Pixel
import('https://pixel.sumeru.systems/v1/sandboxed.js').then(({ SumeruPixel }) => {
  const ap = new SumeruPixel({ shop: 'yourshop.com' });

  analytics.subscribe('product_viewed', (event) => {
    ap.track('product_viewed', { product_id: event.data.productVariant.product.id });
  });
  // etc.
});

Install — Headless / custom​

For Hydrogen, Next.js, custom React storefronts:

// app/layout.tsx or _app.tsx
import Script from 'next/script';

export default function Layout({ children }) {
  return (
    <html>
      <head>
        <Script
          src="https://pixel.sumeru.systems/v1/p.js"
          data-shop="yourshop.com"
          strategy="afterInteractive"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

For SPAs (no full page load between routes), call ap.track on route change manually.

Auto-tracked events​

EventWhen
page_viewEvery page load
product_viewedPDP rendered
add_to_cartAdd-to-cart button clicked
remove_from_cartRemove from cart
cart_viewedCart page rendered
checkout_startedCheckout page rendered
purchaseOrder completion (Shopify webhook auto-triggers)
searchSearch submitted (where detectable)

Custom events​

// On any user action
window.Sumeru?.track('newsletter_signup', {
  source: 'footer',
  list: 'main'
});

window.Sumeru?.track('video_played', {
  video_id: 'demo-2026',
  duration: 120
});

Events appear in Customer 360 + are available in segment rules and trigger journeys.

Identity​

Pixel tracks anonymously (cookie-based) until customer identifies themselves:

Identify on login​

// After Shopify login
window.Sumeru?.identify({
  email: 'jane@example.com',
  shopify_customer_id: '12345'
});

This merges anonymous session events with the identified customer profile (per Customer 360 identity merge).

Identify on opt-in​

// After exit-intent popup capture
window.Sumeru?.identify({
  email: capturedEmail
});

Privacy modes​

Standard (default)​

Cookie-based session. Captures all auto-events + identity when provided.

Privacy-first (CCPA / GDPR)​

Set before pixel loads:

<script>
window.SumeruConfig = {
  privacy: 'strict',
  consent: false  // wait for explicit consent
};
</script>
<script src="https://pixel.sumeru.systems/v1/p.js" async></script>

When consent: false, pixel only loads + makes no network calls. After user consents:

window.Sumeru?.consent(true);

Pixel begins tracking from that point.

Do-not-track​

Pixel respects navigator.doNotTrack === '1' automatically. No tracking unless you explicitly override (not recommended).

Performance​

MetricValue
Initial load~6 KB compressed
Strategyasync
Lighthouse impact< 1 point
Network callsBatched (5 sec or 50 events, whichever first)

The pixel is designed to be invisible to Core Web Vitals.

Verifying install​

After install, check admin: Settings → Pixel → "Events received in last hour" should be > 0 within 1 minute of visitor activity.

If 0:

  • Check browser console for pixel JS errors
  • Verify data-shop attribute matches your shop domain
  • Verify your CSP allows pixel.sumeru.systems

CSP requirements​

script-src https://pixel.sumeru.systems;
connect-src https://api.sumeru.systems;

Debugging​

Enable debug mode:

<script src="https://pixel.sumeru.systems/v1/p.js?debug=1"
        data-shop="yourshop.com"></script>

Logs every event to console.

See also​