Add a filter function to plugins to filter out events so that they are not tracked (#1326)

Author: matus-tomlein

api-docs/docs/browser-tracker/markdown/browser-tracker.md

@@ -23,8 +23,7 @@
 |  [enableAnonymousTracking(configuration, trackers)](./browser-tracker.enableanonymoustracking.md) | Enables anonymous tracking (ie. tracker initialized without <code>anonymousTracking</code>) |
 |  [flushBuffer(configuration, trackers)](./browser-tracker.flushbuffer.md) | Send all events in the outQueue Only need to use this when sending events with a bufferSize of at least 2 |
 |  [newSession(trackers)](./browser-tracker.newsession.md) | Expires current session and starts a new session. |
-|  [newTracker(trackerId, endpoint)](./browser-tracker.newtracker.md) | Initialise a new tracker |
-|  [newTracker(trackerId, endpoint, configuration)](./browser-tracker.newtracker_1.md) | Initialise a new tracker |
+|  [newTracker(trackerId, endpoint, configuration)](./browser-tracker.newtracker.md) | Initialise a new tracker |
 |  [preservePageViewId(trackers)](./browser-tracker.preservepageviewid.md) | Stop regenerating <code>pageViewId</code> (available from <code>web_page</code> context) |
 |  [removeGlobalContexts(contexts, trackers)](./browser-tracker.removeglobalcontexts.md) | All provided contexts will no longer be sent with every event |
 |  [setBufferSize(newBufferSize, trackers)](./browser-tracker.setbuffersize.md) | Set the buffer size Can be useful if you want to stop batching requests to ensure events start sending closer to event creation |

api-docs/docs/browser-tracker/markdown/browser-tracker.newtracker.md

@@ -9,7 +9,7 @@ Initialise a new tracker
 <b>Signature:</b>
 
 ```typescript
-declare function newTracker(trackerId: string, endpoint: string): BrowserTracker;
+declare function newTracker(trackerId: string, endpoint: string, configuration?: TrackerConfiguration): BrowserTracker | null | undefined;
 ```
 
 ## Parameters
@@ -18,8 +18,9 @@ declare function newTracker(trackerId: string, endpoint: string): BrowserTracker
 |  --- | --- | --- |
 |  trackerId | string | The tracker id - also known as tracker namespace |
 |  endpoint | string | Collector endpoint in the form collector.mysite.com |
+|  configuration | TrackerConfiguration | The initialisation options of the tracker |
 
 <b>Returns:</b>
 
-BrowserTracker
+BrowserTracker \| null \| undefined
 

api-docs/docs/browser-tracker/markdown/browser-tracker.newtracker_1.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@snowplow/node-tracker](./node-tracker.md) &gt; [CorePlugin](./node-tracker.coreplugin.md) &gt; [filter](./node-tracker.coreplugin.filter.md)
+
+## CorePlugin.filter property
+
+Called before the payload is sent to the callback to decide whether to send the payload or skip it
+
+<b>Signature:</b>
+
+```typescript
+filter?: (payload: Payload) => boolean;
+```

api-docs/docs/node-tracker/markdown/node-tracker.coreplugin.filter.md

@@ -20,5 +20,6 @@ interface CorePlugin
 |  [afterTrack?](./node-tracker.coreplugin.aftertrack.md) | (payload: Payload) =&gt; void | <i>(Optional)</i> Called just after the trackerCore callback fires |
 |  [beforeTrack?](./node-tracker.coreplugin.beforetrack.md) | (payloadBuilder: PayloadBuilder) =&gt; void | <i>(Optional)</i> Called just before the trackerCore callback fires |
 |  [contexts?](./node-tracker.coreplugin.contexts.md) | () =&gt; SelfDescribingJson\[\] | <i>(Optional)</i> Called when constructing the context for each event Useful for adding additional context to events |
+|  [filter?](./node-tracker.coreplugin.filter.md) | (payload: Payload) =&gt; boolean | <i>(Optional)</i> Called before the payload is sent to the callback to decide whether to send the payload or skip it |
 |  [logger?](./node-tracker.coreplugin.logger.md) | (logger: Logger) =&gt; void | <i>(Optional)</i> Passed a logger instance which can be used to send log information to the active logger |
 

api-docs/docs/node-tracker/markdown/node-tracker.coreplugin.md

