@amplitude/plugin-autocapture-browser

@amplitude/plugin-autocapture-browser (beta)

This plugin is in beta at the moment, naming and interface might change in the future.

Browser SDK plugin for autocapture.

Installation

This package is published on NPM registry and is available to be installed using npm and yarn.

# npm
npm install @amplitude/plugin-autocapture-browser@beta

# yarn
yarn add @amplitude/plugin-autocapture-browser@beta

Usage

This plugin works on top of the Amplitude Browser SDK, generating auto-tracked events and sending to Amplitude.

To use this plugin, you need to install @amplitude/analytics-browser version v1.9.1 or later.

1. Import Amplitude packages

• @amplitude/analytics-browser
• @amplitude/plugin-autocapture-browser

import * as amplitude from '@amplitude/analytics-browser';
import { autocapturePlugin } from '@amplitude/plugin-autocapture-browser';

2. Instantiate the plugin

The plugin accepts 1 optional parameter, which is an Object to configure the allowed tracking options.

const plugin = autocapturePlugin({
  cssSelectorAllowlist: [
    '.amp-tracking',
    '[amp-tracking]'
  ],
  pageUrlAllowlist: [
    'https://amplitude.com',
    new RegExp('https://amplitude.com/blog/*')
  ],
  pageUrlExcludelist: [
    'https://amplitude.com/admin',
    new RegExp('^https:\\/\\/amplitude\\.com\\/private\\/.*
Examples:

The above cssSelectorAllowlist will only allow tracking elements like:

<button amp-tracking>Click</button>
<a class="amp-tracking">Link</a>


The above pageUrlAllowlist will only allow the elements on URL "https://amplitude.com" or any URL matching the "https://amplitude.com/blog/*" to be tracked
The above pageUrlExcludelist will block tracking on URL "https://amplitude.com/admin" or any URL matching the "^https:\/\/amplitude\.com\/private\/.*$" pattern, even if they match the allowlist

Options



Name
Type
Default
Description



cssSelectorAllowlist
string[]
['a', 'button', 'input', 'select', 'textarea', 'label', '[data-amp-default-track]', '.amp-default-track']
When provided, only allow elements matching any selector to be tracked.


pageUrlAllowlist
(string|RegExp)[]
undefined
When provided, only allow elements matching URLs to be tracked.


pageUrlExcludelist
(string|RegExp)[]
undefined
When provided, block tracking on elements matching URLs. Takes precedence over allowlist.


shouldTrackEventResolver
(actionType: ActionType, element: Element) => boolean
undefined
When provided, overwrite all other allowlists and configurations.


dataAttributePrefix
string
'data-amp-track-'
Allow data attributes to be collected in event property.


3. Install plugin to Amplitude SDK
amplitude.add(plugin);
4. Initialize Amplitude SDK
amplitude.init('API_KEY');
)
  ],
});

Examples:

• The above __INLINE_CODE_5__ will only allow tracking elements like:
  • __INLINE_CODE_6__
  • __INLINE_CODE_7__
• The above __INLINE_CODE_8__ will only allow the elements on URL "https://amplitude.com" or any URL matching the "https://amplitude.com/blog/*" to be tracked
• The above __INLINE_CODE_9__ will block tracking on URL "https://amplitude.com/admin" or any URL matching the "^https:\/\/amplitude\.com\/private\/.*$" pattern, even if they match the allowlist

Options

Name	Type	Default	Description
__INLINE_CODE_10__	__INLINE_CODE_11__	__INLINE_CODE_12__	When provided, only allow elements matching any selector to be tracked.
__INLINE_CODE_13__	__INLINE_CODE_14__	__INLINE_CODE_15__	When provided, only allow elements matching URLs to be tracked.
__INLINE_CODE_16__	__INLINE_CODE_17__	__INLINE_CODE_18__	When provided, block tracking on elements matching URLs. Takes precedence over allowlist.
__INLINE_CODE_19__	__INLINE_CODE_20__	__INLINE_CODE_21__	When provided, overwrite all other allowlists and configurations.
__INLINE_CODE_22__	__INLINE_CODE_23__	__INLINE_CODE_24__	Allow data attributes to be collected in event property.

3. Install plugin to Amplitude SDK

__CODE_BLOCK_3__

4. Initialize Amplitude SDK

__CODE_BLOCK_4__