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

// --- Sirdata configuration ---
// loadOnCheckoutOnly: controls whether the Sirdata pixel loads on all pages (false)
// or only on checkout pages (true).
// Recommended value for complete tracking if the server-side component is implemented ONLY in the custom pixel: false
// Recommended value for complete tracking if the server-side component is ALSO implemented on the main pages (in the Theme): true
window.loadOnCheckoutOnly = true;
// --- End of configuration ---

// Exposing Shopify APIs to the Sirdata remote script.
// In the lax sandbox, the `analytics`, `init` and `browser` variables are globals
// injected by Shopify. The script loaded dynamically below does not have direct
// access to them: we expose them via `window` so it can consume them.
window.apiAnalytics = analytics;
window.apiInit = init;
window.apiBrowser = browser;

// Initializing the sandbox dataLayer. Native Shopify events (page_viewed,
// checkout_started, purchase, etc.) are pushed here as soon as they fire.
// This dataLayer is read by the /shopify/custom-pixel script once loaded.
window.shopifyEventsDataLayer = window.shopifyEventsDataLayer || [];
analytics.subscribe("all_events", event => {
  window.shopifyEventsDataLayer.push(event);
});

// Dynamically loading the Sirdata script. document.head.appendChild is used
// instead of insertBefore because it is more robust in the sandbox environment
// (avoids errors if the script collection is empty).
(function() {
  var script = document.createElement('script');
  script.src = 'https://abc.your-subdomain.com/shopify/custom-pixel';
  script.async = true;
  document.head.appendChild(script);
})();

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

<script>
  window.shopifyDataLayer = window.shopifyDataLayer || [];
  window.shopifyDataLayer.push({ 'gtm.start': new Date().getTime(), event: 'gtm.js' });
</script>
<script src="https://abc.your-subdomain.com/shopify/loader" async></script>

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

---

3. Verifying the Installation

Network verification (recommended)

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.