---
title: "How to add heatmaps to your app with v0"
description: "Add heatmaps to a v0 app with session replay, distinct report URLs, privacy controls, and checks for capture and map readiness."
canonical: "https://amplitude.com/build/v0-heatmaps"
---

# How to add heatmaps to your app with v0

Add heatmaps to a v0 app with session replay, distinct report URLs, privacy controls, and checks for capture and map readiness.

Source: https://amplitude.com/build/v0-heatmaps

---

# How to add heatmaps to your app with v0

Use v0 to add replay-backed heatmaps for weekly and monthly reports. Allow 30 minutes for setup, plus capture and map-processing checks.

- v0
- Vite
- Unified SDK 1.1.43
- 25 min

Chris Tam · Last updated 11 November 2026

v0 can turn a report design into an interactive app. Amplitude [heatmaps](https://amplitude.com/heatmaps) use recorded interactions to show which report controls visitors use, while separate report URLs keep weekly and monthly views distinct.

In this tutorial, you'll give v0 a scoped prompt, review its generated framework files, run a standalone reference, and verify the result in a development Amplitude project.

A report app with separate weekly and monthly URLs, one browser SDK initialization, replay privacy controls, and a heatmap configured for a report URL. A short test confirms capture and navigation; an overlay also needs enough processed replay data.

## Prerequisites

- A v0 account with edit access to a chat and enough allowance for your selected model. Inspect Code, App Preview and Terminal before requesting changes.
- Node.js 22.12 or later and Corepack with pnpm 10.33.2. The example pins Vite 8.3.4 and `@amplitude/unified` 1.1.43; it doesn't require another Build tutorial.
- A development Amplitude project and its public client API key from Settings > Projects > your project > General. Confirm its US or EU data center. Check that the project has access to the product and capacity for your test.

Heatmaps are available on Plus, Growth, and Enterprise with session replay access. [Compare plans](https://amplitude.com/pricing) and [sign up for Amplitude](https://app.amplitude.com/signup). Confirm that your project has heatmaps access; an Admin or Manager can enable capture. Use a separate development project for synthetic checks.

## 1. Open the project and connect context

Open a new v0 chat for the synthetic report, or open the app you want to extend. I first ask v0 to inspect its actual framework and existing instrumentation. The complete Vite reference below is a behavior reference; v0 should preserve an existing Next.js app and its router.

v0 planning prompt

```text
Planning only. Inspect this v0 project's framework, router, browser entry point, package manager, existing Amplitude client, consent and authentication. Identify its Preview server and proposed files. Preserve the existing application and explain your tests before editing. Do not deploy, connect accounts or enter credentials. Stop after the plan.
```

Use Code to inspect the files and Terminal for the project's commands. App Preview opens the running application. The [v0 workspace reference](https://v0.app/docs/sandbox) describes these surfaces.

This SDK setup works without an Amplitude MCP connection. If you already use a connected agent for project context, review its account permissions separately from the app's public ingestion configuration.

## 2. Give the agent a precise implementation prompt

Review the plan, then ask v0 to implement the integration. The prompt pins the SDK behavior while leaving the framework adaptation to the project you inspected.

v0 implementation prompt

```text
Implement the reviewed plan in this v0 project. Read the current English SDK references and report their URLs:
https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk/reference
https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk/instrument-and-configure
https://amplitude.com/docs/sdks/session-replay/session-replay-plugin
Use these docs for Amplitude facts. If sources disagree, pause that claim and record both statements until the installed SDK or its owner establishes the behavior.

Read the complete public reference at https://github.com/amplitude/ampli-examples/tree/ffac5f46bc32da3e3da20474708d974c70cd0eaa/browser/coding-tools/heatmaps and its package.json, index.html, main.js, .env.example, .gitignore, pnpm-workspace.yaml and lockfile. Use the complete files in this article if you cannot retrieve the reference. This standalone reference uses Vite. Preserve this project's actual framework, router, scaffold and package manager instead of replacing them with Vite.

For a server-rendered v0 app, dynamically import browser-only SDK code from a client lifecycle or user action. Do not execute it on the server. Use one initialization promise outside React render and preserve it across remounts and repeated actions. Await initAll(apiKey, options) directly; it resolves void. Retain the imported module for track(), experiment() and sessionReplay(). Check against the actual SDK type, not a cast to an invented interface.

Give weekly and monthly reports distinct paths using the existing router. A tab that changes only local state combines its interactions under one URL. Use @amplitude/unified 1.1.43 and initAll once after Start demo. Set top-level serverZone. Enable session events, set replay sampleRate to 1 for the development test, and skip engagement. Mask #sensitive and block #excluded in sessionReplay.privacyConfig. Keep the input masked. Set the synthetic user build-web-heatmaps-demo after initialization. Track Report Exported only from the export action. Keep replay active during the capture check. Preserve consent and privacy selectors when changing routes. Never treat the replay ID or an upload response as proof of correct processed masking.

Keep the app usable with missing keys, invalid region, failed initialization or unavailable product results. Test the configured path as well as the blank-key path. Preserve an existing client, confirmed identity, consent, enabled products and privacy selectors. Do not copy the demo's synthetic ID or sample/skip choices into production, add a second analytics client, replace whole shared files or reset identity while authentication is anonymous/loading.

The Vite reference uses public VITE_ configuration. In a Next.js browser component, use explicit process.env.NEXT_PUBLIC_AMPLITUDE_API_KEY and process.env.NEXT_PUBLIC_AMPLITUDE_SERVER_ZONE reads; feature flags also need NEXT_PUBLIC_AMPLITUDE_DEPLOYMENT_KEY. Keep secret, admin, model-provider and server deployment credentials out of all public variables. Leave examples blank and local .env.local ignored. Keep real keys out of the chat and project instructions. Preserve the project's dev-server command and narrow host validation.

Run local tests, the existing build and an explicit type check when TypeScript is used. Save the changes in a version and inspect its diff. Report local checks, native v0 Preview and live Amplitude outcomes separately. Do not deploy, publish, broaden targeting, connect accounts, purchase credits or make paid model calls.
```

**MCP.** If you already use a connected Amplitude agent, ask it to read the project's existing event names before adding `Report Exported`. Keep the established taxonomy when the same action already has a name. The [MCP reference](https://amplitude.com/docs/amplitude-ai/amplitude-mcp) describes project-context tools.

## 3. Review the proposed changes

Inspect the SDK calls before relying on the UI. A successful preview or a local export counter does not establish an assignment, guide delivery or replay capture.

v0 review prompt

```text
Show every changed and new file. Trace the public configuration, browser-only SDK import, one cached initialization, confirmed identity and product-specific handlers. Confirm initAll(apiKey, options) is awaited as a plain promise and its void result is not used as a client. Show the actual installed SDK types, generated tests, build results and saved version diff. Keep missing/failed configuration usable and preserve the app's other integrations. Report local checks separately from live product outcomes.
```

Use the Code tab and saved version diff to inspect the result. The [v0 editor guide](https://v0.app/docs/code-editing) distinguishes workspace edits from saved changes. If synchronization fails, preserve the affected files, have v0 capture the reviewed changes in a version, then reopen its diff.

The standalone reference uses `VITE_` variables, which are public browser configuration. A Next.js adaptation uses explicit `NEXT_PUBLIC_` reads instead. [Next.js environment guidance](https://nextjs.org/docs/app/guides/environment-variables) explains build-time embedding. Restart after changing configuration and configure hosted builds separately. Never put private credentials in either prefix.

The demo has a fixed synthetic user. Merge an existing app through its current client and confirmed identity, keeping its consent and other enabled products.

## 4. Check the complete reference implementation

These six files make a complete standalone Vite browser reference. Use them in a separate local directory to inspect and run the SDK behavior. In an existing v0 app, merge that behavior into its framework files; keep its routes, authentication, layout and dev-server configuration.

The [Unified SDK installation guide](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk/get-started) supplies the setup. This example pins 1.1.43 for repeatable checks, rather than claiming it is the latest release. Its initialization returns a plain promise, so the reference awaits it directly.

package.json

```json
{
  "name": "amplitude-build-session-replay",
  "private": true,
  "version": "1.0.0",
  "type": "module",
  "packageManager": "pnpm@10.33.2+sha512.a90faf6feeab71ad6c6e57f94e0fe1a12f5dcc22cd754db40ae9593eb6a3e0b6b12e3540218bb37ae083404b1f2ce6db2a4121e979829b4aff94b99f49da1cf8",
  "engines": {
    "node": ">=22.12.0",
    "pnpm": ">=10.21.0"
  },
  "scripts": {
    "dev": "vite --host 127.0.0.1",
    "build": "vite build",
    "preview": "vite preview --host 127.0.0.1"
  },
  "dependencies": {
    "@amplitude/unified": "1.1.43"
  },
  "devDependencies": {
    "vite": "8.3.4"
  }
```

pnpm-workspace.yaml

```yaml
minimumReleaseAge: 10080
trustPolicy: no-downgrade
```

.gitignore

```text
node_modules/
dist/
.env.local
.env.qa
```

.env.example

```text
VITE_AMPLITUDE_API_KEY=
VITE_AMPLITUDE_SERVER_ZONE=US
```

index.html

```html
<!doctype html>
<html lang="en">
  <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Usage report demo</title></head>
  <body>
    <main>
    <nav><a href="/reports/weekly">Weekly report</a> <a href="/reports/monthly">Monthly report</a></nav>
    <p id="report-route"></p>
      <h1>Usage report</h1>
      <p id="report-summary">84 actions in the past 7 days.</p>
      <button id="start">Start demo</button>
      <button id="export-report">Export report</button>
      <p>Local exports: <span id="exports">0</span></p>
      <p id="sensitive" class="amp-mask">SYNTHETIC PRIVATE LABEL</p>
    <label>Test note <input value="SYNTHETIC INPUT ONLY"></label>
    <section id="excluded" class="amp-block">SYNTHETIC EXCLUDED PANEL</section>
    <button id="pause" disabled>Pause recording</button>
      <p id="status" role="status">Demo stopped. Use synthetic data only.</p>
    </main>
    <script type="module" src="/main.js"></script>
  </body>
</html>
```

main.js

```javascript
import * as amplitude from "@amplitude/unified";

document.querySelector("#report-route").textContent = location.pathname === "/reports/monthly" ? "Monthly report" : "Weekly report";
document.querySelector("#report-summary").textContent = location.pathname === "/reports/monthly" ? "320 actions in the past 30 days." : "84 actions in the past 7 days.";
const apiKey = (import.meta.env.VITE_AMPLITUDE_API_KEY || "").trim();
const zone = (import.meta.env.VITE_AMPLITUDE_SERVER_ZONE || "US").trim();
const status = document.querySelector("#status");
const startButton = document.querySelector("#start");
const exportButton = document.querySelector("#export-report");
let started = false;
let starting;
let exports = 0;

exportButton.addEventListener("click", () => {
  exports += 1;
  document.querySelector("#exports").textContent = String(exports);
  if (started) amplitude.track("Report Exported", { report_period: location.pathname === "/reports/monthly" ? "30d" : "7d" });
});

startButton.addEventListener("click", () => {
  if (starting) return;
  if (!apiKey || !["US", "EU"].includes(zone)) {
    status.textContent = "Add the development configuration and restart Vite. Local export still works.";
    return;
  }
  startButton.disabled = true;
  starting = start().catch(() => {
    status.textContent = "Setup failed. Check configuration and connectivity, then reload.";
  });

async function start() {
  await amplitude.initAll(apiKey, {
    serverZone: zone,
    analytics: { autocapture: { sessions: true } },
    sessionReplay: {
      sampleRate: 1,
      privacyConfig: { defaultMaskLevel: "medium", maskSelector: ["#sensitive"], blockSelector: ["#excluded"] },
    },
    engagement: { skip: true },
  });
  amplitude.setUserId("build-web-heatmaps-demo");
  started = true;
  document.querySelector("#pause").disabled = false;
  status.textContent = `Replay requested; device ${amplitude.getDeviceId()}. Verify the processed recording.`;
}

document.querySelector("#pause").addEventListener("click", () => {
  amplitude.sessionReplay()?.stop();
  status.textContent = "Recording paused; analytics remains active.";
});
```

Install with the pinned package manager. Keep the generated lockfile, or use the matching lockfile in the public reference, then use a frozen install on subsequent checkouts.

Terminal

```sh
corepack pnpm install
corepack pnpm build
```

Copy `.env.example` to the ignored `.env.local` before the configured development check. The values in `VITE_` variables enter the built browser bundle; keep only public client configuration there. The [Vite environment reference](https://vite.dev/guide/env-and-mode) explains configuration loading and rebuilds.

## 5. Configure capture and create the map

In Amplitude, open **Settings > Organizational Settings > Session Replay Settings**. Have an Admin or Manager enable session capture and heatmap capture for the development project. Check its sampling configuration and remaining replay capacity. A remote project sampling value can change what gets recorded; requesting `sampleRate: 1` locally does not bypass project controls.

Development product settings

```text
Development check:
- Confirm the correct project and data center.
- Enable session capture and heatmap capture only in the intended development project.
- Record synthetic interactions with sensitive text masked and excluded content blocked.
- Give weekly and monthly reports distinct paths in the app's existing router.
- Preserve the same Amplitude identity for replay and analytics.
```

Open **Heatmaps > + New Heatmap**, choose a map type, and use **Exact match** for the deployed weekly report URL. Start without a segment filter. Use a stable deployed or accessible preview URL; an editor's surrounding v0 URL is not the app page URL. Then check the monthly path separately.

Heatmaps need Session Replay Browser SDK Plugin 1.7.0 or later, or Standalone SDK 1.14.0 or later. Unified manages device ID alignment automatically. Read the installed replay version in Instrumentation Explorer's replay debug panel.

Heatmaps appear after roughly 500 replay clicks on each of at least 10 pages. These are approximate site-wide data requirements, not a promise that this two-page demo produces an overlay immediately. Confirm capture first and let eligible traffic accumulate; don't generate thousands of fake clicks to simulate a production result.

Choose a background from the same screen-width bucket as the interactions. If it looks wrong, use **Change Screenshot > From a Replay**. The buckets are greater than 1440px, 900 to 1440px, 500 to 899px, and less than 500px.

## 6. Run the report

For the local reference, start Vite and open the URL it prints. For a generated v0 app, keep its existing framework command and inspect App Preview. Do not replace a Next.js dev server with the reference's Vite command.

Local reference terminal

```sh
corepack pnpm dev
```

Export before starting the SDK to check that the report stays usable with blank configuration. Then configure the development project, restart, select Start demo once and follow Verify it worked. After the check, stop the server and verify the build:

Local reference terminal

```sh
corepack pnpm build
```

Keep the generated v0 app's direct route loads, navigation and Preview results separate from the standalone reference's checks.

## Verify it worked

1. Open `/reports/weekly`, export a synthetic report, then follow Monthly report. Confirm the address changes to `/reports/monthly`, including on a direct load. In v0, test both preview navigation and direct route loads with its real router.
2. Use Instrumentation Explorer to inspect the SDK version, device ID, replay ID, and capture settings. Read event contents there rather than a compressed Network request body.
3. Inspect a processed recording. Confirm the report navigation and export appear, private text is masked, and excluded contents are absent. A successful upload alone doesn't establish those privacy outcomes.
4. In Heatmaps, check the app's actual URL, date range, capture toggles, and sampling configuration. If the site has enough processed data, confirm the map and background share a screen-width bucket and the expected clicks appear.
5. Add segment or cohort filters only after the unsegmented map works. Empty segmented results can indicate mismatched device IDs or a filter without matching users.

Record capture, route behavior, and a populated overlay as separate outcomes. A local build or a short two-page session cannot prove that the data thresholds have been met.

## Troubleshooting

**Preview is blank or rejects the host.** Confirm the app's existing dev server is running and inspect its actual Preview URL. Keep framework host validation enabled. If an additional trusted host is required, allow that exact host rather than disabling validation globally.

**The map is blank.** Check capture toggles, processed replay data, date and URL filters, sampling, and the approximate site-wide data requirements. A working replay is necessary but doesn't establish a populated map.

**Weekly and monthly clicks overlap.** Keep each view at its own path using the existing router. Local state changes that share a URL merge into one map. Don't rely on query parameters to separate these views.

**Only segment filters are empty.** Confirm replay and analytics use the same device ID and, for signed-in users, the same user ID. Keep the existing Unified client rather than adding a separate initializer.

**The background looks wrong.** Use Change Screenshot > From a Replay and match the background to the data's screen-width bucket. Preserve masking because the background comes from replay capture.

**The hosted app fails during server rendering.** Have v0 dynamically load the browser SDK from a client lifecycle or user action. Preserve one initialization promise and test direct route loads.

**Configuration is absent in Preview.** Check the framework's public environment prefix and explicit variable reads, then restart the development process. Hosted builds need their own build-time values. Keep private credentials out of browser configuration.

## FAQ

### Which Amplitude key goes in the browser app?

The browser app uses a public project API key. An MCP connection authenticates separately. Keep server deployment keys, admin tokens, and secret keys out of browser configuration and committed source.

### Can I use this in an existing v0 app?

Yes. Have the agent merge the behavior into the existing browser entry point and client. Preserve authentication, consent, and routing. The standalone reference uses Vite. Keep the existing app scaffold and router. If it renders on a server, load browser-only SDK code dynamically from a client lifecycle or user action, and test direct route loads.

### Does a successful build prove the product works?

No. A build checks that the browser app can be bundled. The Verify section separately checks the rendered experience, processed activity, and the product result. Record which checks you performed before broadening the audience.

### Will the agent make the same changes every time?

Treat its output as a change to review. Keep the explicit prompt, pinned reference, and repository rules, then compare its diff with the required behavior. An agent can propose a different implementation without establishing that its SDK calls or product settings are correct.

## Full code reference

Step 4 contains every file needed by the standalone browser reference. [Read the public example and lockfile](https://github.com/amplitude/ampli-examples/tree/ffac5f46bc32da3e3da20474708d974c70cd0eaa/browser/coding-tools/heatmaps). Compare its SDK behavior with v0's actual framework files; a matching local reference does not establish that a generated adaptation behaves identically.

### Save the project instructions

Add these constraints through [v0 Instructions](https://v0.app/docs/instructions) and apply them to the conversation. Preserve any existing project guidance and keep credentials out of instructions.

v0 reusable instructions

```text
Preserve the app's framework, router, consent, confirmed identity, enabled Amplitude products and package manager. Keep browser-only SDK imports out of server execution. Reuse one initialization promise and use the imported module after await initAll(apiKey, options). Do not cast an invented SDK interface over the real package. Keep public browser configuration separate from private server credentials. Preserve the product-specific fallback, event timing and privacy rules in this tutorial. Run local checks and inspect the saved version diff. Verify the rendered experience and processed service result separately before rollout. Pause conflicting SDK claims until source evidence or an owner resolves them.
```

## What this unlocks

[Product analytics](https://amplitude.com/amplitude-analytics) shows `Report Exported` for the same identity used by this example. The [session replay](https://amplitude.com/session-replay) integration adds context around that report action. Keep the event name and report-period property consistent as you extend the app.

## Next steps

[Foundationv0 analyticsReview the related analytics walkthrough as optional context.](https://amplitude.com/build/v0-product-analytics)[ReferenceBrowser SDK configurationCheck options before adding more product behavior.](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk/reference)[WorkflowDebug your eventsConfirm identity and event properties in your development project.](https://amplitude.com/docs/analytics/debug-analytics)

Reference docs

[Unified SDK setup →](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk/get-started)[Unified SDK API reference →](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk/reference)[Create a heatmap →](https://amplitude.com/docs/heatmaps/create-a-heatmap)[Troubleshoot heatmaps →](https://amplitude.com/docs/heatmaps/troubleshooting)[Amplitude MCP →](https://amplitude.com/docs/amplitude-ai/amplitude-mcp)[v0 Instructions →](https://v0.app/docs/instructions)[v0 workspace →](https://v0.app/docs/sandbox)

Amplitude is the leading [all-in-one analytics platform](https://amplitude.com/) for building better products. Product and engineering teams use Amplitude to connect [product analytics](https://amplitude.com/amplitude-analytics) and [web analytics](https://amplitude.com/web-analytics) with [session replay](https://amplitude.com/session-replay), [heatmaps](https://amplitude.com/heatmaps), [experimentation](https://amplitude.com/amplitude-experiment), [feature flags](https://amplitude.com/feature-management), and [guides and surveys](https://amplitude.com/guides-and-surveys) in one unified workflow, with [AI agents](https://amplitude.com/ai-agents) working across all of it. Learn how Amplitude is building [self-improving products](https://amplitude.com/self-improving-products) with [Wave](https://amplitude.com/wave), helping teams turn product data into PRs.

For agents

[View raw .md](/build/v0-heatmaps.md)[llms.txt](/llms.txt)

## Build the report, then check the result

Connect a development project and verify the report action before you roll out the integration.

[Create a free account](https://app.amplitude.com/signup)[Browse all Build tutorials](https://amplitude.com/build)
