Add the Event Specifications plugin

common/changes/@snowplow/browser-plugin-event-specifications/feature-event-specifications-plugin_2024-03-25-10-48.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/browser-plugin-event-specifications",
+      "comment": "Created",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/browser-plugin-event-specifications"
+}

common/changes/@snowplow/javascript-tracker/feature-event-specifications-plugin_2024-03-25-10-48.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/javascript-tracker",
+      "comment": "Additions for the Event Specifications plugin",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/javascript-tracker"
+}

common/config/rush/browser-approved-packages.json

@@ -62,6 +62,10 @@
       "name": "@snowplow/browser-plugin-error-tracking",
       "allowedCategories": [ "trackers" ]
     },
+    {
+      "name": "@snowplow/browser-plugin-event-specifications",
+      "allowedCategories": [ "trackers" ]
+    },
     {
       "name": "@snowplow/browser-plugin-focalmeter",
       "allowedCategories": [ "trackers" ]

common/config/rush/repo-state.json

@@ -1,5 +1,5 @@
 // DO NOT MODIFY THIS FILE MANUALLY BUT DO COMMIT IT. It is generated and used by Rush.
 {
-  "pnpmShrinkwrapHash": "76374ca64642c7cf6282ba6e6c9417787e019665",
+  "pnpmShrinkwrapHash": "f6cae2db0ae08480e3fe1d76ae3cc79d521dbfb7",
   "preferredVersionsHash": "bf21a9e8fbc5a3846fb05b4fa0859e0917b2202f"
 }

plugins/browser-plugin-event-specifications/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2024 Snowplow Analytics Ltd
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

plugins/browser-plugin-event-specifications/README.md

@@ -0,0 +1,89 @@
+# Snowplow Event Specifications Plugin
+
+[![npm version][npm-image]][npm-url]
+[![License][license-image]](LICENSE)
+
+Browser Plugin to be used with `@snowplow/browser-tracker`.
+
+The plugin allows you to integrate with Event Specifications for a selected set of plugins. The plugin will automatically add an Event Specification context to the events matching the configuration added on the plugin. This configuration should be retrieved directly from your Data Product in the [Snowplow BDP Console](https://console.snowplowanalytics.com).
+
+## Maintainer quick start
+
+Part of the Snowplow JavaScript Tracker monorepo.  
+Build with [Node.js](https://nodejs.org/en/) (14 or 16) and [Rush](https://rushjs.io/).
+
+### Setup repository
+
+```bash
+npm install -g @microsoft/rush 
+git clone https://github.com/snowplow/snowplow-javascript-tracker.git
+rush update
+```
+
+## Package Installation
+
+With npm:
+
+```bash
+npm install @snowplow/browser-plugin-event-specifications
+```
+
+## Usage
+
+Initialize your tracker with the `EventSpecificationsPlugin`:
+
+```js
+import { newTracker } from '@snowplow/browser-tracker';
+import { EventSpecificationsPlugin } from '@snowplow/browser-plugin-event-specifications';
+
+newTracker('sp1', '{{collector}}', { plugins: [ EventSpecificationsPlugin(/* pluginOptions */) ] });
+
+/* 
+ * Available plugin options `EventSpecificationsPluginOptions`:
+ * {
+ *  [k in AvailablePlugins]: Keys for available plugins that have been added as integrations.
+ * }
+ */
+```
+
+### Getting the expected Event Specification options input
+
+The expected Event Specification option input can be retrieved directly from your Data Product in the [Snowplow BDP Console](https://console.snowplowanalytics.com) and would be similar to the following example:
+
+```js
+EventSpecificationsPlugin(
+     SnowplowMediaPlugin: { play_event: 'event_specification_id' }
+);
+```
+
+### Adding a new integration
+
+Every integration needs to satisfy the following interface:
+
+```ts
+export type Integration = {
+    /**
+     * Find a matching event for the integration with a plugin and an event specification id map.
+     * The returned string should match what we expect as key coming from the configuration object on this specific plugin integration.
+     */
+    detectMatchingEvent: (payloadBuilder: PayloadBuilder) => string | undefined
+}
+```
+
+The `detectMatchingEvent` function should return the key expected for the Event Specification input option of the integration.
+
+To add a new integration, add the required code under `src/integrations` and export it accordingly on the `integrations` object on the `src/integrations/index.ts` file.
+
+## Copyright and license
+
+Licensed and distributed under the [BSD 3-Clause License](LICENSE) ([An OSI Approved License][osi]).
+
+Copyright (c) 2024 Snowplow Analytics Ltd.
+
+All rights reserved.
+
+[npm-url]: https://www.npmjs.com/package/@snowplow/browser-plugin-event-specifications
+[npm-image]: https://img.shields.io/npm/v/@snowplow/browser-plugin-event-specifications
+[docs]: https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/javascript-tracker/
+[osi]: https://opensource.org/licenses/BSD-3-Clause
+[license-image]: https://img.shields.io/npm/l/@snowplow/browser-plugin-event-specifications

plugins/browser-plugin-event-specifications/jest.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+  preset: 'ts-jest',
+  reporters: ['jest-standard-reporter'],
+  testEnvironment: 'jest-environment-jsdom-global',
+};

plugins/browser-plugin-event-specifications/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@snowplow/browser-plugin-event-specifications",
+  "version": "3.22.1",
+  "description": "Automatically adds Event Specifications context to event specifications of a Data Product template.",
+  "homepage": "https://github.com/snowplow/snowplow-javascript-tracker",
+  "bugs": "https://github.com/snowplow/snowplow-javascript-tracker/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/snowplow/snowplow-javascript-tracker.git"
+  },
+  "license": "BSD-3-Clause",
+  "author": "Snowplow Analytics Ltd (https://snowplow.io/)",
+  "sideEffects": false,
+  "main": "./dist/index.umd.js",
+  "module": "./dist/index.module.js",
+  "types": "./dist/index.module.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rollup -c --silent --failAfterWarnings",
+    "test": "jest"
+  },
+  "dependencies": {
+    "@snowplow/browser-tracker-core": "workspace:*",
+    "@snowplow/tracker-core": "workspace:*",
+    "tslib": "^2.3.1"
+  },
+  "devDependencies": {
+    "@ampproject/rollup-plugin-closure-compiler": "~0.27.0",
+    "@rollup/plugin-commonjs": "~21.0.2",
+    "@rollup/plugin-node-resolve": "~13.1.3",
+    "@types/jest": "~27.4.1",
+    "@types/jsdom": "~16.2.14",
+    "@typescript-eslint/eslint-plugin": "~5.15.0",
+    "@typescript-eslint/parser": "~5.15.0",
+    "eslint": "~8.11.0",
+    "jest": "~27.5.1",
+    "jest-environment-jsdom": "~27.5.1",
+    "jest-environment-jsdom-global": "~3.0.0",
+    "jest-standard-reporter": "~2.0.0",
+    "rollup": "~2.70.1",
+    "rollup-plugin-cleanup": "~3.2.1",
+    "rollup-plugin-license": "~2.6.1",
+    "rollup-plugin-terser": "~7.0.2",
+    "rollup-plugin-ts": "~2.0.5",
+    "ts-jest": "~27.1.3",
+    "typescript": "~4.6.2"
+  },
+  "peerDependencies": {
+    "@snowplow/browser-tracker": "~3.22.1"
+  }
+}

