How to add session replay to a Shopify store

A store's product page can show where a shopper paused without explaining the interaction. Session replay records that storefront journey so you can inspect it alongside analytics.

In this tutorial, I'll configure the app-connected project's capture, add synthetic privacy markers, and check the processed replay.

What you'll build

Prerequisites

• An Online Store Shopify test store and permission to install the Amplitude app and edit a duplicated theme. These tutorials target a Liquid theme, not a headless Hydrogen storefront.
• A test product and an Amplitude test project. Get its public API key in Settings > Projects > your project > General > Manage next to API Key. Admins and Managers can view it.
• A storefront privacy configuration that permits this synthetic test. Check initial refusal, grant, and withdrawal on the actual store. The custom code below controls only its own additions; it does not configure or stop the app's collection.
• Before using browser snippets, confirm the app exposes Browser SDK 2 methods on window.amplitude in the top storefront window. Check the installed version in Instrumentation Explorer. Do not add another initializer to make a missing global appear.

An Amplitude account and Shopify test store are required. Sign up for Amplitude; check the product limits for your project before testing.

1. Configure the app-connected project

The Shopify app already includes replay. In Amplitude settings, open Session Replay & Heatmaps and select the project matching the app's API key. Enable session capture and use Sampling to set the synthetic test rate. Save and reopen the settings to confirm they persisted.

# Amplitude project configuration for the synthetic test
Session capture: enabled
Sampling: 100% for this synthetic QA visit
Privacy level: Conservative
Production sampling: choose and verify your intended rate after testing

Use the privacy settings reference to configure remote privacy. Do not add a second replay SDK, call another analytics init, or assume the app bundles the latest npm version. Inspect its deployed version and effective settings in Instrumentation Explorer.

2. Add synthetic privacy markers

Add only this test markup inside the existing offer section, before its closing section tag. Keep the schema, selected product, analytics attribute, experiment selector, and guide anchor. These classes follow the replay plugin reference.

<!-- sections/amplitude-build-offer.liquid: add inside the existing section -->
<p class="amp-mask">FAKE_SHOPIFY_PRIVATE_123</p>
<div class="amp-block">FAKE_SHOPIFY_BLOCKED_123</div>

Use fake values only. Masking covers text and inputs; it does not mask HTML attributes or URLs, and conservative masking does not cover text baked into images or videos. Keep private data out of attributes and URLs and block sensitive media. Remote privacy settings take precedence where they conflict with SDK settings.

3. Record a known storefront sequence

On the actual storefront, note the device ID and start time. Open Home, follow the offer to the selected product, and interact with the native product page. Use only synthetic account or form details.

// Browser Console in the top storefront window
window.amplitude.getDeviceId();
window.amplitude.flush();

Follow capture verification. Inspect replay requests separately from analytics delivery. A sandboxed custom pixel does not record the storefront DOM for this tutorial. The app's replay is a storefront feature; this tutorial does not promise a checkout recording.

4. Inspect playback and restore sampling

Find the replay using the visitor and test time. Replays are generally available about five minutes after a session begins. Open the processed recording, compare the action order and identity, and verify masked text and the blocked placeholder.

# Post-test project settings
Sampling: restore the intended production rate
Privacy: preserve Conservative and explicit masking/blocking rules
Verify: reopen settings and check effective sampling in the browser

Keep the privacy markers until the check is complete. Successful upload is not proof that playback, masking, or identity association worked. Check the hosted theme's styles in playback separately from the live storefront.

MCP: Ask your coding agent to inspect the project's event taxonomy with the Amplitude MCP server before adding custom events. Reuse an existing name when it describes the same action.

Verify it worked

1. Storefront: Open the actual storefront URL while logged out. Inspect the app's script and any theme additions. Use one app-owned analytics installation; a pixel sandbox and the top storefront window are different contexts.
2. Delivery: In browser Network, confirm event POSTs return HTTP 200 from api2.amplitude.com for US or api.eu.amplitude.com for EU. Compressed requests are not a reliable place to read event contents.
3. Instrumentation Explorer: Inspect event names, properties, counts, and device_id in the Chrome extension. Compare one action with one expected event.
4. User Profiles: Search that device ID in Users > User Profiles and inspect its event stream. The docs describe ten seconds to one minute for events. Ingestion Debugger provides request and event counts, not individual payloads.

Complete processed playback and masking checks; accepted upload alone is insufficient.

Troubleshooting

Nothing appears after connecting the app

Check the connected project key, storefront privacy decision, app installation, script requests, and browser blockers. Use the storefront's top window when checking window.amplitude; a sandboxed custom pixel is a separate environment.

Events appear twice

Look for a second SDK in a custom pixel, tag manager, theme snippet, or older integration. Remove the duplicate installation through its supported configuration. Keep the app-owned SDK and the existing theme code.

Theme editing changes the result

Test the actual storefront URL as well as the duplicated theme preview. Confirm the same product, template, hostname, and privacy state. Theme editor rendering alone is not a hosted-store verification.

FAQ

Should I paste the standalone replay SDK into a custom pixel?

Use the app's existing storefront replay installation. Shopify pixels run in a sandbox with controlled APIs; they are not the top storefront window.

Does Conservative mask everything in the page?

It masks text and inputs. HTML attributes, URLs, and text inside static media need separate handling.

Full code reference

Unchanged from earlier pages; keep your versions: App installation, sections/amplitude-build-offer.liquid, assets/amp-shopify-events.js, assets/amp-shopify-guides.js, assets/amp-shopify-experiment-consent.js.

<!-- Preserve the existing offer section and schema. -->
<p class="amp-mask">FAKE_SHOPIFY_PRIVATE_123</p>
<div class="amp-block">FAKE_SHOPIFY_BLOCKED_123</div>

Hand it to your agent

Give your agent this tutorial and the existing theme files. Keep the app installation, all sibling theme additions, and the selected test product.

Agent task: Shopify session replay.
Use the official Amplitude Shopify app as installation owner. Merge only this page's additions; preserve content_for_header, product/cart templates, replay privacy, offer attributes, custom event handlers, and consent. Confirm actual Browser SDK methods before using snippets. Test consent and the promised outcome on a real Shopify test store. Report SDK delivery, native Shopify behavior, product configuration, and processed results separately. Do not call another analytics init or claim checkout behavior from a storefront test.

What this unlocks

Product analytics compares Shopify Offer Clicked with the app's observed product and cart events after both are verified.

Session replay shows the storefront interaction after capture, identity, and privacy checks pass.

Web Experiment uses the observed Shopify Offer Clicked event as the offer-copy test's primary metric.

Guides and surveys can ask what product information a visitor needs after the separate SDK and targeting are configured.

Next steps