Skip to content

Commit c24bb91

Browse files
igneel64igneel64
committed
Add the Event Specifications plugin (snowplow#1300)
1 parent 929ac5d commit c24bb91

23 files changed

+470
-122
lines changed

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

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"changes": [
3+
{
4+
"packageName": "@snowplow/browser-plugin-event-specifications",
5+
"comment": "Created",
6+
"type": "none"
7+
}
8+
],
9+
"packageName": "@snowplow/browser-plugin-event-specifications"
10+
}

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

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"changes": [
3+
{
4+
"packageName": "@snowplow/javascript-tracker",
5+
"comment": "Additions for the Event Specifications plugin",
6+
"type": "none"
7+
}
8+
],
9+
"packageName": "@snowplow/javascript-tracker"
10+
}

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

+4
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,10 @@
6262
"name": "@snowplow/browser-plugin-error-tracking",
6363
"allowedCategories": [ "trackers" ]
6464
},
65+
{
66+
"name": "@snowplow/browser-plugin-event-specifications",
67+
"allowedCategories": [ "trackers" ]
68+
},
6569
{
6670
"name": "@snowplow/browser-plugin-focalmeter",
6771
"allowedCategories": [ "trackers" ]

‎common/config/rush/pnpm-lock.yaml

+51
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎common/config/rush/repo-state.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
// DO NOT MODIFY THIS FILE MANUALLY BUT DO COMMIT IT. It is generated and used by Rush.
22
{
3-
"pnpmShrinkwrapHash": "76374ca64642c7cf6282ba6e6c9417787e019665",
3+
"pnpmShrinkwrapHash": "f6cae2db0ae08480e3fe1d76ae3cc79d521dbfb7",
44
"preferredVersionsHash": "bf21a9e8fbc5a3846fb05b4fa0859e0917b2202f"
55
}

‎plugins/browser-plugin-event-specifications/LICENSE

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

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

+89
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Snowplow Event Specifications Plugin
2+
3+
[![npm version][npm-image]][npm-url]
4+
[![License][license-image]](LICENSE)
5+
6+
Browser Plugin to be used with `@snowplow/browser-tracker`.
7+
8+
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).
9+
10+
## Maintainer quick start
11+
12+
Part of the Snowplow JavaScript Tracker monorepo.
13+
Build with [Node.js](https://nodejs.org/en/) (14 or 16) and [Rush](https://rushjs.io/).
14+
15+
### Setup repository
16+
17+
```bash
18+
npm install -g @microsoft/rush
19+
git clone https://github.com/snowplow/snowplow-javascript-tracker.git
20+
rush update
21+
```
22+
23+
## Package Installation
24+
25+
With npm:
26+
27+
```bash
28+
npm install @snowplow/browser-plugin-event-specifications
29+
```
30+
31+
## Usage
32+
33+
Initialize your tracker with the `EventSpecificationsPlugin`:
34+
35+
```js
36+
import { newTracker } from '@snowplow/browser-tracker';
37+
import { EventSpecificationsPlugin } from '@snowplow/browser-plugin-event-specifications';
38+
39+
newTracker('sp1', '{{collector}}', { plugins: [ EventSpecificationsPlugin(/* pluginOptions */) ] });
40+
41+
/*
42+
* Available plugin options `EventSpecificationsPluginOptions`:
43+
* {
44+
* [k in AvailablePlugins]: Keys for available plugins that have been added as integrations.
45+
* }
46+
*/
47+
```
48+
49+
### Getting the expected Event Specification options input
50+
51+
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:
52+
53+
```js
54+
EventSpecificationsPlugin(
55+
SnowplowMediaPlugin: { play_event: 'event_specification_id' }
56+
);
57+
```
58+
59+
### Adding a new integration
60+
61+
Every integration needs to satisfy the following interface:
62+
63+
```ts
64+
export type Integration = {
65+
/**
66+
* Find a matching event for the integration with a plugin and an event specification id map.
67+
* The returned string should match what we expect as key coming from the configuration object on this specific plugin integration.
68+
*/
69+
detectMatchingEvent: (payloadBuilder: PayloadBuilder) => string | undefined
70+
}
71+
```
72+
73+
The `detectMatchingEvent` function should return the key expected for the Event Specification input option of the integration.
74+
75+
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.
76+
77+
## Copyright and license
78+
79+
Licensed and distributed under the [BSD 3-Clause License](LICENSE) ([An OSI Approved License][osi]).
80+
81+
Copyright (c) 2024 Snowplow Analytics Ltd.
82+
83+
All rights reserved.
84+
85+
[npm-url]: https://www.npmjs.com/package/@snowplow/browser-plugin-event-specifications
86+
[npm-image]: https://img.shields.io/npm/v/@snowplow/browser-plugin-event-specifications
87+
[docs]: https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/javascript-tracker/
88+
[osi]: https://opensource.org/licenses/BSD-3-Clause
89+
[license-image]: https://img.shields.io/npm/l/@snowplow/browser-plugin-event-specifications

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

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
module.exports = {
2+
preset: 'ts-jest',
3+
reporters: ['jest-standard-reporter'],
4+
testEnvironment: 'jest-environment-jsdom-global',
5+
};

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

+53
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
{
2+
"name": "@snowplow/browser-plugin-event-specifications",
3+
"version": "3.22.1",
4+
"description": "Automatically adds Event Specifications context to event specifications of a Data Product template.",
5+
"homepage": "https://github.com/snowplow/snowplow-javascript-tracker",
6+
"bugs": "https://github.com/snowplow/snowplow-javascript-tracker/issues",
7+
"repository": {
8+
"type": "git",
9+
"url": "https://github.com/snowplow/snowplow-javascript-tracker.git"
10+
},
11+
"license": "BSD-3-Clause",
12+
"author": "Snowplow Analytics Ltd (https://snowplow.io/)",
13+
"sideEffects": false,
14+
"main": "./dist/index.umd.js",
15+
"module": "./dist/index.module.js",
16+
"types": "./dist/index.module.d.ts",
17+
"files": [
18+
"dist"
19+
],
20+
"scripts": {
21+
"build": "rollup -c --silent --failAfterWarnings",
22+
"test": "jest"
23+
},
24+
"dependencies": {
25+
"@snowplow/browser-tracker-core": "workspace:*",
26+
"@snowplow/tracker-core": "workspace:*",
27+
"tslib": "^2.3.1"
28+
},
29+
"devDependencies": {
30+
"@ampproject/rollup-plugin-closure-compiler": "~0.27.0",
31+
"@rollup/plugin-commonjs": "~21.0.2",
32+
"@rollup/plugin-node-resolve": "~13.1.3",
33+
"@types/jest": "~27.4.1",
34+
"@types/jsdom": "~16.2.14",
35+
"@typescript-eslint/eslint-plugin": "~5.15.0",
36+
"@typescript-eslint/parser": "~5.15.0",
37+
"eslint": "~8.11.0",
38+
"jest": "~27.5.1",
39+
"jest-environment-jsdom": "~27.5.1",
40+
"jest-environment-jsdom-global": "~3.0.0",
41+
"jest-standard-reporter": "~2.0.0",
42+
"rollup": "~2.70.1",
43+
"rollup-plugin-cleanup": "~3.2.1",
44+
"rollup-plugin-license": "~2.6.1",
45+
"rollup-plugin-terser": "~7.0.2",
46+
"rollup-plugin-ts": "~2.0.5",
47+
"ts-jest": "~27.1.3",
48+
"typescript": "~4.6.2"
49+
},
50+
"peerDependencies": {
51+
"@snowplow/browser-tracker": "~3.22.1"
52+
}
53+
}

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

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
import { nodeResolve } from '@rollup/plugin-node-resolve';
2+
import commonjs from '@rollup/plugin-commonjs';
3+
import ts from 'rollup-plugin-ts'; // Preferred over @rollup/plugin-typescript as it bundles .d.ts files
4+
import { banner } from '../../banner';
5+
import compiler from '@ampproject/rollup-plugin-closure-compiler';
6+
import { terser } from 'rollup-plugin-terser';
7+
import cleanup from 'rollup-plugin-cleanup';
8+
import pkg from './package.json';
9+
import { builtinModules } from 'module';
10+
11+
const umdPlugins = [nodeResolve({ browser: true }), commonjs(), ts()];
12+
const umdName = 'eventSpecifications';
13+
14+
export default [
15+
// CommonJS (for Node) and ES module (for bundlers) build.
16+
{
17+
input: './src/index.ts',
18+
plugins: [...umdPlugins, banner()],
19+
treeshake: { moduleSideEffects: ['sha1'] },
20+
output: [{ file: pkg.main, format: 'umd', sourcemap: true, name: umdName }],
21+
},
22+
{
23+
input: './src/index.ts',
24+
plugins: [...umdPlugins, compiler(), terser(), cleanup({ comments: 'none' }), banner()],
25+
treeshake: { moduleSideEffects: ['sha1'] },
26+
output: [{ file: pkg.main.replace('.js', '.min.js'), format: 'umd', sourcemap: true, name: umdName }],
27+
},
28+
{
29+
input: './src/index.ts',
30+
external: [...builtinModules, ...Object.keys(pkg.dependencies), ...Object.keys(pkg.devDependencies)],
31+
plugins: [
32+
ts(), // so Rollup can convert TypeScript to JavaScript
33+
banner(),
34+
],
35+
output: [{ file: pkg.module, format: 'es', sourcemap: true }],
36+
},
37+
];

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

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
import { BrowserPlugin, BrowserTracker } from '@snowplow/browser-tracker-core';
2+
import { integrations, AvailablePlugins } from './integrations';
3+
import { createEventSpecificationContext } from './utils';
4+
5+
const _trackers: Record<string, BrowserTracker> = {};
6+
7+
type EventSpecificationsPluginOptions = {
8+
[k in AvailablePlugins]?: Record<string, string>;
9+
};
10+
11+
const defaultPluginOptions = {};
12+
13+
export function EventSpecificationsPlugin(
14+
pluginOptions: EventSpecificationsPluginOptions = defaultPluginOptions
15+
): BrowserPlugin {
16+
const options = { ...defaultPluginOptions, ...pluginOptions };
17+
const enabledIntegrations = Object.keys(integrations).filter(
18+
(integration) => options[integration as AvailablePlugins]
19+
);
20+
let trackerId: string;
21+
return {
22+
activateBrowserPlugin: (tracker) => {
23+
trackerId = tracker.id;
24+
_trackers[trackerId] = tracker;
25+
},
26+
beforeTrack(payloadBuilder) {
27+
enabledIntegrations.forEach((integrationKey) => {
28+
const matchedEvent = integrations[integrationKey as AvailablePlugins].detectMatchingEvent(payloadBuilder);
29+
if (!matchedEvent) {
30+
return;
31+
}
32+
const matchingPluginEventMap = options[integrationKey as AvailablePlugins];
33+
const matchingEventSpecificationId = matchingPluginEventMap && matchingPluginEventMap[matchedEvent];
34+
if (!matchingEventSpecificationId) {
35+
return;
36+
}
37+
payloadBuilder.addContextEntity(createEventSpecificationContext(matchingEventSpecificationId));
38+
});
39+
},
40+
};
41+
}

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

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
import { PayloadBuilder } from '@snowplow/tracker-core';
2+
import { snowplowMediaPluginIntegration } from './snowplow-media-plugin';
3+
4+
export type AvailablePlugins = 'SnowplowMediaPlugin';
5+
6+
export type Integration = {
7+
/**
8+
* Find a matching event for the integration with a plugin and an event specification id map.
9+
* The returned string should match what we expect as key coming from the configuration object on this specific plugin integration.
10+
*/
11+
detectMatchingEvent: (payloadBuilder: PayloadBuilder) => string | undefined;
12+
};
13+
14+
export const integrations: Record<AvailablePlugins, Integration> = {
15+
SnowplowMediaPlugin: snowplowMediaPluginIntegration,
16+
} as const;

0 commit comments

Comments
 (0)