@@ -179,6 +179,7 @@ export interface CorePlugin {
     afterTrack?: (payload: Payload) => void;
     beforeTrack?: (payloadBuilder: PayloadBuilder) => void;
     contexts?: () => SelfDescribingJson[];
+    filter?: (payload: Payload) => boolean;
     // Warning: (ae-forgotten-export) The symbol "Logger" needs to be exported by the entry point index.module.d.ts
     logger?: (logger: Logger) => void;
 }

api-docs/docs/node-tracker/node-tracker.api.md

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/browser-tracker-core",
+      "comment": "Add a filter function to plugins to filter out events so that they are not tracked (#1326)",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/browser-tracker-core"
+}

common/changes/@snowplow/browser-tracker-core/issue-plugin_filter_2024-07-09-11-54.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/browser-tracker",
+      "comment": "Add a filter function to plugins to filter out events so that they are not tracked (#1326)",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/browser-tracker"
+}

common/changes/@snowplow/browser-tracker/issue-plugin_filter_2024-07-09-11-54.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/javascript-tracker",
+      "comment": "Add a filter function to plugins to filter out events so that they are not tracked (#1326)",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/javascript-tracker"
+}

common/changes/@snowplow/javascript-tracker/issue-plugin_filter_2024-07-09-11-54.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/node-tracker",
+      "comment": "Add a filter function to plugins to filter out events so that they are not tracked (#1326)",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/node-tracker"
+}

common/changes/@snowplow/node-tracker/issue-plugin_filter_2024-07-09-11-54.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/tracker-core",
+      "comment": "Add a filter function to plugins to filter out events so that they are not tracked (#1326)",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/tracker-core"
+}

common/changes/@snowplow/tracker-core/issue-plugin_filter_2024-07-09-11-54.json

@@ -138,7 +138,7 @@ export interface TrackerCore {
    * @param pb - Payload
    * @param context - Custom contexts relating to the event
    * @param timestamp - Timestamp of the event
-   * @returns Payload after the callback is applied
+   * @returns Payload after the callback is applied or undefined if the event is skipped
    */
   track: (
     /** A PayloadBuilder created by one of the `buildX` functions */
@@ -147,7 +147,7 @@ export interface TrackerCore {
     context?: Array<SelfDescribingJson> | null,
     /** Timestamp override */
     timestamp?: Timestamp | null
-  ) => Payload;
+  ) => Payload | undefined;
 
   /**
    * Set a persistent key-value pair to be added to every payload
@@ -376,13 +376,13 @@ export function trackerCore(configuration: CoreConfiguration = {}): TrackerCore
      * @param pb - Payload
      * @param context - Custom contexts relating to the event
      * @param timestamp - Timestamp of the event
-     * @returns Payload after the callback is applied
+     * @returns Payload after the callback is applied or undefined if the event is skipped
      */
     function track(
       pb: PayloadBuilder,
       context?: Array<SelfDescribingJson> | null,
       timestamp?: Timestamp | null
-    ): Payload {
+    ): Payload | undefined {
       pb.withJsonProcessor(payloadJsonProcessor(encodeBase64));
       pb.add('eid', uuid());
       pb.addDict(payloadPairs);
@@ -404,6 +404,19 @@ export function trackerCore(configuration: CoreConfiguration = {}): TrackerCore
         }
       });
 
+      // Call the filter on plugins to determine if the event should be tracked
+      const skip = corePlugins.find((plugin) => {
+        try {
+          return plugin.filter && plugin.filter(pb.build()) === false;
+        } catch (ex) {
+          LOG.error('Plugin filter', ex);
+          return false;
+        }
+      });
+      if (skip) {
+        return undefined;
+      }
+
       if (typeof callback === 'function') {
         callback(pb);
       }

libraries/tracker-core/src/core.ts

@@ -44,7 +44,7 @@ export interface CorePlugin {
    */
   activateCorePlugin?: (core: TrackerCore) => void;
   /**
-   * Called just before the trackerCore callback fires
+   * Called before the `filter` method is called and before the trackerCore callback fires (if the filter passes)
    * @param payloadBuilder - The payloadBuilder which will be sent to the callback, can be modified
    */
   beforeTrack?: (payloadBuilder: PayloadBuilder) => void;
@@ -53,6 +53,12 @@ export interface CorePlugin {
    * @param payload - The final built payload
    */
   afterTrack?: (payload: Payload) => void;
+  /**
+   * Called before the payload is sent to the callback to decide whether to send the payload or skip it
+   * @param payload - The final event payload, can't be modified.
+   * @returns True if the payload should be sent, false if it should be skipped
+   */
+  filter?: (payload: Payload) => boolean;
   /**
    * Called when constructing the context for each event
    * Useful for adding additional context to events