Add PrivacySandboxPlugin (close #1205)

common/changes/@snowplow/browser-plugin-privacy-sandbox/feature-add-privacy-sandbox-plugin_2023-06-14-20-26.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/browser-plugin-privacy-sandbox",
+      "comment": "Introduce PrivacySandboxPlugin",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/browser-plugin-privacy-sandbox"
+}

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

@@ -114,6 +114,10 @@
       "name": "@snowplow/browser-plugin-performance-timing",
       "allowedCategories": [ "trackers" ]
     },
+    {
+      "name": "@snowplow/browser-plugin-privacy-sandbox",
+      "allowedCategories": [ "trackers" ]
+    },
     {
       "name": "@snowplow/browser-plugin-site-tracking",
       "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": "b3670fdd35939880fb5506b045e5826aeab84996",
+  "pnpmShrinkwrapHash": "9ed9fa735107bdc36f7a01ebbf09f656a122c028",
   "preferredVersionsHash": "bf21a9e8fbc5a3846fb05b4fa0859e0917b2202f"
 }

plugins/browser-plugin-privacy-sandbox/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2023 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-privacy-sandbox/README.md

@@ -0,0 +1,62 @@
+# Snowplow Privacy Sandbox Tracking
+
+[![npm version][npm-image]][npm-url]
+[![License][license-image]](LICENSE)
+
+Browser Plugin to be used with `@snowplow/browser-tracker`.
+
+Allows for adding Privacy Sandbox related data to your Snowplow tracking. To learn more about the Privacy Sandbox you can visit the official [website](https://www.privacysandbox.com/). As more and more APIs become available or further refined, we will be upgrading the plugin with more capabilities and options as more APIs are added to the Privacy Sandbox.
+
+Currently supported APIs:
+- [Topics API](https://developer.chrome.com/docs/privacy-sandbox/topics/overview/)
+
+
+__Note:__ Some of the APIs and data will not be available by default in all users. This is commonly due to these APIs being dependent on browser support, user privacy preferences, browser feature-flags or ad-blocking software. The plugin will not modify or request access explicitly to any of these features if not available by default.
+
+## 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-privacy-sandbox
+```
+
+## Usage
+
+Initialize your tracker with the PrivacySandboxPlugin:
+
+```js
+import { newTracker } from '@snowplow/browser-tracker';
+import { PrivacySandboxPlugin } from '@snowplow/browser-plugin-privacy-sandbox';
+
+newTracker('sp1', '{{collector}}', { plugins: [ PrivacySandboxPlugin() ] }); 
+```
+
+With the plugin added to your tracker, a new context will be attached to every event, when Privacy Sandbox [Topics](https://developer.chrome.com/docs/privacy-sandbox/topics/overview/) are detected for a user.
+
+## Copyright and license
+
+Licensed and distributed under the [BSD 3-Clause License](LICENSE) ([An OSI Approved License][osi]).
+
+Copyright (c) 2023 Snowplow Analytics Ltd.
+
+All rights reserved.
+
+[npm-url]: https://www.npmjs.com/package/@snowplow/browser-plugin-privacy-sandbox
+[npm-image]: https://img.shields.io/npm/v/@snowplow/browser-plugin-privacy-sandbox
+[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-privacy-sandbox

plugins/browser-plugin-privacy-sandbox/jest.config.js

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

plugins/browser-plugin-privacy-sandbox/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@snowplow/browser-plugin-privacy-sandbox",
+  "version": "3.13.1",
+  "description": "Allows for the collection of Privacy Sandbox specific data.",
+  "homepage": "https://docs.snowplow.io/",
+  "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": "Peter Perlepes",
+  "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.13.1"
+  }
+}

plugins/browser-plugin-privacy-sandbox/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 = 'snowplowPrivacySandbox';
+
+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-privacy-sandbox/src/index.ts

@@ -0,0 +1,43 @@
+import { BrowserPlugin } from '@snowplow/browser-tracker-core';
+import { PRIVACY_SANDBOX_TOPICS_SCHEMA } from './schemata';
+import { LOG } from '@snowplow/tracker-core';
+import { BrowsingTopicsOptions, PrivacySandboxTopic, Topic } from './types';
+
+declare global {
+  interface Document {
+    /* Declare Feature Policy types https://developer.mozilla.org/en-US/docs/Web/API/FeaturePolicy */
+    featurePolicy?: {
+      allowsFeature: (feature: string, origin?: string) => boolean;
+    };
+    browsingTopics: (options: BrowsingTopicsOptions) => Promise<PrivacySandboxTopic[]>;
+  }
+}
+
+/**
+ * Adds Privacy Sandbox Topics context to events
+ */
+export function PrivacySandboxPlugin(): BrowserPlugin {
+  let topics: Topic[] = [];
+
+  return {
+    activateBrowserPlugin: function () {
+      const isTopicsApiAvailable =
+        'browsingTopics' in document && document.featurePolicy?.allowsFeature('browsing-topics');
+
+      if (isTopicsApiAvailable) {
+        document
+          .browsingTopics({ skipObservation: true })
+          .then((availableTopics) => {
+            topics = availableTopics.map(({ topic, version }) => ({
+              topic,
+              version,
+            }));
+          })
+          .catch((err) => LOG.error(err));
+      }
+    },
+    contexts: function () {
+      return topics.length ? [{ schema: PRIVACY_SANDBOX_TOPICS_SCHEMA, data: { topics } }] : [];
+    },
+  };
+}

plugins/browser-plugin-privacy-sandbox/src/schemata.ts

@@ -0,0 +1 @@
+export const PRIVACY_SANDBOX_TOPICS_SCHEMA = 'iglu:com.google.privacysandbox/topics/jsonschema/1-0-0';

plugins/browser-plugin-privacy-sandbox/src/types.ts

@@ -0,0 +1,14 @@
+export type PrivacySandboxTopic = {
+  configVersion: string;
+  modelVersion: string;
+  taxonomyVersion: string;
+  topic: number;
+  version: string;
+};
+
+export type Topic = Pick<PrivacySandboxTopic, 'topic' | 'version'>;
+
+export type BrowsingTopicsOptions = {
+  /* Enabling will not cause the current page to be included in the weekly epoch calculation or update the list of topics observed for the caller. */
+  skipObservation?: boolean;
+};

plugins/browser-plugin-privacy-sandbox/test/__snapshots__/privacy-sandbox.test.ts.snap

@@ -0,0 +1,22 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Privacy Sandbox plugin Returns no values when feature policy "browsing-topics" is off 1`] = `undefined`;
+
+exports[`Privacy Sandbox plugin Returns values for Privacy Sandbox properties 1`] = `
+Object {
+  "data": Array [
+    Object {
+      "data": Object {
+        "topics": Array [
+          Object {
+            "topic": 1,
+            "version": "chrome.1:1:1",
+          },
+        ],
+      },
+      "schema": "iglu:com.google.privacysandbox/topics/jsonschema/1-0-0",
+    },
+  ],
+  "schema": "iglu:com.snowplowanalytics.snowplow/contexts/jsonschema/1-0-0",
+}
+`;