--- title: "How to add heatmaps to a Shopify store" description: "Enable heatmaps for a Shopify storefront. Match a product URL, select a replay background, and verify viewport and traffic coverage." canonical: "https://amplitude.com/en-us/build/shopify-heatmaps" --- # How to add heatmaps to a Shopify store Enable heatmaps for a Shopify storefront. Match a product URL, select a replay background, and verify viewport and traffic coverage. Source: https://amplitude.com/en-us/build/shopify-heatmaps --- # How to add heatmaps to a Shopify store Enable heatmaps for a Shopify storefront. Match a product URL, select a replay background, and verify viewport and traffic coverage. - Shopify - Online Store theme - Amplitude app - 25 min Chris Tam · Last updated 19 October 2026 A Shopify product page puts photos, options, and purchase controls in one view. [Heatmaps](https://amplitude.com/heatmaps) combine recorded storefront interactions so you can inspect where shoppers click and scroll. In this tutorial, I'll use the app's existing replay capture, target one product URL, and align its map with a recorded viewport. ## What you'll build A Shopify product-page heatmap configured with deliberate URL matching, a replay background, and a matching viewport bucket. ## 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. Heatmaps require eligible paid access and replay. [Compare plans](https://amplitude.com/pricing) and [sign up](https://app.amplitude.com/signup). ## 1. Check access and deployed replay support Keep the app installation from [web analytics](/build/shopify-web-analytics) and the verified capture and privacy settings from [session replay](/build/shopify-session-replay). Follow the [heatmap prerequisites](https://amplitude.com/docs/heatmaps/create-a-heatmap). The deployed replay plugin must be at least 1.7.0; check its version rather than assuming the app's bundled version. Browser Console on the product page ```javascript // Browser Console on the product page window.amplitude.getDeviceId(); ``` Heatmaps require an eligible Plus, Growth, or Enterprise plan with replay access. Admins or Managers manage capture; users with View permissions can create maps. The Browser SDK and replay plugin manage device-ID alignment together. ## 2. Enable and verify heatmap capture In Session Replay & Heatmaps settings, select the app-connected project and enable Heatmaps Capture. Save and reopen it. Check session capture and the effective sample rate too. An enabled replay upload does not establish that heatmap capture is enabled. Product-page QA checklist ```text # Product-page QA checklist Replay capture: enabled and verified Heatmaps Capture: enabled and persisted Project: same key used by the Shopify app Traffic: consented storefront visits at the widths to analyze ``` Heatmaps use replay interactions, not a custom marker event or a second click-autocapture installation. Current docs describe approximate initial requirements of ten separate pages and about 500 replay clicks per page. A small development store can verify configuration without producing a populated overlay. ## 3. Target the actual product URL Open Heatmaps > + New Heatmap, choose a map type, and begin with All Users and a date range that includes your traffic. Use Exact match for the product URL recorded by the app. Shopify variant links can contain query parameters, so compare the captured Page URL rather than pasting a theme preview address. Browser Console: compare with the actual captured Page URL ```javascript // Browser Console: compare with the actual captured Page URL location.href; ``` [Page Location](https://amplitude.com/docs/get-started/event-property-definitions) includes the query string; Page URL removes query parameters. Check the actual property and any hash before widening a match. Do not treat a change between product variants as a separate URL map unless the recorded URL distinguishes it. ## 4. Align the background with the recorded width Choose Change Screenshot > From a Replay and use a representative product-page state. If no background exists, choose a replay background through the available screenshot control. The background and data must share the same width bucket: over 1440px, 900 to 1440px, 500 to 899px, or under 500px. Browser Console during the visit used for the background ```javascript // Browser Console during the visit used for the background window.innerWidth; ``` Inspect a populated click or scroll overlay before narrowing segments. Compare product controls and variant state with the background. If no overlay is available, record the result as unverified; a playable replay cannot substitute for the aggregate check. **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. Verify a populated overlay and matching replay background explicitly. ## 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 ### Do I install a separate heatmap SDK? The map uses the existing replay data. Check the app's deployed replay version and project capture controls. ### Why can a replay work while the heatmap is empty? Check heatmap capture, data volume, processing, the recorded URL, and viewport alignment separately. ## 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. Record the actual viewport used for this test. ```javascript // Record the actual viewport used for this test. window.innerWidth; ``` ## 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 heatmaps. 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 guides and surveys to a Shopify storeAsk visitors what product information they need on the storefront.](/build/shopify-guides-surveys)[ShopifyHow to add Web Experiment to a Shopify storeTest storefront offer copy after inspecting the recorded page.](/build/shopify-web-experiment)[ShopifyHow to add session replay to a Shopify storeConfigure Shopify replay sampling and masking through the app-connected project. Verify a synthetic storefront recording before production capture.](/build/shopify-session-replay) Reference docs [Amplitude shopify plugin →](https://amplitude.com/docs/data/amplitude-shopify-plugin)[Heatmaps →](https://amplitude.com/docs/heatmaps)[Create a heatmap →](https://amplitude.com/docs/heatmaps/create-a-heatmap)[Session replay settings →](https://amplitude.com/docs/session-replay/session-replay-settings)[Event property definitions →](https://amplitude.com/docs/get-started/event-property-definitions)[Shopify Customer Privacy API →](https://shopify.dev/docs/api/customer-privacy) For agents [View raw .md](/build/shopify-heatmaps.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)