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

Adding context entities to tracked events​

You can also attach context entities to the tracked button click events as either an array of self-describing JSON objects or a callback function that returns the entities dynamically.

Statically defined context entities​

To add a static list of context entities to the events, use the following configuration

window.snowplow('enableButtonClickTracking', {
  context: [
    {
      schema: 'iglu:com.example_company/page/jsonschema/1-2-1',
      data: { pageType: 'test' }
    }
  ],
});

Dynamic context entities​

You can define a callback function that takes the click event and button element as parameters and returns a context entity for that specific event.

window.snowplow('enableButtonClickTracking', {
  context: function (event, element) {
    return {
      schema: 'iglu:com.example_company/click/jsonschema/1-2-1',
      data: { content: element.textContent }
    };
  },
});

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