<script id='coframe-installation-script'>
  (function () {
    // Early exit for performance testing
    if (/cf_disable/.test(location.search)) return console.warn('[Coframe] Disabled via URL parameter');
  
    // Coframe config
    const config = {
      projectId: 'YOUR_PROJECT_ID',
      startTime: Date.now(),
      timeoutMs: 1000,
      currentUrl: window.location.href,
    };
  
    // Prevent duplicate installation
    const script_id = 'coframe-sdk-js';
    if (document.getElementById(script_id)) return console.warn('[Coframe] SDK already installed');
  
    // Coframe queue setup
    (window.CFQ = window.CFQ || []).push({ config });
  
    // Coframe antiflicker CSS
    const style = document.createElement('style');
    style.id = 'coframe-antiflicker';
    style.textContent =
      ':root { --cf-show: 0;}' +
      'body { opacity: var(--cf-show) !important; transition: opacity 0.2s ease; }'
    function hide() { document.head.appendChild(style); }
    function show() {
      document.documentElement.style.setProperty('--cf-show', '1');
      style.parentNode && style.parentNode.removeChild(style);
    }
    hide(); setTimeout(show, config.timeoutMs);
  
    // Coframe SDK JS
    var edgeUrl = new URL('https://edge.cofra.me/cf.js');
    edgeUrl.searchParams.set('config', encodeURIComponent(JSON.stringify(config)));
  
    const script = document.createElement('script');
    script.id = script_id;
    script.async = true;
    script.src = edgeUrl.toString();
    script.onerror = () => { show(); console.error('[Coframe] SDK failed to load'); };
    document.head.appendChild(script);
  })();
</script>

<script id='coframe-installation-script'>
  (function () {
    // Early exit for performance testing
    if (/cf_disable/.test(location.search)) return console.warn('[Coframe] Disabled via URL parameter');
  
    // Coframe config
    const config = {
      projectId: 'YOUR_PROJECT_ID',
      startTime: Date.now(),
      timeoutMs: 1000,
      currentUrl: window.location.href,
    };
  
    // Prevent duplicate installation
    const script_id = 'coframe-sdk-js';
    if (document.getElementById(script_id)) return console.warn('[Coframe] SDK already installed');
  
    // Coframe queue setup
    (window.CFQ = window.CFQ || []).push({ config });
  
    // Coframe antiflicker CSS
    const style = document.createElement('style');
    style.id = 'coframe-antiflicker';
    style.textContent =
      ':root { --cf-show: 0;}' +
      'body { opacity: var(--cf-show) !important; transition: opacity 0.2s ease; }'
    function hide() { document.head.appendChild(style); }
    function show() {
      document.documentElement.style.setProperty('--cf-show', '1');
      style.parentNode && style.parentNode.removeChild(style);
    }
    hide(); setTimeout(show, config.timeoutMs);
  
    // Coframe SDK JS
    var edgeUrl = new URL('https://edge.cofra.me/cf.js');
    edgeUrl.searchParams.set('config', encodeURIComponent(JSON.stringify(config)));
  
    const script = document.createElement('script');
    script.id = script_id;
    script.async = true;
    script.src = edgeUrl.toString();
    script.onerror = () => { show(); console.error('[Coframe] SDK failed to load'); };
    document.head.appendChild(script);
  })();
</script>

(function() {
  if (/cf_disable/.test(location.search)) {
    console.warn('[Coframe][Shopify] Disabled via URL parameter');
    return;
  }
  window.CFQS = window.CFQS || [];
  function loadCoframeShopifyPixel() {
    const script_id = 'coframe-shopify-pixel';
    if (document.getElementById(script_id)) return console.warn('[Coframe][Shopify] Pixel already installed');
    const config = { projectId: 'YOUR_PROJECT_ID' };
    window.CFQS.push({ config });
    var scriptUrl = new URL('https://edge.cofra.me/coframe-shopify-pixel.js');
    scriptUrl.searchParams.set('config', encodeURIComponent(JSON.stringify(config)));
    const script = document.createElement('script');
    script.id = script_id;
    script.src = scriptUrl.toString();
    script.async = true;
    script.onerror = () => { console.error('[Coframe][Pixel] SDK failed to load'); };
    (document.head || document.documentElement).appendChild(script);
  }
  loadCoframeShopifyPixel();
  const dispatchCoframeEvent = (shopify_event) => { window.CFQS.push({ shopify_event }); };
  analytics.subscribe('product_added_to_cart', dispatchCoframeEvent);
  analytics.subscribe('checkout_started', dispatchCoframeEvent);
  analytics.subscribe('checkout_completed', dispatchCoframeEvent);
})();

# Shopify

Install Coframe in a Shopify theme, plus checkout tracking for Shopify Plus

This guide is for storefronts running on Shopify. You will add the Coframe
installation script to your theme’s `theme.liquid` file so that it runs on
every storefront page. If you are on Shopify Plus, a separate section below
covers checkout tracking via a Custom Pixel.


Use the Shopify app instead

