caution

You are reading documentation for an outdated version. Here’s the latest one!

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

JavaScript (tag)

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)

Browser (npm)

• npm install @snowplow/browser-plugin-button-click-tracking@3
• yarn add @snowplow/browser-plugin-button-click-tracking@3
• pnpm add @snowplow/browser-plugin-button-click-tracking@3

Enable and disable tracking

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

JavaScript (tag)

window.snowplow(
    'addPlugin',
    'https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-button-click-tracking@3/dist/index.umd.min.js',
    ['snowplowButtonClickTracking', 'ButtonClickTrackingPlugin']
);

window.snowplow('enableButtonClickTracking');

Browser (npm)

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)

window.snowplow('disableButtonClickTracking');

Browser (npm)

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)

window.snowplow('enableButtonClickTracking', {
  filter: {
    allowlist: ['my-button'],
  }
});

Browser (npm)

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)

window.snowplow('enableButtonClickTracking', {
  filter: {
    denylist: ['my-button'],
  }
});

Browser (npm)

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)

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

Browser (npm)

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)

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

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:

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