Add a configurable default label in button click tracking and fix disabling for specific trackers (close #1397 and #1421)

PR #1423

Author: jethron

Diff for: common/changes/@snowplow/browser-plugin-button-click-tracking/issue-button-click-disable_2025-04-04-06-42.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/browser-plugin-button-click-tracking",
+      "comment": "Allow per-tracker disabling",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/browser-plugin-button-click-tracking"
+}

Diff for: common/changes/@snowplow/browser-plugin-button-click-tracking/issue-button-click-disable_2025-04-04-06-48.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/browser-plugin-button-click-tracking",
+      "comment": "Add default label to avoid bad events",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/browser-plugin-button-click-tracking"
+}

Diff for: common/changes/@snowplow/javascript-tracker/issue-button-click-disable_2025-04-04-06-42.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/javascript-tracker",
+      "comment": "Fix inactive button-click test",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/javascript-tracker"
+}

Diff for: plugins/browser-plugin-button-click-tracking/src/api.ts

@@ -52,13 +52,19 @@ export function enableButtonClickTracking(
 ) {
   // Ensure that click tracking uses the latest configuration
   // In the case of `enableButtonClickTracking` being called multiple times in a row
-  disableButtonClickTracking();
+  disableButtonClickTracking(trackers);
 
   trackers.forEach((trackerId) => {
     // Store the configuration for this tracker, if it doesn't already exist
     // This allows us to enable click tracking for a tracker if it has been disabled
     _listeners[trackerId] = (event: MouseEvent) => {
-      eventHandler(event, trackerId, filterFunctionFromFilter(configuration.filter), configuration.context);
+      eventHandler(
+        event,
+        trackerId,
+        filterFunctionFromFilter(configuration.filter),
+        configuration.defaultLabel,
+        configuration.context
+      );
     };
 
     const addClickListener = () => {
@@ -80,12 +86,12 @@ export function enableButtonClickTracking(
  *
  * Can be re-enabled with {@link enableButtonClickTracking}
  */
-export function disableButtonClickTracking() {
-  for (const trackerId in _trackers) {
+export function disableButtonClickTracking(trackers: Array<string> = Object.keys(_trackers)) {
+  trackers.forEach((trackerId) => {
     if (_listeners[trackerId]) {
       document.removeEventListener('click', _listeners[trackerId], true);
     }
-  }
+  });
 }
 
 /**
@@ -96,12 +102,18 @@ export function disableButtonClickTracking() {
  * @param filter - The filter function to use for button click tracking
  * @param context - The dynamic context which will be evaluated for each button click event
  */
-function eventHandler(event: MouseEvent, trackerId: string, filter: FilterFunction, context?: DynamicContext) {
+function eventHandler(
+  event: MouseEvent,
+  trackerId: string,
+  filter: FilterFunction,
+  defaultLabel?: string | ((element: HTMLElement) => string),
+  context?: DynamicContext
+) {
   let elem = (event.composed ? event.composedPath()[0] : event.target) as HTMLElement | null;
   while (elem) {
     if (elem instanceof HTMLButtonElement || (elem instanceof HTMLInputElement && elem.type === 'button')) {
       if (filter(elem)) {
-        const buttonClickEvent = createEventFromButton(elem);
+        const buttonClickEvent = createEventFromButton(elem, defaultLabel);
         buttonClickEvent.context = resolveDynamicContext(context, buttonClickEvent, elem);
         trackButtonClick(buttonClickEvent, [trackerId]);
       }

Diff for: plugins/browser-plugin-button-click-tracking/src/types.ts

@@ -18,6 +18,8 @@ export interface ButtonClickTrackingConfiguration {
   filter?: Filter;
   /** The dynamic context which will be evaluated for each button click event */
   context?: DynamicContext;
+  /** A default label to use if one can not be determined by the content or data attributes */
+  defaultLabel?: string | ((element: HTMLElement) => string);
 }
 
 /**

Diff for: plugins/browser-plugin-button-click-tracking/src/util.ts

@@ -42,14 +42,19 @@ export function filterFunctionFromFilter(filter?: Filter): FilterFunction {
  * @returns The button click event
  */
 export function createEventFromButton(
-  button: HTMLButtonElement | HTMLInputElement
+  button: HTMLButtonElement | HTMLInputElement,
+  defaultLabel?: string | ((element: HTMLElement) => string)
 ): ButtonClickEvent & CommonEventProperties {
   let ret = {} as ButtonClickEvent & CommonEventProperties;
 
   if (button.tagName === 'INPUT') {
     ret.label = button.dataset.spButtonLabel || button.value;
   } else {
-    ret.label = button.dataset.spButtonLabel || button.innerText;
+    ret.label =
+      button.dataset.spButtonLabel ||
+      button.innerText ||
+      (typeof defaultLabel === 'function' ? defaultLabel(button) : defaultLabel) ||
+      '(empty)';
   }
 
   button.id && (ret.id = button.id);

Diff for: plugins/browser-plugin-button-click-tracking/test/test.test.ts

@@ -145,6 +145,31 @@ describe('Button Click Tracking Plugin', () => {
         expect(createEventFromButton(button)).toEqual(event);
       });
 
+      it('should use specified default label', () => {
+        const button = document.createElement('button');
+        button.innerText = '';
+        button.id = 'testId';
+        button.className = 'testClass testClass2';
+        button.name = 'testName';
+
+        const event1 = {
+          label: 'defaultLabel',
+          id: 'testId',
+          classes: ['testClass', 'testClass2'],
+          name: 'testName',
+        };
+
+        expect(createEventFromButton(button, 'defaultLabel')).toEqual(event1);
+
+        const event2 = {
+          label: 'testClass testClass2',
+          id: 'testId',
+          classes: ['testClass', 'testClass2'],
+          name: 'testName',
+        };
+        expect(createEventFromButton(button, (btn) => btn.className)).toEqual(event2);
+      });
+
       it('should prefer the data-sp-button-label attribute over the innerText', () => {
         const button = document.createElement('button');
         button.innerText = 'testLabel';

Diff for: trackers/javascript-tracker/test/integration/buttonClick.test.ts

@@ -30,11 +30,11 @@ describe('Snowplow Micro integration', () => {
     name?: string;
   };
 
-  const makeEvent = (button: Button, method: string) => {
+  const makeEvent = (button: Button, method: string, suffix: string = '') => {
     return {
       event: {
         event: 'unstruct',
-        app_id: 'button-click-tracking-' + testIdentifier,
+        app_id: 'button-click-tracking-' + testIdentifier + suffix,
         page_url: `http://snowplow-js-tracker.local:8080/button-click-tracking.html?eventMethod=${method}`,
         unstruct_event: {
           data: {
@@ -81,6 +81,11 @@ describe('Snowplow Micro integration', () => {
       await (await $('#disabled-click')).click();
       await browser.pause(500);
 
+      await (await $('#selective')).click();
+      await browser.pause(500);
+      await (await $('#selective-click')).click();
+      await browser.pause(500);
+
       await (await $('#enable')).click();
       await browser.pause(500);
       await (await $('#enabled-click')).click();
@@ -155,14 +160,29 @@ describe('Snowplow Micro integration', () => {
       expect(logContains(ev)).toBe(false);
     });
 
+    it('should get one selective-click', () => {
+      const ev1 = makeEvent({ id: 'selective-click', label: 'SelectiveEnabledClick' }, method);
+      expect(logContains(ev1)).toBe(false);
+
+      const ev2 = makeEvent({ id: 'selective-click', label: 'SelectiveEnabledClick' }, method, '-second');
+      logContainsButtonClick(ev2);
+    });
+
     it('should get enabled-click', () => {
       const ev = makeEvent({ id: 'enabled-click', label: 'EnabledClick' }, method);
       logContainsButtonClick(ev);
     });
 
     it('should get `final-config` as it is the last config set', () => {
-      const ev = makeEvent({ id: 'final-config', classes: ['final-config'], label: 'Final Config' }, method);
-      logContainsButtonClick(ev);
+      const ev1 = makeEvent({ id: 'final-config', classes: ['final-config'], label: 'Final Config' }, method);
+      logContainsButtonClick(ev1);
+
+      const ev2 = makeEvent(
+        { id: 'final-config', classes: ['final-config'], label: 'Final Config' },
+        method,
+        '-second'
+      );
+      expect(logContains(ev2)).toBe(false);
     });
   });
 });

Diff for: trackers/javascript-tracker/test/pages/button-click-tracking.html

@@ -59,17 +59,20 @@
     <button id="disable" onclick="snowplow('disableButtonClickTracking')">Disable</button>
     <button id="disabled-click">DisabledClick</button>
 
+    <button id="selective" onclick="snowplow('enableButtonClickTracking:sp2')">Selective enable</button>
+    <button id="selective-click">SelectiveEnabledClick</button>
+
     <button id="enable" onclick="snowplow('enableButtonClickTracking')">Enable</button>
     <button id="enabled-click">EnabledClick</button>
 
     <!-- Ensuring the final config is used after multiple calls to `enableButtonClickTracking` -->
-    <button id="set-multiple-configs" onClick="setMultipleConfigs">Set Multiple Configs</button>
+    <button id="set-multiple-configs" onClick="setMultipleConfigs()">Set Multiple Configs</button>
     <button id="final-config" class="final-config">Final Config</button>
 
     <script>
       function setMultipleConfigs() {
-        enableButtonClickTracking({ denylist: ['final-config'] });
-        enableButtonClickTracking();
+        snowplow('enableButtonClickTracking', { filter: { denylist: ['final-config'] } });
+        snowplow('enableButtonClickTracking:sp');
       }
     </script>
 
@@ -112,6 +115,10 @@
         appId: 'button-click-tracking-' + testIdentifier,
         method: parseQuery().eventMethod,
       });
+      snowplow('newTracker', 'sp2', collector_endpoint, {
+        appId: 'button-click-tracking-' + testIdentifier + '-second',
+        method: parseQuery().eventMethod,
+      });
       snowplow(function () {
         document.getElementById('init').innerText = 'true';
       });