plugins/browser-plugin-event-specifications/rollup.config.js

@@ -0,0 +1,37 @@
+import { nodeResolve } from '@rollup/plugin-node-resolve';
+import commonjs from '@rollup/plugin-commonjs';
+import ts from 'rollup-plugin-ts'; // Preferred over @rollup/plugin-typescript as it bundles .d.ts files
+import { banner } from '../../banner';
+import compiler from '@ampproject/rollup-plugin-closure-compiler';
+import { terser } from 'rollup-plugin-terser';
+import cleanup from 'rollup-plugin-cleanup';
+import pkg from './package.json';
+import { builtinModules } from 'module';
+
+const umdPlugins = [nodeResolve({ browser: true }), commonjs(), ts()];
+const umdName = 'eventSpecifications';
+
+export default [
+  // CommonJS (for Node) and ES module (for bundlers) build.
+  {
+    input: './src/index.ts',
+    plugins: [...umdPlugins, banner()],
+    treeshake: { moduleSideEffects: ['sha1'] },
+    output: [{ file: pkg.main, format: 'umd', sourcemap: true, name: umdName }],
+  },
+  {
+    input: './src/index.ts',
+    plugins: [...umdPlugins, compiler(), terser(), cleanup({ comments: 'none' }), banner()],
+    treeshake: { moduleSideEffects: ['sha1'] },
+    output: [{ file: pkg.main.replace('.js', '.min.js'), format: 'umd', sourcemap: true, name: umdName }],
+  },
+  {
+    input: './src/index.ts',
+    external: [...builtinModules, ...Object.keys(pkg.dependencies), ...Object.keys(pkg.devDependencies)],
+    plugins: [
+      ts(), // so Rollup can convert TypeScript to JavaScript
+      banner(),
+    ],
+    output: [{ file: pkg.module, format: 'es', sourcemap: true }],
+  },
+];

