Make addPlugin() consistent across tracker types (close #938)

Author: Paul Boocock

libraries/browser-tracker-core/src/tracker/index.ts

@@ -70,8 +70,8 @@ import {
   DisableAnonymousTrackingConfiguration,
   EnableAnonymousTrackingConfiguration,
   FlushBufferConfiguration,
+  BrowserPluginConfiguration,
 } from './types';
-import { BrowserPlugin } from '../plugins';
 
 /** Repesents an instance of an activity tracking configuration */
 type ActivityConfig = {
@@ -1233,9 +1233,9 @@ export function Tracker(
   const partialTracker = newTracker(trackerId, namespace, version, endpoint, sharedState, trackerConfiguration),
     tracker = {
       ...partialTracker,
-      addPlugin: (plugin: BrowserPlugin) => {
-        tracker.core.addPlugin(plugin);
-        plugin.activateBrowserPlugin?.(tracker);
+      addPlugin: (configuration: BrowserPluginConfiguration) => {
+        tracker.core.addPlugin(configuration);
+        configuration.plugin.activateBrowserPlugin?.(tracker);
       },
     };
 

libraries/browser-tracker-core/src/tracker/types.ts

@@ -29,7 +29,12 @@
  */
 
 import { BrowserPlugin } from '../plugins';
-import { CommonEventProperties, SelfDescribingJson, TrackerCore } from '@snowplow/tracker-core';
+import {
+  CommonEventProperties,
+  SelfDescribingJson,
+  TrackerCore,
+  CorePluginConfiguration,
+} from '@snowplow/tracker-core';
 import { SharedState } from '../state';
 
 /* Configuration for Anonymous Tracking */
@@ -241,18 +246,38 @@ export interface PageViewEvent {
   contextCallback?: (() => Array<SelfDescribingJson>) | null;
 }
 
+/**
+ * The configuration that can be changed when disabling anonymous tracking
+ */
 export interface DisableAnonymousTrackingConfiguration {
+  /* Available configurations for different storage strategies */
   stateStorageStrategy?: StateStorageStrategy;
 }
 
+/**
+ * The configuration that can be changed when enabling anonymous tracking
+ */
 export interface EnableAnonymousTrackingConfiguration {
+  /* Configuration for Anonymous Tracking */
   options?: AnonymousTrackingOptions;
 }
 
+/**
+ * The configuration that can be changed when flushing the buffer
+ */
 export interface FlushBufferConfiguration {
+  /* The size of the buffer after this flush */
   newBufferSize?: number;
 }
 
+/**
+ * The configuration of the plugin to add
+ */
+export interface BrowserPluginConfiguration extends CorePluginConfiguration {
+  /* The plugin to add */
+  plugin: BrowserPlugin;
+}
+
 /**
  * The Browser Tracker
  */
@@ -485,5 +510,9 @@ export interface BrowserTracker {
    */
   clearUserData: () => void;
 
-  addPlugin: (plugin: BrowserPlugin) => void;
+  /**
+   * Add a plugin into the plugin collection after Tracker has already been initialised
+   * @param configuration The plugin to add
+   */
+  addPlugin: (configuration: BrowserPluginConfiguration) => void;
 }

libraries/tracker-core/src/core.ts

@@ -288,17 +288,31 @@ export interface TrackerCore {
 
   /**
    * Add a plugin into the plugin collection after Core has already been initialised
-   * @param plugin The plugin to add
+   * @param configuration The plugin to add
    */
-  addPlugin(plugin: CorePlugin): void;
+  addPlugin(configuration: CorePluginConfiguration): void;
 }
 
+/**
+ * The configuration object for the tracker core library
+ */
 export interface CoreConfiguration {
+  /* Should payloads be base64 encoded when built */
   base64?: boolean;
+  /* A list of all the plugins to include at load */
   corePlugins?: Array<CorePlugin>;
+  /* The callback which will fire each time `track()` is called */
   callback?: (PayloadData: PayloadBuilder) => void;
 }
 
+/**
+ * The configuration of the plugin to add
+ */
+export interface CorePluginConfiguration {
+  /* The plugin to add */
+  plugin: CorePlugin;
+}
+
 /**
  * Create a tracker core object
  *
@@ -513,7 +527,8 @@ export function trackerCore(configuration: CoreConfiguration = {}): TrackerCore
     partialCore = newCore(base64 ?? true, plugins, callback),
     core = {
       ...partialCore,
-      addPlugin: (plugin: CorePlugin) => {
+      addPlugin: (configuration: CorePluginConfiguration) => {
+        const { plugin } = configuration;
         plugins.push(plugin);
         plugin.logger?.(LOG);
         plugin.activateCorePlugin?.(core);

libraries/tracker-core/src/index.ts

@@ -39,6 +39,6 @@ export * from './contexts';
 export * from './plugins';
 export * from './payload';
 export * from './core';
+export * from './logger';
 
 export { version } from '../package.json';
-export { LOG, LOG_LEVEL, Logger } from './logger';

trackers/browser-tracker/src/api.ts

@@ -31,7 +31,7 @@
 import {
   ActivityTrackingConfiguration,
   ActivityTrackingConfigurationCallback,
-  BrowserPlugin,
+  BrowserPluginConfiguration,
   DisableAnonymousTrackingConfiguration,
   EnableAnonymousTrackingConfiguration,
   FlushBufferConfiguration,
@@ -448,8 +448,14 @@ export function clearUserData(trackers?: Array<string>) {
   });
 }
 
-export function addPlugin(configuration: { plugin: BrowserPlugin }, trackers?: Array<string>) {
+/**
+ * Add a plugin into the plugin collection after trackers have already been initialised
+ *
+ * @param configuration The plugin to add
+ * @param trackers The tracker identifiers which the plugin will be added to
+ */
+export function addPlugin(configuration: BrowserPluginConfiguration, trackers?: Array<string>) {
   dispatchToTrackers(trackers, (t) => {
-    t.addPlugin(configuration.plugin);
+    t.addPlugin(configuration);
   });
 }