diff --git a/common/changes/@snowplow/browser-plugin-privacy-sandbox/feature-add-privacy-sandbox-plugin_2023-06-14-20-26.json b/common/changes/@snowplow/browser-plugin-privacy-sandbox/feature-add-privacy-sandbox-plugin_2023-06-14-20-26.json new file mode 100644 index 000000000..7d163ead2 --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/common/config/rush/pnpm-lock.yaml b/common/config/rush/pnpm-lock.yaml index f56229ef6..4af07a5d3 100644 --- a/common/config/rush/pnpm-lock.yaml +++ b/common/config/rush/pnpm-lock.yaml @@ -1070,6 +1070,55 @@ importers: ts-jest: 27.1.3_60149d457e34ffba7d4e845dde6a1263 typescript: 4.6.2 + ../../plugins/browser-plugin-privacy-sandbox: + specifiers: + '@ampproject/rollup-plugin-closure-compiler': ~0.27.0 + '@rollup/plugin-commonjs': ~21.0.2 + '@rollup/plugin-node-resolve': ~13.1.3 + '@snowplow/browser-tracker-core': workspace:* + '@snowplow/tracker-core': workspace:* + '@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 + tslib: ^2.3.1 + typescript: ~4.6.2 + dependencies: + '@snowplow/browser-tracker-core': link:../../libraries/browser-tracker-core + '@snowplow/tracker-core': link:../../libraries/tracker-core + tslib: 2.3.1 + devDependencies: + '@ampproject/rollup-plugin-closure-compiler': 0.27.0_rollup@2.70.1 + '@rollup/plugin-commonjs': 21.0.2_rollup@2.70.1 + '@rollup/plugin-node-resolve': 13.1.3_rollup@2.70.1 + '@types/jest': 27.4.1 + '@types/jsdom': 16.2.14 + '@typescript-eslint/eslint-plugin': 5.15.0_f2c49ce7d0e93ebcfdb4b7d25b131b28 + '@typescript-eslint/parser': 5.15.0_eslint@8.11.0+typescript@4.6.2 + eslint: 8.11.0 + jest: 27.5.1 + jest-environment-jsdom: 27.5.1 + jest-environment-jsdom-global: 3.0.0_jest-environment-jsdom@27.5.1 + jest-standard-reporter: 2.0.0 + rollup: 2.70.1 + rollup-plugin-cleanup: 3.2.1_rollup@2.70.1 + rollup-plugin-license: 2.6.1_rollup@2.70.1 + rollup-plugin-terser: 7.0.2_rollup@2.70.1 + rollup-plugin-ts: 2.0.5_rollup@2.70.1+typescript@4.6.2 + ts-jest: 27.1.3_60149d457e34ffba7d4e845dde6a1263 + typescript: 4.6.2 + ../../plugins/browser-plugin-site-tracking: specifiers: '@ampproject/rollup-plugin-closure-compiler': ~0.27.0 diff --git a/common/config/rush/repo-state.json b/common/config/rush/repo-state.json index 7fbe4955b..bd6f926e1 100644 --- a/common/config/rush/repo-state.json +++ b/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": "5484bd61ddb42855b5228699721d75c1d5b9cb25", + "pnpmShrinkwrapHash": "eefa4bd00b3696bf3bbfd5ad5c63a0a6b34f5fc4", "preferredVersionsHash": "bf21a9e8fbc5a3846fb05b4fa0859e0917b2202f" } diff --git a/plugins/browser-plugin-privacy-sandbox/LICENSE b/plugins/browser-plugin-privacy-sandbox/LICENSE new file mode 100644 index 000000000..b91bf94ae --- /dev/null +++ b/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. diff --git a/plugins/browser-plugin-privacy-sandbox/README.md b/plugins/browser-plugin-privacy-sandbox/README.md new file mode 100644 index 000000000..ec680e6e4 --- /dev/null +++ b/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 diff --git a/plugins/browser-plugin-privacy-sandbox/jest.config.js b/plugins/browser-plugin-privacy-sandbox/jest.config.js new file mode 100644 index 000000000..bd3ea4e2a --- /dev/null +++ b/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', +}; diff --git a/plugins/browser-plugin-privacy-sandbox/package.json b/plugins/browser-plugin-privacy-sandbox/package.json new file mode 100644 index 000000000..16c0a3e5b --- /dev/null +++ b/plugins/browser-plugin-privacy-sandbox/package.json @@ -0,0 +1,53 @@ +{ + "name": "@snowplow/browser-plugin-privacy-sandbox", + "version": "3.12.0", + "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.12.0" + } +} diff --git a/plugins/browser-plugin-privacy-sandbox/rollup.config.js b/plugins/browser-plugin-privacy-sandbox/rollup.config.js new file mode 100644 index 000000000..6c968d34c --- /dev/null +++ b/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 }], + }, +]; diff --git a/plugins/browser-plugin-privacy-sandbox/src/index.ts b/plugins/browser-plugin-privacy-sandbox/src/index.ts new file mode 100644 index 000000000..fc65f8b65 --- /dev/null +++ b/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; + } +} + +/** + * 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 } }] : []; + }, + }; +} diff --git a/plugins/browser-plugin-privacy-sandbox/src/schemata.ts b/plugins/browser-plugin-privacy-sandbox/src/schemata.ts new file mode 100644 index 000000000..e759a94b0 --- /dev/null +++ b/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'; diff --git a/plugins/browser-plugin-privacy-sandbox/src/types.ts b/plugins/browser-plugin-privacy-sandbox/src/types.ts new file mode 100644 index 000000000..41ca0f1a7 --- /dev/null +++ b/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; + +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; +}; diff --git a/plugins/browser-plugin-privacy-sandbox/test/__snapshots__/privacy-sandbox.test.ts.snap b/plugins/browser-plugin-privacy-sandbox/test/__snapshots__/privacy-sandbox.test.ts.snap new file mode 100644 index 000000000..8b7bbd864 --- /dev/null +++ b/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", +} +`; diff --git a/plugins/browser-plugin-privacy-sandbox/test/privacy-sandbox.test.ts b/plugins/browser-plugin-privacy-sandbox/test/privacy-sandbox.test.ts new file mode 100644 index 000000000..7324ecdee --- /dev/null +++ b/plugins/browser-plugin-privacy-sandbox/test/privacy-sandbox.test.ts @@ -0,0 +1,98 @@ +import { buildLinkClick, trackerCore } from '@snowplow/tracker-core'; +import { JSDOM } from 'jsdom'; +import { PrivacySandboxPlugin } from '../src'; +import { BrowserTracker } from '@snowplow/browser-tracker-core'; +import { setImmediate } from 'timers'; + +declare var jsdom: JSDOM; + +describe('Privacy Sandbox plugin', () => { + it('Returns values for Privacy Sandbox properties', async () => { + const sampleTopicEntry = { + topic: 1, + taxonomyVersion: '1', + version: 'chrome.1:1:1', + modelVersion: '1', + configurationVersion: '1', + }; + + Object.defineProperties(jsdom.window.document, { + browsingTopics: { + value: () => { + return Promise.resolve([sampleTopicEntry]); + }, + configurable: true, + }, + featurePolicy: { + value: { + allowsFeature: (feature: string) => feature === 'browsing-topics', + }, + configurable: true, + }, + }); + + const plugin = PrivacySandboxPlugin(); + + const core = trackerCore({ + corePlugins: [plugin], + callback: (payloadBuilder) => { + const json = payloadBuilder.getJson().filter((e) => e.keyIfEncoded === 'cx'); + expect(json[0].json).toMatchSnapshot(); + }, + }); + + plugin.activateBrowserPlugin?.({ core } as BrowserTracker); + + const flushPromises = () => new Promise(setImmediate); + await flushPromises(); + + core.track(buildLinkClick({ targetUrl: 'https://example.com' })); + }); + + it('Returns no values when feature policy "browsing-topics" is off', async () => { + const sampleTopicEntry = { + topic: 1, + taxonomyVersion: '1', + version: 'chrome.1:1:1', + modelVersion: '1', + configurationVersion: '1', + }; + + Object.defineProperties(jsdom.window.document, { + browsingTopics: { + value: () => { + return Promise.resolve([sampleTopicEntry]); + }, + configurable: true, + }, + featurePolicy: { + value: { + allowsFeature: function (feature: string) { + if (feature === 'browsing-topics') { + return false; + } + return true; + }, + }, + configurable: true, + }, + }); + + const plugin = PrivacySandboxPlugin(); + + const core = trackerCore({ + corePlugins: [plugin], + callback: (payloadBuilder) => { + const json = payloadBuilder.getJson().filter((e) => e.keyIfEncoded === 'cx'); + expect(json[0]?.json).toMatchSnapshot(); + }, + }); + + plugin.activateBrowserPlugin?.({ core } as BrowserTracker); + + const flushPromises = () => new Promise(setImmediate); + await flushPromises(); + + core.track(buildLinkClick({ targetUrl: 'https://example.com' })); + }); +}); diff --git a/plugins/browser-plugin-privacy-sandbox/tsconfig.json b/plugins/browser-plugin-privacy-sandbox/tsconfig.json new file mode 100644 index 000000000..4082f16a5 --- /dev/null +++ b/plugins/browser-plugin-privacy-sandbox/tsconfig.json @@ -0,0 +1,3 @@ +{ + "extends": "../../tsconfig.json" +} diff --git a/rush.json b/rush.json index 796a51882..48348a769 100644 --- a/rush.json +++ b/rush.json @@ -553,6 +553,12 @@ "projectFolder": "plugins/browser-plugin-media", "reviewCategory": "plugins", "versionPolicyName": "tracker" + }, + { + "packageName": "@snowplow/browser-plugin-privacy-sandbox", + "projectFolder": "plugins/browser-plugin-privacy-sandbox", + "reviewCategory": "plugins", + "versionPolicyName": "tracker" } ] }