# Install on Shopify

Paste one script tag into your theme's `theme.liquid`, save, and open your store. It runs on the pages your theme renders: home, collections, products, cart, search and classic account pages. It does not run on checkout (see [Checkout](#checkout-thank-you-and-order-status-pages)).

Platform steps checked against the official Shopify documentation on 2026-11-03: [Editing theme code](https://help.shopify.com/en/manual/online-store/themes/theme-structure/extend/edit-theme-code), [checkout.liquid](https://shopify.dev/docs/storefronts/themes/architecture/layouts/checkout-liquid), [Checkout Extensibility upgrade guide](https://help.shopify.com/en/manual/checkout-settings/checkout-extensibility/checkout-upgrade), [Custom pixels](https://help.shopify.com/en/manual/promoting-marketing/pixels/custom-pixels), [Web pixels and sandboxes](https://shopify.dev/docs/apps/build/marketing-analytics/pixels), [Theme app extensions](https://shopify.dev/docs/apps/build/online-store/theme-app-extensions), [Liquid customer object](https://shopify.dev/docs/api/liquid/objects/customer).

## Quick install

Settings › Channels in the Telltale dashboard shows this tag with your real key already filled in. Copy it from there.

```html
<script src="https://app.trytelltale.dev/sdk/v1.js" data-telltale-key="YOUR_SITE_PUBLISHABLE_KEY"></script>
```

1. In your Shopify admin, go to Online Store › Themes.
2. Next to your current (published) theme, open the **⋯** menu and choose **Edit code**.
3. Under **layout**, open `theme.liquid`.
4. Find the closing `</head>` tag and paste the tag on the line just before it.
5. Choose **Save**.

Before you edit, you can keep a copy: from the same **⋯** menu, choose **Duplicate**. Editing a theme you have not published only changes that copy, so make sure you edit the one your customers see.

**Why not an app embed or a custom pixel?** Theme app embeds are made by apps; you cannot add one without an app that ships it. If Telltale ships a Shopify app, it will use an app embed, and this page will say so. Until then, `theme.liquid` is the way. Customer events (custom pixels) run inside a sandboxed frame that cannot see the storefront page, so they cannot observe how the page is used. Do not install Telltale as a custom pixel.

## Consent

The tag records from page load. That is right for stores that show no cookie or consent banner.

If your store shows a banner (Shopify's own cookie banner or an app's), hold the tag: add `data-telltale-wait-for-consent`. A held tag sends nothing at all until you call `optIn()`.

```html
<script src="https://app.trytelltale.dev/sdk/v1.js" data-telltale-key="YOUR_SITE_PUBLISHABLE_KEY" data-telltale-wait-for-consent></script>
```

Then, wherever your banner reports the visitor's choice, call:

```javascript
// When the banner allows measurement:
window.Telltale.getClient().optIn();
// When the visitor refuses or withdraws:
window.Telltale.getClient().optOut();
```

Apply the saved decision on every page load, and again each time it changes. Signing in is not consent. For OneTrust, Cookiebot or Sourcepoint, use the [Consent bridge guide](/docs/consent) and the [OneTrust](/docs/consent-onetrust), [Cookiebot](/docs/consent-cookiebot) or [Sourcepoint](/docs/consent-sourcepoint) recipe.

## Identify the signed-in customer

Link each session to the customer who is signed in. Shopify's customer ID is a stable number. Never send the e-mail address, name or phone number.

**From your server (recommended).** If you run your own backend or app server, link the session there. This is the identity Telltale trusts. See [Quickstart step 2](/docs/quickstart#2-attach-identity-from-your-own-authentication) and [Server API › Associate identity](/docs/server#associate-identity).

**In the tag (a label).** In `theme.liquid`, add the customer ID only when a customer is signed in:

```liquid
<script src="https://app.trytelltale.dev/sdk/v1.js" data-telltale-key="YOUR_SITE_PUBLISHABLE_KEY"{% if customer %} data-telltale-user-id="shopify_{{ customer.id }}"{% endif %}></script>
```

For B2B stores, you can add the company the customer is buying for the same way, with `data-telltale-account-id="company_{{ customer.current_company.id }}"` inside the same `{% if customer %}`. A held tag ignores these attributes until `optIn()`; after consent, call `window.Telltale.getClient().identify({ userId: 'shopify_123' })` with the same ID. Calls to `identify()` reject while the tag is held, so wrap them in `try { ... } catch {}`.

## Content Security Policy

Shopify storefront themes do not usually send a Content Security Policy that limits scripts. If you or an app add one, allow the Telltale server for scripts and for connections:

```http
Content-Security-Policy: script-src 'self' https://app.trytelltale.dev; connect-src 'self' https://app.trytelltale.dev
```

Keep the sources your policy already lists. Never add `'unsafe-inline'` or `'unsafe-eval'` for Telltale. See the [Content Security Policy guide](/docs/csp).

## Check it worked

1. In the Telltale dashboard, open Settings › Channels and leave the **Is it working?** check open.
2. Choose **Open my site to test it**, or open your store in a new tab yourself. Browse a product page and the cart.
3. Watch the check move through **Script loaded on** your address, **First session received** and, if you set up identify, **Signed-in user linked** (sign in as a test customer to see it). When the first session arrives, it links to it.

You can also look in your browser's DevTools › Network: `sdk/v1.js` should answer 200, and so should `api/sdk/init`. If it stays at the first step, see [It's not working](/docs/troubleshooting).

## Checkout, thank you and order status pages

Telltale does not observe Shopify checkout. Shopify no longer runs theme code on its checkout pages: `checkout.liquid` is unsupported for the information, shipping and payment steps, and for the Thank you and Order status pages it was sunset on August 28, 2025 (Plus stores); script tags there were sunset on 28 August 2025 for Plus stores and on 26 August 2026 for all other stores. So the tag in `theme.liquid` does not load on those pages, whatever plan you are on.

Protect the steps before checkout instead: sign-in and account pages, the cart, and product pages. If your store uses Shopify's new customer accounts, those account pages are hosted by Shopify and do not run your theme either.

## Common mistakes

- **Editing an unpublished theme.** The tag only runs in the theme your customers see. Check that the theme you edited is the current one, or publish it.
- **Testing in theme preview.** Preview pages run the theme you are previewing, not your live one. Test on the live store address.
- **The `myshopify.com` address versus your own domain.** `https://your-store.myshopify.com`, `https://example.com` and `https://www.example.com` are all different addresses. Add each one visitors use under Settings › Channels › Website addresses.
- **Pasting the tag after `</head>` or into a section file.** Put it just before `</head>` in `layout/theme.liquid`, so every page gets it.
- **Losing the tag on a theme change.** A new theme does not copy your edits. Add the tag again when you switch themes.
- **Store password page.** While your store is password protected, only you see it. That is fine for testing; the check works the same.
- **Ad blockers.** Some privacy extensions block third-party scripts. Test in a window without extensions.