Before you create a heatmap, confirm that your Amplitude instrumentation meets the prerequisites, then follow the steps to build and target your first heatmap.

## Prerequisites

Your Amplitude instrumentation must meet the following requirements.

### Session Replay

{% callout type="note" heading="Client availability" %}
Heatmaps supports web-based session replays only, and doesn't support mobile apps or SDKs.
{% /callout %}

Heatmaps requires these minimum SDK versions:

- [Session Replay Browser SDK Plugin](/docs/session-replay/session-replay-plugin): 1.7.0.
- [Session Replay Standalone SDK](/docs/session-replay/session-replay-standalone-sdk): 1.14.0.

{% callout type="note" heading="Session Replay sample rate" %}
Heatmaps use Session Replay data to track interactions on your pages. If you use a sample rate to limit the number of replays you generate, you also limit the events available to build heatmaps. A limited sample rate produces a less comprehensive view of user interactions and can reduce heatmap accuracy.
{% /callout %}

### Heatmap data requirements

Heatmaps appear after Amplitude collects enough replay click data across your site: at least 10 separate pages, with about 500 tracked replay clicks on each page. These thresholds are approximate and may change as Heatmaps evolves.

### Matching device identifiers

Heatmaps require that the `device_id` on heatmap events from the Session Replay Plugin or Standalone Session Replay SDK matches the `device_id` on your Amplitude analytics events.

If you use the [Browser SDK 2.x with the Session Replay Plugin](/docs/sdks/session-replay/session-replay-plugin) or the [Unified SDK](/docs/sdks/analytics/browser/browser-unified-sdk), Amplitude manages `device_id` alignment automatically.

If you use the [Standalone Session Replay SDK](/docs/sdks/session-replay/session-replay-standalone-sdk) with a third-party or homegrown analytics pipeline, pass the same `device_id` and `session_id` to Session Replay that you attach to your analytics events. If your backend generates device identifiers that differ from the browser, heatmap segment filters and event joins won't work correctly.

When `device_id` values don't match:

- **Unsegmented heatmaps** (URL and date filters only) still render from heatmap events.
- **Segment and cohort filters** return empty or incorrect results, because Amplitude can't join heatmap clicks to analytics users.
- **Microscope actions** (view events, view replays, create cohort from a heatmap selection) won't link to the right users.
- **Session Replay playback** for a specific replay may still work, because replays are keyed by the SR SDK's `device_id`/`session_id`.

If your analytics pipeline sets `user_id` for logged-in users, use the same `user_id` on both sides as well.

### Create a development project (optional)

Amplitude recommends that you create a separate development project to test Heatmapping without impacting your production environment.

{% callout type="note" heading="Event taxonomy impact" %}
Heatmap and Session Replay events don't count toward your allotted event volume, and Amplitude doesn't bill you for them.
{% /callout %}

## Create a heatmap

To create a new Heatmap:

1. Navigate to **Heatmaps** in the left navigation in Amplitude.
2. Click **+ New Heatmap**.
3. Choose a [Heatmap type](/docs/heatmaps/map-types). You can update the map type at any point.
4. Select the URL to analyze. Use the following URL matching options to target the pages you care about.
   - **Exact match**: Matches the URL exactly as you specify it. Ideal for single URLs. For example, `https://amplitude.com`.
   - **Pattern match**: Uses wildcards to match more than one URL with a similar pattern. Useful for targeting dynamic paths. For example, `https://amplistore/products/*` matches `/products/shoes` and `/product/accessories`.
   - **Contains**: Matches URLs that contain a specific keyword or segment anywhere in the URL. Useful for common themes. For example, `/search?q=` matches the search results page for any user query.
   - **Starts with**: Matches all URLs that begin with a specific prefix. Useful for capturing sections of a site. For example, `https://amplitude.com/blog` captures the `/blog` page and all subpages.
5. Select or create a **Segment** using user properties or cohorts to narrow the focus to a specific set of users.
6. Optionally, select different device types to understand how users interact on devices of different widths.
7. Choose a background for your heatmap. Backgrounds are snapshots of a session replay and represent the page's state during replay collection. Each heatmap generates eight backgrounds. Amplitude selects each background from the page state that generates the most actions during a session.