For the complete documentation index, see llms.txt. This page is also available as Markdown.

Shopify - Configuration

Shopify Server-Side Implementation — Installation Guide

This guide covers the full deployment of the Sirdata server-side solution on a Shopify store. The installation relies on two separate components:

  1. A custom Pixel (Customer Events): collects events within the Shopify sandbox context.

  2. A loader script: injected into the main theme, it handles the connection with your tracking server.

Architecture: two contexts, two dataLayers

Before getting started, it is important to understand the technical separation between the two execution environments. Although they coexist on the same page, they operate in isolated worlds.

Context

Variable

Role

Shopify sandbox iframe (Custom Pixel)

window.shopifyEventsDataLayer

Receives native Shopify events (page_viewed, checkout_started, etc.)

Main page (theme.liquid)

window.shopifyDataLayer

Serves as the dataLayer for the Sirdata loader, replacing the GTM dataLayer

These two variables do not share the same scope. The remote script loaded from the sandbox iframe (/shopify/custom-pixel) retrieves shopifyEventsDataLayer from its sandboxed context. The loader (/shopify/loader), on the other hand, runs on the main page and reads shopifyDataLayer. Communication between the two is handled on the Sirdata server side.


1. Configuring the Custom Pixel (Customer Events)

Shopify isolates third-party pixels in a lax sandbox (cross-origin iframe). This model is less restrictive than a strict sandbox (web worker): it allows DOM access, dynamic <script> element creation and the use of standard browser APIs. This is why dynamically loading an external script works in this context.

Configuration steps

  1. From your Shopify admin, go to Settings > Customer events.

  2. Click Add custom pixel.

  3. Name it (e.g.: Sirdata_Server_Side).

  4. In the Code section, insert the following script:

Before saving: replace abc.your-subdomain.com with your actual Sirdata tracking domain.

JavaScript

  1. Click Save, then Connect the pixel.


2. Adding the Loader Script to the Theme

The loader must be present on all pages of the store. It initializes the main dataLayer and loads the Sirdata server script from the page context (outside the sandbox).

If GTM is currently installed on the theme: this script fully replaces the GTM snippet. Remove the existing GTM <script> block from theme.liquid before pasting the code below.

Integration steps

  1. Go to Online Store > Themes.

  2. On the active theme, click the three dots (...) > Edit code.

  3. Open the theme.liquid file.

  4. Paste the following code into the <head> tag, as high as possible:

HTML

Do not forget to replace abc.your-subdomain.com with your Sirdata tracking domain.


3. Verifying the Installation

In Chrome DevTools, open the Network tab and filter by your tracking subdomain (e.g.: abc.your-subdomain.com). Browse the store and check that the following requests appear with a 200 OK status:

  • /shopify/loader

  • /shopify/custom-pixel

Verifying the sandbox dataLayer

The Custom Pixel runs in an isolated iframe. The window.shopifyEventsDataLayer variable is not accessible from the main page context — typing this command in the console will return nothing.

To inspect it, there are two approaches:

Option A — Shopify Pixel Helper

Install the Shopify Pixel Helper Chrome extension, which inspects active pixels and fired events without manual DevTools manipulation.

Option B — Iframe context in Chrome DevTools

  1. Open the Console tab.

  2. In the dropdown menu to the left of the prompt (default: top), select the Shopify sandbox iframe context (often named Sandbox... or linked to the pixel URL).

  3. Type window.shopifyEventsDataLayer to view the collected events.


⚠️ Points of attention before going into production

DNS and Sirdata configuration

The tracking subdomain (e.g.: abc.your-subdomain.com) must be configured in your Sirdata interface and point to the Sirdata servers via a CNAME DNS record. Make sure DNS propagation is complete before testing.

GTM conflict

If the GTM snippet is not removed from the theme before adding the loader, both scripts will coexist and may generate duplicate events.

Scope of the loadOnCheckoutOnly flag

Setting this flag to true restricts the loading of the Sirdata pixel to checkout pages only.

  • Useful if you want to limit tracking to conversion events.

  • Drawback: navigation (Upper Funnel) and catalog events will then not be collected by this component.

Mis à jour