> For the complete documentation index, see [llms.txt](https://server-side.docs.sirdata.net/sirdata-server-side/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://server-side.docs.sirdata.net/sirdata-server-side/english-1/installation/cms/shopify-configuration.md).

# 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);
})();
```

5. 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>
```

{% hint style="info" %}
*Do not forget to replace `abc.your-subdomain.com` with your Sirdata tracking domain.*
{% endhint %}

***

### 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.