Shopify

api_base accepts an absolute HTTPS URL with or without one trailing slash. The snippet preserves the protocol separator and renders the loader URL as https://api.example.com/v1/widget.js. Its Liquid rendering regression runs in CI (tests/shopify-snippet.test.rb, Liquid 4.0.4).

Embed the widget on Online Store theme pages or custom Liquid sections using the theme snippet integrations/shopify/snippets/playflow-widget.liquid.

Install the snippet

Copy playflow-widget.liquid into your theme snippets/ folder, then render it:

{% render 'playflow-widget',
  project_id: 'proj_your_id',
  api_base: 'https://api.example.com',
%}

Omit session_token for anonymous free-play. Owner preview is in admin. Repeated snippets mount independent wrappers; all attribute values are escaped. Legacy mode: 'preview' renders an explanation without loading a game. For identified play, render a fresh server-issued token only in the authenticated player's response; do not store it in a public metafield. Obtain a replacement from your backend on expiration, then remount the widget for the same player.

Checkout and customer accounts

The theme snippet does not implement a Shopify checkout or customer account extension. Do not paste it into the current thank-you or order status pages: Shopify has retired the corresponding checkout.liquid and additional-scripts integration paths. These surfaces need a separate supported Shopify extension, which RetentionPlay does not currently provide. See Shopify's checkout migration requirements.

For campaigns on theme pages, use the current lobby and server-confirmed game outcomes. The R1 reward wheel awards tickets or resources; legacy scratch_v1 and wheel_v1 are not supported promo templates in this flow.

Security

• Add your storefront domain to allowed_origins.
• Issue session_token server-side with POST /v1/server/session-token; never put API keys or secrets in Liquid.
• Verify X-RetentionPlay-Signature (or legacy X-PlayFlow-Signature) on reward webhooks.

Roadmap

A first-class Shopify app (OAuth + metafield setup, theme app extension block) is on the roadmap; until then use the theme snippet above.