Add support for named global context (#1331)

The `addGlobalContexts` API now accepts an `object` mapping "names" to context primitives or context generators, rather than just an array of "unnamed" global entities/generators.

Calling `addGlobalContexts` multiple times with values of the same "name" will overwrite the previous value for subsequent events, allowing "upserting" or updating of global context without having to remove the previous version first and introducing duplicates.

`removeGlobalContexts` can now also accept plain strings which are handled as names, so primitives/generators can be removed by name without having to own a reference to the generating function or an object that serializes to the same string.

Author: jethron

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

@@ -29,7 +29,7 @@ export interface ActivityTrackingConfigurationCallback {
 }
 
 // @public
-export function addGlobalContexts(contexts: Array<ConditionalContextProvider | ContextPrimitive>, trackers?: Array<string>): void;
+export function addGlobalContexts(contexts: Array<ConditionalContextProvider | ContextPrimitive> | Record<string, ConditionalContextProvider | ContextPrimitive>, trackers?: Array<string>): void;
 
 // @public
 export function addPlugin(configuration: BrowserPluginConfiguration, trackers?: Array<string>): void;
@@ -293,7 +293,7 @@ export function preservePageViewId(trackers?: Array<string>): void;
 export type PreservePageViewIdForUrl = boolean | "full" | "pathname" | "pathnameAndSearch";
 
 // @public
-export function removeGlobalContexts(contexts: Array<ConditionalContextProvider | ContextPrimitive>, trackers?: Array<string>): void;
+export function removeGlobalContexts(contexts: Array<ConditionalContextProvider | ContextPrimitive | string>, trackers?: Array<string>): void;
 
 // @public
 export type RequestFailure = {

common/changes/@snowplow/browser-tracker/PE-5311-namedctx_2024-07-17-02-36.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/browser-tracker",
+      "comment": "Add support for named global context",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/browser-tracker"
+}

common/changes/@snowplow/tracker-core/PE-5311-namedctx_2024-07-17-02-36.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/tracker-core",
+      "comment": "Add support for named global context",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/tracker-core"
+}

libraries/tracker-core/src/contexts.ts

