---
title: "How to add session replay to a Shopify store"
description: "Configure Shopify replay sampling and masking through the app-connected project. Verify a synthetic storefront recording before production capture."
canonical: "https://amplitude.com/en-us/build/shopify-session-replay"
---
# How to add session replay to a Shopify store
Configure Shopify replay sampling and masking through the app-connected project. Verify a synthetic storefront recording before production capture.
Source: https://amplitude.com/en-us/build/shopify-session-replay
---
# How to add session replay to a Shopify store
Configure Shopify replay sampling and masking through the app-connected project. Verify a synthetic storefront recording before production capture.
- Shopify
- Online Store theme
- Amplitude app
- 25 min
Chris Tam · Last updated 19 October 2026
A store's product page can show where a shopper paused without explaining the interaction. [Session replay](https://amplitude.com/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
A sampled Shopify storefront recording with masked test text, blocked test content, and a matching analytics visitor.
## 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](https://app.amplitude.com/signup); check the product limits for your project before testing.
## 1. Configure the app-connected project
The [Shopify app](https://amplitude.com/docs/data/amplitude-shopify-plugin) 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
```text
# 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](https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay) 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](/build/shopify-web-analytics), before its closing section tag. Keep the schema, selected product, analytics attribute, experiment selector, and guide anchor. These classes follow the [replay plugin reference](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin).
sections/amplitude-build-offer.liquid: add inside the existing section
```html
FAKE_SHOPIFY_PRIVATE_123
FAKE_SHOPIFY_BLOCKED_123
```
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
```javascript
// Browser Console in the top storefront window
window.amplitude.getDeviceId();
window.amplitude.flush();
```
Follow [capture verification](https://amplitude.com/docs/session-replay/verify-capture). 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
```text
# 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](https://amplitude.com/docs/amplitude-ai/amplitude-mcp) 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.
```html
FAKE_SHOPIFY_PRIVATE_123
FAKE_SHOPIFY_BLOCKED_123
```
## 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 prompt
```text
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](https://amplitude.com/amplitude-analytics) compares Shopify Offer Clicked with the app's observed product and cart events after both are verified.
[Session replay](https://amplitude.com/session-replay) shows the storefront interaction after capture, identity, and privacy checks pass.
[Web Experiment](https://amplitude.com/web-experimentation) uses the observed Shopify Offer Clicked event as the offer-copy test's primary metric.
[Guides and surveys](https://amplitude.com/guides-and-surveys) can ask what product information a visitor needs after the separate SDK and targeting are configured.
## Next steps
[ShopifyHow to add web analytics to a Shopify storeConnect Shopify to Amplitude with the official app. Verify storefront page views, campaign attribution, and anonymous visitor continuity.](/build/shopify-web-analytics)[ShopifyHow to add product analytics to a Shopify storeTrack a Shopify offer click alongside app-provided product and cart events. Keep clicks separate from confirmed commerce outcomes.](/build/shopify-product-analytics)[ShopifyHow to add heatmaps to a Shopify storeEnable heatmaps for a Shopify storefront. Match a product URL, select a replay background, and verify viewport and traffic coverage.](/build/shopify-heatmaps)
Reference docs
[Amplitude shopify plugin →](https://amplitude.com/docs/data/amplitude-shopify-plugin)[Session replay settings →](https://amplitude.com/docs/session-replay/session-replay-settings)[Manage privacy settings for session replay →](https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay)[Session replay plugin →](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin)[Verify capture →](https://amplitude.com/docs/session-replay/verify-capture)[Shopify Customer Privacy API →](https://shopify.dev/docs/api/customer-privacy)
For agents
[View raw .md](/build/shopify-session-replay.md)[llms.txt](/llms.txt)
## Add Amplitude to your Shopify site
Connect the official Shopify app and follow the tutorials for each product.
[Create a free account](https://app.amplitude.com/signup)[Browse all Build tutorials](https://amplitude.com/build)