Stores on Shopify should install the [Coframe Shopify app](../docs/shopify-app-overview.html): no
theme code, the pixel and order webhooks included, and anti-flicker managed
from the app. This page is the manual method for stores that cannot use the
app. Never run both; see
[migrating from the manual install](../docs/setup.html#migrating-from-the-manual-install).





[Video: Video: pasting into theme.liquid before </head>, saving, and verifying on the storefront (65s, narrated)](assets/videos/fig13-install-shopify.mp4)
Watch: 65s — pasting into theme.liquid before </head>, saving, and verifying on the storefront

## Shopify theme steps

- From your Shopify admin, go to Online Store → Themes.


- Find your active theme, click the **“…”** menu, and select Edit code.


- In the file tree on the left, open Layout* → *`theme.liquid`**.


- Locate the closing `</head>` tag and paste the installation script
(see below) immediately before it.


- Click Save.



The script must be pasted directly into `theme.liquid` — do not load it
through an async tag manager such as Google Tag Manager. Because anti-flicker
is enabled, the script needs to run synchronously before the browser renders
the page body. Loading it asynchronously through a tag manager defeats this and
will cause a visible flash of unstyled content.

## Installation script

Copy the script below and paste it into `theme.liquid` before `</head>`.
Replace `YOUR_PROJECT_ID` with the project ID from your Coframe dashboard.


HTML



```html
<script id='coframe-installation-script'>
  (function () {
    // Early exit for performance testing
    if (/cf_disable/.test(location.search)) return console.warn('[Coframe] Disabled via URL parameter');
  
    // Coframe config
    const config = {
      projectId: 'YOUR_PROJECT_ID',
      startTime: Date.now(),
      timeoutMs: 1000,
      currentUrl: window.location.href,
    };
  
    // Prevent duplicate installation
    const script_id = 'coframe-sdk-js';
    if (document.getElementById(script_id)) return console.warn('[Coframe] SDK already installed');
  
    // Coframe queue setup
    (window.CFQ = window.CFQ || []).push({ config });
  
    // Coframe antiflicker CSS
    const style = document.createElement('style');
    style.id = 'coframe-antiflicker';
    style.textContent =
      ':root { --cf-show: 0;}' +
      'body { opacity: var(--cf-show) !important; transition: opacity 0.2s ease; }'
    function hide() { document.head.appendChild(style); }
    function show() {
      document.documentElement.style.setProperty('--cf-show', '1');
      style.parentNode && style.parentNode.removeChild(style);
    }
    hide(); setTimeout(show, config.timeoutMs);
  
    // Coframe SDK JS
    var edgeUrl = new URL('https://edge.cofra.me/cf.js');
    edgeUrl.searchParams.set('config', encodeURIComponent(JSON.stringify(config)));
  
    const script = document.createElement('script');
    script.id = script_id;
    script.async = true;
    script.src = edgeUrl.toString();
    script.onerror = () => { show(); console.error('[Coframe] SDK failed to load'); };
    document.head.appendChild(script);
  })();
</script>
```

## Verify it is working

After saving `theme.liquid` and loading your storefront in a browser:



- Open the browser console and confirm there are no `[Coframe]` error messages.


- In the Network tab, look for a request to `edge.cofra.me/cf.js`. A
successful `200` response means the SDK loaded correctly.


- Check that a `coframe-sdk-js` script element appears in the DOM (you can
inspect the `<head>` in the Elements panel).





For a full walkthrough of how to validate the integration and confirm that
Coframe is operating as expected, see
[Testing and Validation](../docs/testing-and-validation.html).

## Shopify Plus — Checkout Tracking (Custom Pixel)

Shopify Plus merchants can track checkout events by adding Coframe as a Custom
Pixel. This is separate from the theme installation above and only applies to
the checkout flow.


Custom Pixel steps

- In your Shopify admin, go to Settings → Customer events.


- Click More views if the pixel list is not immediately visible, then
select Custom pixels.


- Click Add custom pixel and name it `coframe-tracking`.


- Paste the pixel script (see below) into the code editor.


- Click Save, then click Connect.



Pixel script
Replace `YOUR_PROJECT_ID` with the project ID from your Coframe dashboard.


JS



```
(function() {
  if (/cf_disable/.test(location.search)) {
    console.warn('[Coframe][Shopify] Disabled via URL parameter');
    return;
  }
  window.CFQS = window.CFQS || [];
  function loadCoframeShopifyPixel() {
    const script_id = 'coframe-shopify-pixel';
    if (document.getElementById(script_id)) return console.warn('[Coframe][Shopify] Pixel already installed');
    const config = { projectId: 'YOUR_PROJECT_ID' };
    window.CFQS.push({ config });
    var scriptUrl = new URL('https://edge.cofra.me/coframe-shopify-pixel.js');
    scriptUrl.searchParams.set('config', encodeURIComponent(JSON.stringify(config)));
    const script = document.createElement('script');
    script.id = script_id;
    script.src = scriptUrl.toString();
    script.async = true;
    script.onerror = () => { console.error('[Coframe][Pixel] SDK failed to load'); };
    (document.head || document.documentElement).appendChild(script);
  }
  loadCoframeShopifyPixel();
  const dispatchCoframeEvent = (shopify_event) => { window.CFQS.push({ shopify_event }); };
  analytics.subscribe('product_added_to_cart', dispatchCoframeEvent);
  analytics.subscribe('checkout_started', dispatchCoframeEvent);
  analytics.subscribe('checkout_completed', dispatchCoframeEvent);
})();
```

## Optional configuration

The default script is designed to work without additional configuration. Once
the SDK is installed, you can tune behavior using the following guides:



- [SDK options](../docs/sdk-options.html) — timeout, disable conditions,
and other core settings


- [Identity settings](../docs/identity-settings.html) — associate SDK
activity with a known user identity


- [Tracking settings](../docs/tracking-settings.html) — control which
events and page interactions Coframe records


- [Anti-flicker](../docs/anti-flicker.html) — understand how the anti-flicker
mechanism works and how to adjust it for your performance requirements