# Zoning Insights Instrumentation

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

Amplitude's autocapture powers Zoning Insights. Choose the instrumentation method that matches your setup. You only need one method — each option enables the same autocapture events that power Zoning Insights.

## Browser SDK

Use the Browser SDK for the most direct path to instrumentation. Zoning Insights requires Browser SDK version 2.39.0 or higher.

### Install the SDK

```bash
npm i @amplitude/analytics-browser@2.39.0
```

### Configure autocapture

After installing the SDK, initialize Amplitude with autocapture enabled. This configures the two settings Zoning Insights needs: `pageViews` to track page views, and `elementInteractions` to track clicks and element visibility.

```javascript
import * as amplitude from '@amplitude/analytics-browser';

const AMPLITUDE_API_KEY = '<API_KEY>'; // replace with your project API key

const options = {
  autocapture: {
    pageViews: true,
    elementInteractions: {
      viewportContentUpdated: true,
  },
  frustrationInteractions: true,
},
}};

amplitude.init(AMPLITUDE_API_KEY, options);
```

### Advanced: fine-tune exposure tracking

For more control, pass an object to `elementInteractions` to configure `viewportContentUpdated` directly. For example, set `exposureDuration` to control how long an element must be visible before it counts as an exposure (default: 150ms).

```javascript
import * as amplitude from '@amplitude/analytics-browser';

const AMPLITUDE_API_KEY = '<API_KEY>';

const options = {
  autocapture: {
    pageViews: true,
    elementInteractions: {
      viewportContentUpdated: {
        enabled: true,
        exposureDuration: 150,
      },
    },
  },
};

amplitude.init(AMPLITUDE_API_KEY, options);
```

### Find your API key

In Amplitude, go to _Settings → Projects → \[Your Project\] → General → API Key_. Replace `<API_KEY>` with your project's API key.

## Google Tag Manager

Use the official Amplitude template from the GTM Template Gallery or a Custom HTML tag. Both approaches load the SDK and enable autocapture for Zoning Insights.

### Option A: Official Amplitude GTM template (recommended)

The official Amplitude GTM template gives you a form-based UI for all SDK settings — no code editing required.

**Step 1: Add the template**

1. In your GTM workspace, go to _Workspace → Templates → Search Gallery_.
2. Search for "Amplitude" and select **Amplitude Analytics Browser SDK**.
3. Click **Add to workspace** and accept the permissions.

**Step 2: Create an Init tag**

1. Go to _Tags → New_ and select the Amplitude template.
2. Set **Tag Type** to **Initialize**. This tag must fire before all other Amplitude tags.
3. Enter your Amplitude API key.
4. Under **Autocapture Events**, make sure **Page Views** and **Element Interactions** are enabled.
5. Set the trigger to **All Pages — Initialization** or **All Pages — DOM Ready**.

| Trigger | Behavior |
| --- | --- |
| **All Pages — Initialization** | Fires earliest — catches all interactions. |
| **All Pages — DOM Ready** | Fires after DOM is parsed — catches nearly all interactions. |
| **All Pages — Window Loaded** | Fires too late — early clicks may be missed. |

**Step 3: Preview and publish**

Use GTM's Preview mode to confirm the init tag fires on every page. Check the browser **Network** tab for requests to `api2.amplitude.com`, then verify that the `[Amplitude] Viewport Content Updated` event appears. Once confirmed, publish the container.

### Option B: Custom HTML tag

For a faster single-site setup, use a Custom HTML tag. Go to _Tags → New → Custom HTML_, paste the snippet below, and set the trigger to **All Pages — DOM Ready**.

```html
<!-- GTM → Tags → New → Custom HTML -->
<!-- Trigger: All Pages — DOM Ready -->
<script src="https://cdn.amplitude.com/libs/analytics-browser-2.39.0-min.js.gz"></script>
<script>
  window.amplitude.init('YOUR_API_KEY', {
    autocapture: {
      pageViews: true,
      elementInteractions: true,
    },
  });
</script>
```

### Content Security Policy

