Install on Shopify

View as Markdown

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

Platform steps checked against the official Shopify documentation on 2026-11-03: Editing theme code, checkout.liquid, Checkout Extensibility upgrade guide, Custom pixels, Web pixels and sandboxes, Theme app extensions, Liquid customer object.

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.

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 and the OneTrust, Cookiebot or 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 and Server API › 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.

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.

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