Add WebView plugin (#1402)

mscwilson · mscwilson · commit 8192744c588a · 2025-01-20T11:43:28.000Z
* Add plugin based on my local webview tracker

* Use webview tracker symlink

* Correctly parse base64-encoded payloads

* Parse string numbers

* Add namespaces config option

* Remove unused callback

* Add docstring

* Fix self-desc events

* Use actual webview tracker

* Run rush change
diff --git a/common/changes/@snowplow/browser-plugin-webview/issue-webview_plugin_2025-01-16-14-44.json b/common/changes/@snowplow/browser-plugin-webview/issue-webview_plugin_2025-01-16-14-44.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/browser-plugin-webview",
+      "comment": "Add WebView plugin (#1402)",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/browser-plugin-webview"
+}
diff --git a/common/config/rush/browser-approved-packages.json b/common/config/rush/browser-approved-packages.json
@@ -166,6 +166,10 @@
       "name": "@snowplow/tracker-core",
       "allowedCategories": [ "libraries", "plugins", "trackers" ]
     },
+    {
+      "name": "@snowplow/webview-tracker",
+      "allowedCategories": [ "plugins" ]
+    },
     {
       "name": "@testing-library/dom",
       "allowedCategories": [ "libraries" ]
diff --git a/common/config/rush/pnpm-lock.yaml b/common/config/rush/pnpm-lock.yaml
diff --git 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": "d1933251824ef3eb837586f089856ce0f6036111",
+  "pnpmShrinkwrapHash": "bf29537a7fb7a501d796ce47e6bdb37daa9b0507",
   "preferredVersionsHash": "bf21a9e8fbc5a3846fb05b4fa0859e0917b2202f"
 }