plugins/browser-plugin-event-specifications/src/index.ts

@@ -0,0 +1,43 @@
+import { BrowserPlugin, BrowserTracker } from '@snowplow/browser-tracker-core';
+import { integrations, AvailablePlugins } from './integrations';
+import { createEventSpecificationContext } from './utils';
+
+const _trackers: Record<string, BrowserTracker> = {};
+
+type EventSpecificationsPluginOptions = {
+  [k in AvailablePlugins]?: Record<string, string>;
+};
+
+const defaultPluginOptions = {};
+
+export function EventSpecificationsPlugin(
+  pluginOptions: EventSpecificationsPluginOptions = defaultPluginOptions
+): BrowserPlugin {
+  const options = { ...defaultPluginOptions, ...pluginOptions };
+  const enabledIntegrations = Object.keys(integrations).filter(
+    (integration) => options[integration as AvailablePlugins]
+  );
+  let trackerId: string;
+  return {
+    activateBrowserPlugin: (tracker) => {
+      trackerId = tracker.id;
+      _trackers[trackerId] = tracker;
+      return;
+    },
+    beforeTrack(payloadBuilder) {
+      enabledIntegrations.forEach((integrationKey) => {
+        const matchedEvent = integrations[integrationKey as AvailablePlugins].detectMatchingEvent(payloadBuilder);
+        if (!matchedEvent) {
+          return;
+        }
+        const matchingPluginEventMap = Object.values(options).find(
+          (eventSpecificationIds) => eventSpecificationIds[matchedEvent]
+        );
+        if (!matchingPluginEventMap) {
+          return;
+        }
+        payloadBuilder.addContextEntity(createEventSpecificationContext(matchingPluginEventMap[matchedEvent]));
+      });
+    },
+  };
+}

plugins/browser-plugin-event-specifications/src/integrations/index.ts

@@ -0,0 +1,16 @@
+import { PayloadBuilder } from '@snowplow/tracker-core';
+import { snowplowMediaPluginIntegration } from './snowplow-media-plugin';
+
+export type AvailablePlugins = 'SnowplowMediaPlugin';
+
+export type Integration = {
+  /**
+   * Find a matching event for the integration with a plugin and an event specification id map.
+   * The returned string should match what we expect as key coming from the configuration object on this specific plugin integration.
+   */
+  detectMatchingEvent: (payloadBuilder: PayloadBuilder) => string | undefined;
+};
+
+export const integrations = {
+  SnowplowMediaPlugin: snowplowMediaPluginIntegration,
+} as const;