Create performance navigation timing plugin (close #1171)

common/changes/@snowplow/browser-plugin-performance-navigation-timing/feature-performance-navigation-timing-plugin_2023-04-13-08-08.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/browser-plugin-performance-navigation-timing",
+      "comment": "Introduce Performance Navigation Timing plugin",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/browser-plugin-performance-navigation-timing"
+}

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": "acc89ec01200ab3281ee1b0320ec90dfd66db4fa",
+  "pnpmShrinkwrapHash": "1b4af3f37be662be92115c24013c6b260e74acc8",
   "preferredVersionsHash": "bf21a9e8fbc5a3846fb05b4fa0859e0917b2202f"
 }

plugins/browser-plugin-performance-navigation-timing/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-performance-navigation-timing/README.md

@@ -0,0 +1,61 @@
+# Snowplow Performance Navigation Timing Tracking
+
+[![npm version][npm-image]][npm-url]
+[![License][license-image]](LICENSE)
+
+Browser Plugin to be used with `@snowplow/browser-tracker`.
+
+Adds Performance Navigation Timing contexts to your Snowplow tracking. To learn more about the properties tracked, you can visit the [specification](https://www.w3.org/TR/navigation-timing-2/) or MDN [documentation site](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceNavigationTiming).
+
+The following diagram shows the ResourceTiming and PerformanceNavigationTiming properties and how they connect to the navigation of the page main document.
+
+<figure>
+  <img src="./docs/performance_navigation_timeline.svg" alt="performance navigation timeline"/>
+  <figcaption>Performance navigation timeline from the <a href="https://www.w3.org/TR/navigation-timing-2/">W3C specification.</a></figcaption>
+</figure>
+
+## 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-performance-navigation-timing
+```
+
+## Usage
+
+Initialize your tracker with the PerformanceNavigationTimingPlugin:
+
+```js
+import { newTracker } from '@snowplow/browser-tracker';
+import { PerformanceNavigationTimingPlugin } from '@snowplow/browser-plugin-performance-navigation-timing';
+
+newTracker('sp1', '{{collector}}', { plugins: [ PerformanceNavigationTimingPlugin() ] }); 
+```
+
+## 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-performance-navigation-timing
+[npm-image]: https://img.shields.io/npm/v/@snowplow/browser-plugin-performance-navigation-timing
+[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-performance-navigation-timing

plugins/browser-plugin-performance-navigation-timing/jest.config.js

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

plugins/browser-plugin-performance-navigation-timing/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@snowplow/browser-plugin-performance-navigation-timing",
+  "version": "3.9.0",
+  "description": "Attaches Performance Navigation Timing data to Snowplow events",
+  "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.9.0"
+  }
+}

plugins/browser-plugin-performance-navigation-timing/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 = 'snowplowPerformanceNavigationTiming';
+
+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-performance-navigation-timing/src/contexts.ts

@@ -0,0 +1,100 @@
+import { PERFORMANCE_NAVIGATION_TIMING_SCHEMA } from './schemata';
+
+declare global {
+  interface Window {
+    mozPerformance: any;
+    msPerformance: any;
+    webkitPerformance: any;
+  }
+}
+
+type PerformanceNavigationTimingContext = PerformanceNavigationTiming & {
+  activationStart?: number;
+  deliveryType?: string;
+};
+
+/**
+ * Creates a context from the PerformanceNavigationTiming object
+ *
+ * @returns object PerformanceNavigationTiming context
+ */
+export function getPerformanceNavigationTimingContext() {
+  const performanceAlias =
+    window.performance || window.mozPerformance || window.msPerformance || window.webkitPerformance || {};
+
+  if (performanceAlias.getEntriesByType) {
+    const [performanceNavigationTiming] = performanceAlias.getEntriesByType('navigation') as [
+      PerformanceNavigationTiming
+    ];
+
+    if (!performanceNavigationTiming) {
+      return [];
+    }
+
+    return constructNavigationTimingContext(performanceNavigationTiming);
+  }
+
+  return [];
+}
+
+export function constructNavigationTimingContext(
+  performanceNavigationTimingInstance: PerformanceNavigationTimingContext
+) {
+  const performanceNavigationKeys = [
+    'entryType',
+    'duration',
+    'nextHopProtocol',
+    'workerStart',
+    'redirectStart',
+    'redirectEnd',
+    'fetchStart',
+    'domainLookupStart',
+    'domainLookupEnd',
+    'connectStart',
+    'secureConnectionStart',
+    'connectEnd',
+    'requestStart',
+    'responseStart',
+    'responseEnd',
+    'transferSize',
+    'encodedBodySize',
+    'decodedBodySize',
+    'serverTiming',
+    'unloadEventStart',
+    'unloadEventEnd',
+    'domInteractive',
+    'domContentLoadedEventStart',
+    'domContentLoadedEventEnd',
+    'domComplete',
+    'loadEventStart',
+    'loadEventEnd',
+    'type',
+    'redirectCount',
+    'activationStart',
+    'deliveryType',
+  ] as const;
+
+  const performanceContextData = performanceNavigationKeys.reduce((accum, key) => {
+    const performanceValue = performanceNavigationTimingInstance[key];
+    if (key === 'serverTiming' && Array.isArray(performanceValue)) {
+      accum[key] = performanceValue.length
+        ? performanceValue.map(({ description, duration, name }: PerformanceServerTiming) => ({
+            description,
+            duration,
+            name,
+          }))
+        : undefined;
+    } else if (performanceValue) {
+      accum[key] = performanceValue;
+    }
+
+    return accum;
+  }, {} as Record<typeof performanceNavigationKeys[number], unknown>);
+
+  return [
+    {
+      schema: PERFORMANCE_NAVIGATION_TIMING_SCHEMA,
+      data: performanceContextData,
+    },
+  ];
+}