diff --git a/plugins/browser-plugin-webview/CHANGELOG.json b/plugins/browser-plugin-webview/CHANGELOG.json
@@ -0,0 +1,5 @@
+{
+  "name": "@snowplow/browser-plugin-webview",
+  "entries": [
+  ]
+}
diff --git a/plugins/browser-plugin-webview/LICENSE b/plugins/browser-plugin-webview/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.
diff --git a/plugins/browser-plugin-webview/README.md b/plugins/browser-plugin-webview/README.md
@@ -0,0 +1,59 @@
+# Snowplow WebView Plugin
+
+[![npm version][npm-image]][npm-url]
+[![License][license-image]](LICENSE)
+
+Browser Plugin to be used with `@snowplow/browser-tracker`.
+
+This plugin is for use in WebViews. It forwards the events to the Snowplow Android, iOS, or React Native trackers via the [Snowplow WebView tracker](https://github.com/snowplow-incubator/snowplow-webview-tracker).
+
+## Maintainer quick start
+
+Part of the Snowplow JavaScript Tracker monorepo.
+Build with [Node.js](https://nodejs.org/en/) (18 - 20) 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-webview
+```
+
+## Usage
+
+Initialize your tracker with the `WebViewPlugin`:
+
+```js
+import { newTracker } from '@snowplow/browser-tracker';
+import { WebViewPlugin } from '@snowplow/browser-plugin-webview';
+
+newTracker('sp1', '{{collector_url}}', {
+   appId: 'my-app-id',
+   plugins: [ WebViewPlugin() ],
+});
+```
+
+For a full API reference, you can read the plugin [documentation page](https://docs.snowplow.io/docs/collecting-data/collecting-from-own-applications/javascript-trackers/browser-tracker/browser-tracker-v3-reference/plugins/webview/).
+
+## 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-webview
+[npm-image]: https://img.shields.io/npm/v/@snowplow/browser-plugin-webview
+[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-webview
diff --git a/plugins/browser-plugin-webview/jest.config.js b/plugins/browser-plugin-webview/jest.config.js
@@ -0,0 +1,6 @@
+module.exports = {
+  preset: 'ts-jest',
+  reporters: ['jest-standard-reporter'],
+  setupFilesAfterEnv: ['../../setupTestGlobals.ts'],
+  testEnvironment: 'jest-environment-jsdom-global',
+};
diff --git a/plugins/browser-plugin-webview/package.json b/plugins/browser-plugin-webview/package.json
@@ -0,0 +1,54 @@
+{
+  "name": "@snowplow/browser-plugin-webview",
+  "version": "4.1.0",
+  "description": "Automatically forwards events to Snowplow mobile trackers running in a WebView.",
+  "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",
+    "@snowplow/webview-tracker": "^0.3.0"
+  },
+  "devDependencies": {
+    "@ampproject/rollup-plugin-closure-compiler": "~0.27.0",
+    "@rollup/plugin-commonjs": "~21.0.2",
+    "@rollup/plugin-node-resolve": "~13.1.3",
+    "@types/jest": "~28.1.1",
+    "@types/jsdom": "~16.2.14",
+    "@typescript-eslint/eslint-plugin": "~5.15.0",
+    "@typescript-eslint/parser": "~5.15.0",
+    "eslint": "~8.11.0",
+    "jest": "~28.1.3",
+    "jest-environment-jsdom": "~28.1.3",
+    "jest-environment-jsdom-global": "~4.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": "~28.0.8",
+    "typescript": "~4.6.2"
+  },
+  "peerDependencies": {
+    "@snowplow/browser-tracker": "~4.0.1"
+  }
+}
diff --git a/plugins/browser-plugin-webview/rollup.config.js b/plugins/browser-plugin-webview/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 = 'snowplowWebViewTracking';
+
+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-webview/src/index.ts b/plugins/browser-plugin-webview/src/index.ts
@@ -0,0 +1,79 @@
+import { BrowserPlugin, Payload } from '@snowplow/browser-tracker-core';
+import { hasMobileInterface, trackWebViewEvent } from '@snowplow/webview-tracker';
+import { Logger, SelfDescribingEvent, SelfDescribingJson } from '@snowplow/tracker-core';
+import { base64urldecode } from './utils';
+
+type WebViewPluginOptions = {
+  /**
+   * Provide a list of tracker namespaces to forward events to.
+   * By default, the events will be forwarded to the default mobile tracker.
+   */
+  trackerNamespaces?: string[];
+};
+
+/**
+ * Forwards events to Snowplow mobile trackers running in a WebView.
+ * @param configuration - Configuration. Specify certain tracker namespaces to forward events to.
+ */
+export function WebViewPlugin(configuration?: WebViewPluginOptions): BrowserPlugin {
+  let LOG: Logger;
+
+  return {
+    logger: (logger: Logger) => {
+      LOG = logger;
+    },
+
+    filter: (payload) => {
+      if (hasMobileInterface() === true) {
+        LOG.debug(`Payload (event ID: ${payload.eid}) was filtered out and forwarded to WebView tracker.`);
+
+        let atomicProperties = {
+          eventName: payload.e as string,
+          trackerVersion: payload.tv as string,
+          useragent: (payload.ua as string) ?? window.navigator.userAgent,
+          url: payload.url as string | undefined,
+          title: payload.page as string | undefined,
+          referrer: payload.refr as string | undefined,
+          category: payload.se_ca as string | undefined,
+          action: payload.se_ac as string | undefined,
+          label: payload.se_la as string | undefined,
+          property: payload.se_pr as string | undefined,
+          value: payload.se_va !== undefined ? parseFloat(payload.se_va as string) : undefined,
+          minXOffset: payload.pp_mix !== undefined ? parseInt(payload.pp_mix as string) : undefined,
+          maxXOffset: payload.pp_max !== undefined ? parseInt(payload.pp_max as string) : undefined,
+          minYOffset: payload.pp_miy !== undefined ? parseInt(payload.pp_miy as string) : undefined,
+          maxYOffset: payload.pp_may !== undefined ? parseInt(payload.pp_may as string) : undefined,
+        };
+        let event = getSelfDescribingEventData(payload);
+        let entities = getEntities(payload);
+        let trackers: Array<string> | undefined = configuration?.trackerNamespaces;
+
+        trackWebViewEvent({ properties: atomicProperties, event: event, context: entities }, trackers);
+
+        return false;
+      } else {
+        return true;
+      }
+    },
+  };
+}
+
+function getSelfDescribingEventData(payload: Payload): SelfDescribingEvent | undefined {
+  if (payload.ue_pr) {
+    return JSON.parse(payload.ue_pr as string).data;
+  } else if (payload.ue_px) {
+    let decoded = base64urldecode(payload.ue_px as string);
+    return JSON.parse(decoded).data;
+  }
+  return undefined;
+}
+
+function getEntities(payload: Payload): SelfDescribingJson[] {
+  if (payload.co) {
+    return JSON.parse(payload.co as string)['data'];
+  } else if (payload.cx) {
+    let decoded = base64urldecode(payload.cx as string);
+    return JSON.parse(decoded)['data'];
+  }
+  return [];
+}
diff --git a/plugins/browser-plugin-webview/src/utils.ts b/plugins/browser-plugin-webview/src/utils.ts
diff --git a/plugins/browser-plugin-webview/test/webview.test.ts b/plugins/browser-plugin-webview/test/webview.test.ts
diff --git a/plugins/browser-plugin-webview/tsconfig.json b/plugins/browser-plugin-webview/tsconfig.json
diff --git a/rush.json b/rush.json

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`// DO NOT MODIFY THIS FILE MANUALLY BUT DO COMMIT IT. It is generated and used by Rush.`
`2`	`2`	`{`
`3`		`- "pnpmShrinkwrapHash": "d1933251824ef3eb837586f089856ce0f6036111",`
	`3`	`+ "pnpmShrinkwrapHash": "bf29537a7fb7a501d796ce47e6bdb37daa9b0507",`
`4`	`4`	`"preferredVersionsHash": "bf21a9e8fbc5a3846fb05b4fa0859e0917b2202f"`
`5`	`5`	`}`
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +{
 +  "name": "@snowplow/browser-plugin-webview",
 +  "entries": [
 +  ]
 +}