If your site uses CSP headers, add `cdn.amplitude.com` to `script-src` and `api2.amplitude.com` to `connect-src`.

## Tealium iQ

Use a JavaScript Extension in Tealium iQ to load the Amplitude SDK with autocapture enabled.

> **Warning:**
>
> Tealium's server-side Amplitude connector doesn't run the Browser SDK on the page. Zoning Insights requires the SDK running client-side in the browser. Use the JavaScript Extension below instead of, or in addition to, the server-side connector.

### Create a JavaScript Extension

1. In Tealium iQ, go to _Extensions → Add Extension → JavaScript Code_.
2. Set the scope to **Before Load Rules** and the condition to **All Pages**.
3. Paste the code below.
4. Replace `YOUR_API_KEY` with your Amplitude project API key.

```javascript
// Tealium iQ → Extensions → JavaScript Code
// Scope: Before Load Rules | Condition: All Pages
(function() {
  var s = document.createElement('script');
  s.src = 'https://cdn.amplitude.com/libs/analytics-browser-2.39.0-min.js.gz';
  s.async = false;
  s.onload = function() {
    if (!window.amplitude) return;
    window.amplitude.init('YOUR_API_KEY', {
      autocapture: {
        pageViews: true,
        elementInteractions: true,
      },
    });
  };
  document.head.appendChild(s);
})();
```

5. Use Tealium's QA mode to verify the extension fires on all pages, then publish the profile.

### Running alongside Tealium EventStream

You can run Tealium's server-side Amplitude connector in parallel with this client-side Extension. EventStream handles your server-side business events; the Extension handles Zoning Insights autocapture. Both write to the same Amplitude project using the same API key.

## Segment

Load the Amplitude Browser SDK alongside Segment. Zoning Insights requires the SDK running client-side — Segment's server-side Amplitude destination alone isn't enough.

> **Warning:**
>
> Segment's cloud-mode Amplitude (Actions) destination routes events to Amplitude's HTTP API — it doesn't load the Browser SDK or enable autocapture on the page. You need the SDK running in the browser for Zoning Insights to work.

Load both SDKs in parallel. Amplitude handles Zoning Insights autocapture; Segment handles your existing custom event pipeline. The two SDKs don't conflict.

```javascript
import * as amplitude from '@amplitude/analytics-browser';
import { AnalyticsBrowser } from '@segment/analytics-next';

// Amplitude — handles Zoning Insights autocapture
amplitude.init('YOUR_AMPLITUDE_API_KEY', {
  autocapture: {
    pageViews: true,
    elementInteractions: true,
  },
});

// Segment — your existing event pipeline
const analytics = AnalyticsBrowser.load({
  writeKey: 'YOUR_SEGMENT_WRITE_KEY',
});

// Keep user identity in sync
function identify(userId, traits = {}) {
  analytics.identify(userId, traits);
  amplitude.setUserId(userId);
  const evt = new amplitude.Identify();
  Object.entries(traits).forEach(([k, v]) => evt.set(k, v));
  amplitude.identify(evt);
}
```

## Verify your setup

After setting up any of the methods above, confirm that autocapture events are flowing into your Amplitude project.

### Option A: Event Segmentation chart

In Amplitude, create an Event Segmentation chart on the project you sent data to. Search for the event:

```text
[Amplitude] Viewport Content Updated
```

If data appears, autocapture is working correctly and Zoning Insights can start computing metrics.

### Option B: Amplitude Chrome Extension

Install the [Amplitude Chrome Extension](https://chromewebstore.google.com/detail/amplitude-event-explorer/acehfjhnmhbmgkedjmjlobpgdicnhkbp) and navigate to your instrumented site. The extension shows events being tracked in real time. Look for `[Amplitude] Viewport Content Updated` and `[Amplitude] Element Clicked` events appearing as you scroll and click.

### What to look for

Once you see `[Amplitude] Viewport Content Updated` events flowing into your project, Zoning Insights has the data it needs. Zones begin populating with metrics like click rate, exposure rate, scroll reach, and rage click rate.