Guides

Shopify

Embed games on product pages, blog articles, or a dedicated games page — no app required.

Shopify's Online Store 2.0 themes (Dawn and everything built on it) ship with a Custom Liquid block that accepts raw HTML and JavaScript. That's all you need to embed Playgent.

Load the SDK site-wide (recommended)

Add the SDK script once in your theme so every Custom Liquid block stays small:

In your admin, go to Online Store → Themes → ⋯ → Edit code.
Open layout/theme.liquid.
Just before </head>, paste:

html

<script src="https://static.playgent.com/player/v2.js"></script>

Save. Every page on your storefront now has the SDK loaded.

Embed on a product page or article

In the theme editor, add a Custom Liquid section (or block, depending on your template) where the game should appear, then paste:

html

<div id="playgent-host"></div>
<script>
  Playgent.init({
    containerId: "playgent-host",
    player: "plyr_acme",
    game: "sudoku",
    mode: "daily",
  });
</script>

Replace plyr_acme with your player ID. If you didn't load the SDK site-wide, prepend the <script src=…player/v2.js> tag inside the same block.

Dedicated games page

Create a new Page (Online Store → Pages → Add page), then in the Theme template dropdown either use the default page template or create a custom one (templates/page.games.liquid). Add a Custom Liquid section with a multi-game switcher:

html

<div id="playgent-host"></div>

<div class="pg-tabs" style="display:flex; gap:8px; margin-top:12px;">
  <button onclick="player.load({ game: 'sudoku', mode: 'daily' })">Sudoku</button>
  <button onclick="player.load({ game: 'wordsearch', mode: 'daily' })">Wordsearch</button>
  <button onclick="player.load({ game: 'trivia', mode: 'daily' })">Trivia</button>
</div>

<script>
  const player = Playgent.init({
    containerId: "playgent-host",
    player: "plyr_acme",
    game: "sudoku",
    mode: "daily",
  });
</script>

player.load() swaps content without a remount — see Calling methods.

Wire completions to Shopify customer data

Pass the logged-in customer's ID so completion events tie back to your shop:

html

<div id="playgent-host"></div>
<script>
  Playgent.init({
    containerId: "playgent-host",
    player: "plyr_acme",
    game: "sudoku",
    mode: "daily",
    {% if customer %}
    externalUserId: "{{ customer.id }}",
    externalUsername: {{ customer.first_name | json }},
    {% endif %}
    onComplete: ({ score, won, timeMs }) => {
      // forward to Shopify analytics, Klaviyo, etc.
      console.log("game completed", { score, won, timeMs });
    },
  });
</script>

Shopify gotchas

Content Security Policy (CSP)

Some themes and apps (Shopify's Hydrogen, certain checkout extensions) ship a strict CSP that blocks third-party scripts. If the game doesn't load, check your browser console for CSP violations and allow:

static.playgent.com
pgl.playgent.com

Storefront caching and identity

Shopify caches storefront HTML aggressively at the CDN edge for performance. If you bake externalUserId into the inline Playgent.init via Liquid (as above), the value is correct for that customer but cached pages might serve a stale ID to other visitors on the same URL with cookie variation.

Fix: for high-traffic pages, omit externalUserId from the inline call and push it after mount with player.setIdentity() using a customer-specific fetch.

Theme app extensions and script order

If you use multiple Shopify apps that inject scripts into the storefront, load order matters. Keep player/v2.js early (in theme.liquid's <head>) so any inline Playgent.init calls later in the page can find window.Playgent when they run.

Checkout pages

Playgent doesn't render inside Shopify Checkout — checkout extensions run in a sandbox with very limited capabilities. Embed on product / collection / page / article templates instead.

Origin allowlist

Add your storefront's domains to the player in Hub → Configuration → Players. Include:

Your custom domain (shop.acme.com, acme.com).
The myshopify.com preview domain (acme.myshopify.com) — useful for previewing themes before they're published.

Players reference →

Ghost

Webflow