Zoning Insights Instrumentation

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

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.

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).

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.

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.

<!-- 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.

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.

// 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.

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

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:

[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 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.