Button click tracking
This plugin enables the automatic tracking of clicks on buttons, covering both <button>
and <input type="button">
elements.
The plugin is available from Version 3.18 of the tracker.
Button click events are automatically tracked once configured.
Install pluginβ
- JavaScript (tag)
- Browser (npm)
Tracker Distribution | Included |
---|---|
sp.js | β |
sp.lite.js | β |
Download:
Download from GitHub Releases (Recommended) | Github Releases (plugins.umd.zip) |
Available on jsDelivr | jsDelivr (latest) |
Available on unpkg | unpkg (latest) |
npm install @snowplow/browser-plugin-button-click-tracking
yarn add @snowplow/browser-plugin-button-click-tracking
pnpm add @snowplow/browser-plugin-button-click-tracking
Enable and disable trackingβ
To start tracking all button clicks, call the enableButtonClickTracking
function:
- JavaScript (tag)
- Browser (npm)
window.snowplow(
'addPlugin',
'https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-button-click-tracking@latest/dist/index.umd.min.js',
['snowplowButtonClickTracking', 'ButtonClickTrackingPlugin']
);
window.snowplow('enableButtonClickTracking');
import { enableButtonClickTracking, enableButtonClickTracking } from '@snowplow/browser-plugin-button-click-tracking';
newTracker('sp1', '{{collector_url}}', {
appId: 'my-app-id',
plugins: [ ButtonClickTrackingPlugin() ],
});
enableButtonClickTracking();
Then, to stop tracking button clicks, call the disableButtonClickTracking
function:
- JavaScript (tag)
- Browser (npm)
window.snowplow('disableButtonClickTracking');
import { disableButtonClickTracking } from '@snowplow/browser-plugin-button-click-tracking';
disableButtonClickTracking();
Configurationβ
There are three ways to configure which buttons are tracked. If no configuration is specified, as shown above, all buttons on the page will be tracked.
Allowlistβ
You can specify a list of CSS classes to match against the buttons you want to track. Only buttons that contain the class will be tracked.
- JavaScript (tag)
- Browser (npm)
window.snowplow('enableButtonClickTracking', {
filter: {
allowlist: ['my-button'],
}
});
import { enableButtonClickTracking } from '@snowplow/browser-plugin-button-click-tracking';
enableButtonClickTracking({
filter: {
allowlist: ['my-button'],
}
});
Denylistβ
Inversely, you can specify a list of CSS classes to match against the buttons you want to ignore. Only buttons that do not contain the class will be tracked.
- JavaScript (tag)
- Browser (npm)
window.snowplow('enableButtonClickTracking', {
filter: {
denylist: ['my-button'],
}
});
import { enableButtonClickTracking } from '@snowplow/browser-plugin-button-click-tracking';
enableButtonClickTracking({
filter: {
denylist: ['my-button'],
}
});
Filter functionβ
Finally, you can specify a function that will be called for each button on the page. If the function returns true
, the button will be tracked. If it returns false
, the button will not be tracked.
- JavaScript (tag)
- Browser (npm)
window.snowplow('enableButtonClickTracking', {
filter: (element) => {
return element.id === 'my-button';
},
});
import { enableButtonClickTracking } from '@snowplow/browser-plugin-button-click-tracking';
enableButtonClickTracking({
filter: (element) => {
return element.id === 'my-button';
},
});
Tracked dataβ
The plugin will track the following data (if present on the element):
Field | Description | Type | Required? |
---|---|---|---|
label | The text on the button, or a user-provided override | string | Yes |
id | The ID of the button | string | No |
classes | The classes of the button | string[] | No |
name | The name of the button | string | No |
HereΒ is the JSON schema for a button click event.
Overriding the label with data-sp-button-label
β
By default, the plugin will use the text on the button as the label. However, you can override this by adding a data-sp-button-label
attribute to the button:
<button data-sp-button-label="My custom label">Click me</button>
This will result in the following event:
{
"schema": "iglu:com.snowplowanalytics.snowplow/button_click/jsonschema/1-0-0",
"data": {
// Note the label is "My custom label", not "Click me"
"label": "My custom label",
}
}
This can also be useful in the case of icon buttons, where there is no text on the button.
Full exampleβ
- JavaScript (tag)
- Browser (npm)
Suppose we have the following button on our page:
<button id="home-btn" class="nav-btn blue-btn outlined" data-sp-button-label="Home" name="home">
<i class="fa fa-home">
</button>
We can configure the plugin to only track this button class:
window.snowplow('enableButtonClickTracking', {
filter: {
allowlist: ['nav-btn'],
}
});
On click, this will result in the following event:
{
"schema": "iglu:com.snowplowanalytics.snowplow/button_click/jsonschema/1-0-0",
"data": {
"label": "Home",
"id": "home-btn",
"classes": ["nav-btn", "blue-btn", "outlined"],
"name": "home"
}
}
Suppose we have the following button on our page:
<button id="home-btn" class="nav-btn blue-btn outlined" data-sp-button-label="Home" name="home">
<i class="fa fa-home">
</button>
We can configure the plugin to only track this button class:
import { enableButtonClickTracking } from '@snowplow/browser-plugin-button-click-tracking';
enableButtonClickTracking({
filter: {
allowlist: ['nav-btn'],
}
});
On click, this will result in the following event:
{
"schema": "iglu:com.snowplowanalytics.snowplow/button_click/jsonschema/1-0-0",
"data": {
"label": "Home",
"id": "home-btn",
"classes": ["nav-btn", "blue-btn", "outlined"],
"name": "home"
}
}