Autocapture Plugin

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.

Installation

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

1<script defer src="https://cdn.amplitude.com/libs/analytics-browser-2.9.0-min.js.gz"></script>
2<script defer src="https://cdn.amplitude.com/libs/plugin-autocapture-browser-0.9.0-min.js.gz"></script>

1npm install @amplitude/analytics-browser
2npm install @amplitude/plugin-autocapture-browser@beta

1yarn add @amplitude/analytics-browser
2yarn 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.

1<script type="module">
2  window.amplitude.init(AMPLITUDE_API_KEY)
3  const autocapturePlugin = window.amplitudeAutocapturePlugin.plugin();
4  window.amplitude.add(autocapturePlugin);
5</script>

1import * as amplitude from '@amplitude/analytics-browser';
2import { autocapturePlugin } from '@amplitude/plugin-autocapture-browser';
3 
4amplitude.init(AMPLITUDE_API_KEY);
5amplitude.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
`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

 1const plugin = autocapturePlugin({
 2  cssSelectorAllowlist: [
 3    '.amp-tracking',
 4    '[amp-tracking]'
 5  ],
 6  pageUrlAllowlist: [
 7    'https://amplitude.com',
 8    new RegExp('https://amplitude.com/blog/*')
 9  ],
10});

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

Note

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.

1import { DEFAULT_CSS_SELECTOR_ALLOWLIST } from '@amplitude/plugin-autocapture-browser';
2 
3const selectors = [
4  ...DEFAULT_CSS_SELECTOR_ALLOWLIST,
5  '.class-of-a-thing-i-want-to-track',
6];

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:

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

Remove the plugin:

1// npm
2npm uninstall @amplitude/plugin-autocapture-browser
3 
4// yarn
5yarn remove @amplitude/plugin-autocapture-browser

Remove the initialization code:

1// Remove the following lines of code
2import { autocapturePlugin } from '@amplitude/plugin-autocapture-browser';
3 
4amplitude.add(autocapturePlugin());