@@ -116,7 +116,11 @@ export interface GlobalContexts {
    * Adds conditional or primitive global contexts
    * @param contexts - An Array of either Conditional Contexts or Primitive Contexts
    */
-  addGlobalContexts(contexts: Array<ConditionalContextProvider | ContextPrimitive>): void;
+  addGlobalContexts(
+    contexts:
+      | Array<ConditionalContextProvider | ContextPrimitive>
+      | Record<string, ConditionalContextProvider | ContextPrimitive>
+  ): void;
 
   /**
    * Removes all global contexts
@@ -127,7 +131,7 @@ export interface GlobalContexts {
    * Removes previously added global context, performs a deep comparison of the contexts or conditional contexts
    * @param contexts - An Array of either Condition Contexts or Primitive Contexts
    */
-  removeGlobalContexts(contexts: Array<ConditionalContextProvider | ContextPrimitive>): void;
+  removeGlobalContexts(contexts: Array<ConditionalContextProvider | ContextPrimitive | string>): void;
 
   /**
    * Returns all applicable global contexts for a specified event
@@ -142,6 +146,8 @@ export interface GlobalContexts {
 export function globalContexts(): GlobalContexts {
   let globalPrimitives: Array<ContextPrimitive> = [];
   let conditionalProviders: Array<ConditionalContextProvider> = [];
+  let namedPrimitives: Record<string, ContextPrimitive> = {};
+  let namedConditionalProviders: Record<string, ConditionalContextProvider> = {};
 
   /**
    * Returns all applicable global contexts for a specified event
@@ -152,46 +158,75 @@ export function globalContexts(): GlobalContexts {
     const eventSchema = getUsefulSchema(event);
     const eventType = getEventType(event);
     const contexts: Array<SelfDescribingJson> = [];
-    const generatedPrimitives = generatePrimitives(globalPrimitives, event, eventType, eventSchema);
+    const generatedPrimitives = generatePrimitives(
+      globalPrimitives.concat(Object.values(namedPrimitives)),
+      event,
+      eventType,
+      eventSchema
+    );
     contexts.push(...generatedPrimitives);
 
-    const generatedConditionals = generateConditionals(conditionalProviders, event, eventType, eventSchema);
+    const generatedConditionals = generateConditionals(
+      conditionalProviders.concat(Object.values(namedConditionalProviders)),
+      event,
+      eventType,
+      eventSchema
+    );
     contexts.push(...generatedConditionals);
 
     return contexts;
   };
 
   return {
     getGlobalPrimitives(): Array<ContextPrimitive> {
-      return globalPrimitives;
+      return globalPrimitives.concat(Object.values(namedPrimitives));
     },
 
     getConditionalProviders(): Array<ConditionalContextProvider> {
-      return conditionalProviders;
+      return conditionalProviders.concat(Object.values(namedConditionalProviders));
     },
 
-    addGlobalContexts(contexts: Array<ConditionalContextProvider | ContextPrimitive>): void {
-      const acceptedConditionalContexts: ConditionalContextProvider[] = [];
-      const acceptedContextPrimitives: ContextPrimitive[] = [];
-      for (const context of contexts) {
-        if (isConditionalContextProvider(context)) {
-          acceptedConditionalContexts.push(context);
-        } else if (isContextPrimitive(context)) {
-          acceptedContextPrimitives.push(context);
+    addGlobalContexts(
+      contexts:
+        | Array<ConditionalContextProvider | ContextPrimitive>
+        | Record<string, ConditionalContextProvider | ContextPrimitive>
+    ): void {
+      if (Array.isArray(contexts)) {
+        const acceptedConditionalContexts: ConditionalContextProvider[] = [];
+        const acceptedContextPrimitives: ContextPrimitive[] = [];
+        for (const context of contexts) {
+          if (isConditionalContextProvider(context)) {
+            acceptedConditionalContexts.push(context);
+          } else if (isContextPrimitive(context)) {
+            acceptedContextPrimitives.push(context);
+          }
+        }
+        globalPrimitives = globalPrimitives.concat(acceptedContextPrimitives);
+        conditionalProviders = conditionalProviders.concat(acceptedConditionalContexts);
+      } else {
+        for (const [name, context] of Object.entries(contexts)) {
+          if (isConditionalContextProvider(context)) {
+            namedConditionalProviders[name] = context;
+          } else if (isContextPrimitive(context)) {
+            namedPrimitives[name] = context;
+          }
         }
       }
-      globalPrimitives = globalPrimitives.concat(acceptedContextPrimitives);
-      conditionalProviders = conditionalProviders.concat(acceptedConditionalContexts);
     },
 
     clearGlobalContexts(): void {
       conditionalProviders = [];
       globalPrimitives = [];
+      namedConditionalProviders = {};
+      namedPrimitives = {};
     },
 
-    removeGlobalContexts(contexts: Array<ConditionalContextProvider | ContextPrimitive>): void {
+    removeGlobalContexts(contexts: Array<ConditionalContextProvider | ContextPrimitive | string>): void {
       for (const context of contexts) {
-        if (isConditionalContextProvider(context)) {
+        if (typeof context === 'string') {
+          delete namedConditionalProviders[context];
+          delete namedPrimitives[context];
+        } else if (isConditionalContextProvider(context)) {
           conditionalProviders = conditionalProviders.filter(
             (item) => JSON.stringify(item) !== JSON.stringify(context)
           );

libraries/tracker-core/src/core.ts

@@ -273,7 +273,11 @@ export interface TrackerCore {
    * Adds contexts globally, contexts added here will be attached to all applicable events
    * @param contexts - An array containing either contexts or a conditional contexts
    */
-  addGlobalContexts(contexts: Array<ConditionalContextProvider | ContextPrimitive>): void;
+  addGlobalContexts(
+    contexts:
+      | Array<ConditionalContextProvider | ContextPrimitive>
+      | Record<string, ConditionalContextProvider | ContextPrimitive>
+  ): void;
 
   /**
    * Removes all global contexts
@@ -284,7 +288,7 @@ export interface TrackerCore {
    * Removes previously added global context, performs a deep comparison of the contexts or conditional contexts
    * @param contexts - An array containing either contexts or a conditional contexts
    */
-  removeGlobalContexts(contexts: Array<ConditionalContextProvider | ContextPrimitive>): void;
+  removeGlobalContexts(contexts: Array<ConditionalContextProvider | ContextPrimitive | string>): void;
 
   /**
    * Add a plugin into the plugin collection after Core has already been initialised

libraries/tracker-core/test/contexts.ts

@@ -215,6 +215,75 @@ test('Add global contexts', (t) => {
   t.is(globalContexts.getConditionalProviders().length, 2, 'Correct number of conditional providers added');
 });
 
+test('Handle named global contexts', (t) => {
+  const geolocationContext = {
+    schema: 'iglu:com.snowplowanalytics.snowplow/geolocation_context/jsonschema/1-1-0',
+    data: {
+      latitude: 40.0,
+      longitude: 55.1,
+    },
+  };
+
+  function eventTypeContextGenerator(args?: contexts.ContextEvent) {
+    const context: SelfDescribingJson = {
+      schema: 'iglu:com.snowplowanalytics.snowplow/mobile_context/jsonschema/1-0-1',
+      data: {
+        osType: 'ubuntu',
+        osVersion: '2018.04',
+        deviceManufacturer: 'ASUS',
+        deviceModel: args ? String(args['eventType']) : '',
+      },
+    };
+    return context;
+  }
+
+  const bothRuleSet = {
+    accept: ['iglu:com.snowplowanalytics.snowplow/*/jsonschema/*-*-*'],
+    reject: ['iglu:com.snowplowanalytics.snowplow/*/jsonschema/*-*-*'],
+  };
+
+  const filterFunction = function (args?: contexts.ContextEvent) {
+    return args?.eventType === 'ue';
+  };
+
+  const filterProvider: contexts.FilterProvider = [filterFunction, [geolocationContext, eventTypeContextGenerator]];
+  const ruleSetProvider: contexts.RuleSetProvider = [bothRuleSet, [geolocationContext, eventTypeContextGenerator]];
+
+  const namedContexts = {
+    filters: filterProvider,
+    rules: ruleSetProvider,
+    static: geolocationContext,
+    generator: eventTypeContextGenerator,
+  };
+  const globalContexts = contexts.globalContexts();
+
+  globalContexts.addGlobalContexts(namedContexts);
+  t.is(globalContexts.getGlobalPrimitives().length, 2, 'Correct number of primitives added');
+  t.is(globalContexts.getConditionalProviders().length, 2, 'Correct number of conditional providers added');
+
+  globalContexts.removeGlobalContexts(['static', 'rules']);
+  t.is(globalContexts.getGlobalPrimitives().length, 1, 'Correct number of primitives removed');
+  t.is(globalContexts.getConditionalProviders().length, 1, 'Correct number of conditional providers removed');
+
+  globalContexts.clearGlobalContexts();
+  t.is(globalContexts.getGlobalPrimitives().length, 0, 'All primitives removed');
+  t.is(globalContexts.getConditionalProviders().length, 0, 'All conditional providers removed');
+
+  globalContexts.addGlobalContexts([geolocationContext]);
+  globalContexts.addGlobalContexts({ geo: geolocationContext });
+  t.is(globalContexts.getGlobalPrimitives().length, 2, 'Treats anonymous and named globals separately');
+
+  const mutatedGeolocationContext = JSON.parse(JSON.stringify(geolocationContext));
+  mutatedGeolocationContext.data.latitude = 30;
+
+  globalContexts.addGlobalContexts({ geo: mutatedGeolocationContext });
+  t.deepEqual(
+    globalContexts.getGlobalPrimitives(),
+    [geolocationContext, mutatedGeolocationContext],
+    'Upserts named globals'
+  );
+});
+
 test('Remove one of two global context primitives', (t) => {
   const geolocationContext = {
     schema: 'iglu:com.snowplowanalytics.snowplow/geolocation_context/jsonschema/1-1-0',

trackers/browser-tracker/src/api.ts

@@ -411,7 +411,9 @@ export function trackSelfDescribingEvent(event: SelfDescribingEvent & CommonEven
  * @param trackers - The tracker identifiers which the global contexts will be added to
  */
 export function addGlobalContexts(
-  contexts: Array<ConditionalContextProvider | ContextPrimitive>,
+  contexts:
+    | Array<ConditionalContextProvider | ContextPrimitive>
+    | Record<string, ConditionalContextProvider | ContextPrimitive>,
   trackers?: Array<string>
 ) {
   dispatchToTrackers(trackers, (t) => {
@@ -426,7 +428,7 @@ export function addGlobalContexts(
  * @param trackers - The tracker identifiers which the global contexts will be remove from
  */
 export function removeGlobalContexts(
-  contexts: Array<ConditionalContextProvider | ContextPrimitive>,
+  contexts: Array<ConditionalContextProvider | ContextPrimitive | string>,
   trackers?: Array<string>
 ) {
   dispatchToTrackers(trackers, (t) => {