Skip to content

Autocapture

Amplitude's Autocapture plugin extends the events and properties that Amplitude tracks by default, and enables Visual Labeling to enable you to define events based on elements on your site. For more information about Visual Labeling, see Visual Labeling.

This feature is in alpha release

This feature is in closed alpha release. Customers with any paid plan can contact their Amplitude Customer Service Manager or Account Executive to get access.

Installation

Autocapture requires the latest versions of the Amplitude Browser SDK (2.7.3) and the Autocapture plugin (0.9.0)

<script defer src="https://cdn.amplitude.com/libs/analytics-browser-2.7.3-min.js.gz"></script>
<script defer src="https://cdn.amplitude.com/libs/plugin-autocapture-browser-0.9.0-min.js.gz"></script>
npm install @amplitude/analytics-browser
npm install @amplitude/plugin-autocapture-browser@beta
yarn add @amplitude/analytics-browser
yarn add @amplitude/plugin-autocapture-browser@beta

Initialize the plugin

The Amplitude Browser SDK supports a plugin architecture that enables features like Autocapture. To enable the plugin, update your code with one of the following snippets, depending on your implementation. Both methods require that you define the Autocapture plugin, then call add() to enable it.

<script type="module">
  window.amplitude.init(AMPLITUDE_API_KEY)
  const autocapturePlugin = window.amplitudeAutocapturePlugin.plugin();
  window.amplitude.add(autocapturePlugin);
</script>
import * as amplitude from '@amplitude/analytics-browser';
import { autocapturePlugin } from '@amplitude/plugin-autocapture-browser';

amplitude.init(AMPLITUDE_API_KEY);
amplitude.add(autocapturePlugin());

Configuration

The Autocapture plugin adds four settings that help you configure what the plugin tracks.

Setting
Default Description
cssSelectorAllowlist ['a','button','input','select','textarea','label','[data-amp-default-track]','.amp-default-track'] String[]. Accepts one or more CSS selectors that define which elements on the page to track.
pageUrlAllowlist undefined (string|RegExp)[]. Defines the URL, URLs, or URL pattern on which Amplitude tracks default events
shouldTrackEventResolver undefined Function. Programatically determines if Amplitude should or shouldn't track an event.
dataAttributePrefix data-amp-track Allows the plugin to capture data attributes as an event property
const plugin = autocapturePlugin({
  cssSelectorAllowlist: [
    '.amp-tracking',
    '[amp-tracking]'
  ],
  pageUrlAllowlist: [
    'https://amplitude.com',
    new RegExp('https://amplitude.com/blog/*')
  ],
});

By default, if you don't use these settings, Amplitude tracks the default selectors on all page on which you enable the plugin.

Specifying CSS Selectors

When specify the CSS selectors to track, your selection overrides the default. To retain the default selectors import the DEFAULT_CSS_SELECTOR_ALLOWLIST and include it in your code.

import { DEFAULT_CSS_SELECTOR_ALLOWLIST } from '@amplitude/plugin-autocapture-browser';

const selectors = [
  ...DEFAULT_CSS_SELECTOR_ALLOWLIST,
  '.class-of-a-thing-i-want-to-track',
];

New events

When you enable the Autocapture plugin, Amplitude sends two events, from which you can create Labeled Events with Visual Labeling:

  • [Amplitude] Element Clicked
  • [Amplitude] Element Changed

These two events capture properties that describe the corresponding element and other context about the user's browser:

  • [Amplitude] Element ID
  • [Amplitude] Element Class
  • [Amplitude] Element Tag
  • [Amplitude] Element Text (Collected for [Amplitude] Element Clicked, only)
  • [Amplitude] Element Href (Collected for [Amplitude] Element Clicked, only)
  • [Amplitude] Element Position Left
  • [Amplitude] Element Position Top
  • [Amplitude] Viewport Height
  • [Amplitude] Viewport Width
  • [Amplitude] Page URL
  • [Amplitude] Page Title
  • [Amplitude] Element Selector
  • [Amplitude] Element Attributes
  • [Amplitude] Element Aria Label
  • [Amplitude] Element Parent Label

Disable Autocapture

To disable Autocapture, remove the plugin from any pages that implement it, and set defaultTracking: false in the Amplitude initialization on that page.

Remove the following lines of code:

<!-- load Amplitude Autocapture plugin -->
<script defer src="https://cdn.amplitude.com/libs/plugin-autocapture-browser-0.9.0-min.js.gz"></script>
<!-- initialize Amplitude SDK and Autocapture plugin -->
<script type="module">
  const autocapturePlugin = window.amplitudeAutocapturePlugin.plugin();
  window.amplitude.add(autocapturePlugin);
</script>

Remove the plugin:

// npm
npm uninstall @amplitude/plugin-autocapture-browser

// yarn
yarn remove @amplitude/plugin-autocapture-browser

Remove the initialization code:

// Remove the following lines of code
import { autocapturePlugin } from '@amplitude/plugin-autocapture-browser';

amplitude.add(autocapturePlugin());

Was this page helpful?