Skip to main content

Button click tracking

This plugin enables the automatic tracking of clicks on buttons, covering both <button> and <input type="button"> elements.

note

The plugin is available from Version 3.18 of the tracker.

Button click events are automatically tracked once configured.

Install plugin

Tracker DistributionIncluded
sp.js
sp.lite.js

Download:

Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)

Enable and disable tracking

To start tracking all button clicks, call the enableButtonClickTracking function:

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');

Then, to stop tracking button clicks, call the disableButtonClickTracking function:

window.snowplow('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.

window.snowplow('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.

window.snowplow('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.

window.snowplow('enableButtonClickTracking', {
filter: (element) => {
return element.id === 'my-button';
},
});

Tracked data

The plugin will track the following data (if present on the element):

FieldDescriptionTypeRequired?
labelThe text on the button, or a user-provided overridestringYes
idThe ID of the buttonstringNo
classesThe classes of the buttonstring[]No
nameThe name of the buttonstringNo

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

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"
}
}