@reykjavik/webtools 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -4,6 +4,17 @@
 
 - ... <!-- Add new lines here. -->
 
+## 0.1.7
+
+_2023-04-19_
+
+- `@reykjavik/webtools/next/SiteImprove`:
+  - feat: Auto-track outbound link clicks, also for late-injected elements.
+  - feat: Add `pingSiteImproveOutbound` helper
+  - fix: Strip pageview ref URLs on history back/forward traversal
+- `@reykjavik/webtools/next/http`
+  - fix: Make `ErrorProps` accept `HTTP_ERROR_ALL`
+
 ## 0.1.0 – 0.1.6
 
 _2023-03-24_

package/README.md

@@ -29,7 +29,7 @@ yarn add @reykjavik/webtools
 - [`@reykjavik/webtools/next/SiteImprove`](#reykjavikwebtoolsnextsiteimprove)
   - [`SiteImprove` component](#siteimprove-component)
   - [`pingSiteImprove` helper](#pingsiteimprove-helper)
-- [Changelog](#changelog)
+  - [`pingSiteImproveOutbound` helper](#pingsiteimproveoutbound-helper)
 
 <!-- prettier-ignore-start -->
 
@@ -399,6 +399,8 @@ applications and perform custom event tracking.
 A component for loading a SiteImprove analytics script and set up page-view
 tracking across Next.js routes.
 
+It also automatically logs all out-öbound link clicks.
+
 ```js
 import { SiteImprove } from '@reykjavik/webtools/next/SiteImprove';
 
@@ -446,7 +448,26 @@ const handleSubmit = () => {
 };
 ```
 
-In dev mode it only logs tracking events to the console.
+### `pingSiteImproveOutbound` helper
+
+**Syntax:** `pingSiteImproveOutbound(ourl: string): void`
+
+A small helper for reporting to SiteImrove when the user is programmatically
+being sent to a different URL/resource.
+
+```js
+import { pingSiteImproveOutbound } from '@reykjavik/webtools/next/SiteImprove';
+
+const handleSubmit = () => {
+  // perform submit action...
+  if (success) {
+    const fileUrl ='/download/report.pdf'
+    pingSiteImproveOutbound(fileUrl);
+    document.location.href = fileUrl
+  }
+};
+
+
 
 ---
 
@@ -454,3 +475,4 @@ In dev mode it only logs tracking events to the console.
 
 See
 [CHANGELOG.md](https://github.com/reykjavikcity/webtools/blob/main/CHANGELOG.md)
+```

package/esm/next/SiteImprove.d.ts

@@ -9,21 +9,34 @@ declare global {
              * just-in-time.
              */
             _jit_defined_?: true;
+            core?: {
+                data: Array<SiteImproveEvent>;
+            };
         };
     }
 }
-type SiteImproveEvent = SiteImprovePageView | SiteImproveCustomEvent;
+type SiteImproveEvent = SiteImprovePageView | SiteImproveRequest | SiteImproveCustomEvent;
 type SiteImprovePageView = [
     type: 'trackdynamic',
     data: {
         /** New page URL */
         url: string;
         /** The previous (referer) URL */
-        ref: string;
+        ref?: string;
         /** New page title */
         title?: string;
     }
 ];
+type SiteImproveRequest = [
+    type: 'request',
+    data: {
+        /** Outbound URL */
+        ourl: string;
+        /** The current page URL */
+        ref: string;
+        autoonclick?: 1;
+    }
+];
 type SiteImproveCustomEvent = [
     type: 'event',
     category: string,
@@ -78,4 +91,11 @@ export declare const SiteImprove: (props: SiteImproveProps) => JSX.Element | nul
  * @see https://github.com/reykjavikcity/webtools/tree/v0.1##pingsiteimprove-helper
  */
 export declare const pingSiteImprove: (category: string, action: string, label?: string) => void;
+/**
+ * A small helper for reporting to SiteImrove when the user is programmatically
+ * being sent to a different URL/resource.
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1##pingsiteimproveoutbound-helper
+ */
+export declare const pingSiteImproveOutbound: (ourl: string) => void;
 export {};

package/esm/next/SiteImprove.js

@@ -1,6 +1,6 @@
 import React, { useEffect } from 'react';
-import { Router } from 'next/router';
-import Script from 'next/script';
+import { Router } from 'next/router.js';
+import Script from 'next/script.js';
 import { useCookieHubConsent } from '../CookieHubConsent.js';
 // END: Mock typing of SiteImprove's event tracking API
 // --------------------------------------------------------------------------
@@ -40,11 +40,44 @@ const sendRoutingEvent = (url) => _emitEvent([
     'trackdynamic',
     {
         url,
-        ref: refUrl,
+        // On `history.back()`/`history.forward()` the URL change happens before
+        // `routeChangeStart`, so `refUrl` and `url` become the same.
+        // in that case we suppress the `ref`
+        ref: refUrl !== url ? refUrl : undefined,
         title: document.title,
     },
 ]);
 // ---------------------------------------------------------------------------
+const logOutboundLinks = () => {
+    const captureLinkClicks = (e) => {
+        const link = e.target.closest('a[href]');
+        if (!link || link.$$bound) {
+            return;
+        }
+        link.$$bound = true;
+        // Waiting for the bubble phase allows other click handlers to preventDefault()
+        link.addEventListener('click', (e) => {
+            var _a, _b;
+            if (e.defaultPrevented) {
+                return;
+            }
+            // Skip logging outbound request if SiteImprove has already done so.
+            // BTW, SiteImprove binds its autoonclick handlers on "mousedown"
+            // so they're guaranteed to have run before our "click" listener.
+            const events = (_b = (_a = window._sz) === null || _a === void 0 ? void 0 : _a.core) === null || _b === void 0 ? void 0 : _b.data;
+            const [type, data] = (events && events[events.length - 1]) || [];
+            if (type === 'request' && data.autoonclick && data.ourl === link.href) {
+                return;
+            }
+            pingSiteImproveOutbound(link.href);
+        });
+    };
+    const { body } = document;
+    // bind 'click' listener to the capture phase
+    body.addEventListener('click', captureLinkClicks, true);
+    return () => body.removeEventListener('click', captureLinkClicks, true);
+};
+// ---------------------------------------------------------------------------
 const idToken = '[ACCOUNT_ID]';
 const scriptUrlTemplate = `https://siteimproveanalytics.com/js/siteanalyze_${idToken}.js`;
 /**
@@ -70,9 +103,11 @@ export const SiteImprove = (props) => {
             const routerEvents = Router.events;
             routerEvents.on('routeChangeStart', captureRefUrl);
             routerEvents.on('routeChangeComplete', sendRoutingEvent);
+            const stopLoggingOutboundLinks = logOutboundLinks();
             return () => {
                 routerEvents.off('routeChangeStart', captureRefUrl);
                 routerEvents.off('routeChangeComplete', sendRoutingEvent);
+                stopLoggingOutboundLinks();
             };
         }
     }, 
@@ -95,7 +130,21 @@ export const SiteImprove = (props) => {
 export const pingSiteImprove = (category, action, label) => {
     if (process.env.NODE_ENV === 'development' &&
         (!window._sz || window._sz._jit_defined_)) {
-        console.warn('`pingSiteImprove` Was called before SiteImprove script was loaded.');
+        console.warn('`pingSiteImprove` was called before SiteImprove script was loaded.');
     }
     _emitEvent(['event', category, action, label]);
 };
+// ---------------------------------------------------------------------------
+/**
+ * A small helper for reporting to SiteImrove when the user is programmatically
+ * being sent to a different URL/resource.
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1##pingsiteimproveoutbound-helper
+ */
+export const pingSiteImproveOutbound = (ourl) => {
+    if (process.env.NODE_ENV === 'development' &&
+        (!window._sz || window._sz._jit_defined_)) {
+        console.warn('`pingSiteImproveOutbound` was called before SiteImprove script was loaded.');
+    }
+    _emitEvent(['request', { ourl, ref: document.location.href }]);
+};

package/esm/next/http.d.ts

@@ -2,21 +2,20 @@
 import React, { FunctionComponent } from 'react';
 import { Cleanup } from '@reykjavik/hanna-utils';
 import { ServerResponse } from 'http';
-import type { AppType } from 'next/app';
-import type { HTTP_418_ImATeapot, HTTP_ERROR, TTLConfig } from '../http.js';
-type HTTP_ERROR_all = HTTP_ERROR | typeof HTTP_418_ImATeapot;
+import type { AppType } from 'next/app.js';
+import type { HTTP_ERROR_ALL, TTLConfig } from '../http.js';
 export * from '../http.js';
 type NextContextLike = {
     res: ServerResponse;
 };
 export type ErrorProps = {
-    statusCode: HTTP_ERROR_all;
+    statusCode: HTTP_ERROR_ALL;
     message?: string;
 };
 type ErrorizedPageProps<EP extends ErrorProps = ErrorProps> = {
     __error: ErrorProps;
 } & Omit<EP, keyof ErrorProps>;
-type ShowErrorPageFn<EP extends ErrorProps = ErrorProps> = (response: ServerResponse | NextContextLike, error: (ErrorProps extends EP ? HTTP_ERROR_all : never) | EP, 
+type ShowErrorPageFn<EP extends ErrorProps = ErrorProps> = (response: ServerResponse | NextContextLike, error: (ErrorProps extends EP ? HTTP_ERROR_ALL : never) | EP, 
 /** Defaults to `"2s"`. Gets forwarded on to the `cacheControl` helper from `@reykjavik/webtools/http` */
 ttl?: TTLConfig) => {
     props: ErrorizedPageProps<EP>;

package/next/SiteImprove.d.ts

@@ -9,21 +9,34 @@ declare global {
              * just-in-time.
              */
             _jit_defined_?: true;
+            core?: {
+                data: Array<SiteImproveEvent>;
+            };
         };
     }
 }
-type SiteImproveEvent = SiteImprovePageView | SiteImproveCustomEvent;
+type SiteImproveEvent = SiteImprovePageView | SiteImproveRequest | SiteImproveCustomEvent;
 type SiteImprovePageView = [
     type: 'trackdynamic',
     data: {
         /** New page URL */
         url: string;
         /** The previous (referer) URL */
-        ref: string;
+        ref?: string;
         /** New page title */
         title?: string;
     }
 ];
+type SiteImproveRequest = [
+    type: 'request',
+    data: {
+        /** Outbound URL */
+        ourl: string;
+        /** The current page URL */
+        ref: string;
+        autoonclick?: 1;
+    }
+];
 type SiteImproveCustomEvent = [
     type: 'event',
     category: string,
@@ -78,4 +91,11 @@ export declare const SiteImprove: (props: SiteImproveProps) => JSX.Element | nul
  * @see https://github.com/reykjavikcity/webtools/tree/v0.1##pingsiteimprove-helper
  */
 export declare const pingSiteImprove: (category: string, action: string, label?: string) => void;
+/**
+ * A small helper for reporting to SiteImrove when the user is programmatically
+ * being sent to a different URL/resource.
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1##pingsiteimproveoutbound-helper
+ */
+export declare const pingSiteImproveOutbound: (ourl: string) => void;
 export {};

package/next/SiteImprove.js

@@ -26,10 +26,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.pingSiteImprove = exports.SiteImprove = void 0;
+exports.pingSiteImproveOutbound = exports.pingSiteImprove = exports.SiteImprove = void 0;
 const react_1 = __importStar(require("react"));
-const router_1 = require("next/router");
-const script_1 = __importDefault(require("next/script"));
+const router_js_1 = require("next/router.js");
+const script_js_1 = __importDefault(require("next/script.js"));
 const CookieHubConsent_js_1 = require("../CookieHubConsent.js");
 // END: Mock typing of SiteImprove's event tracking API
 // --------------------------------------------------------------------------
@@ -69,11 +69,44 @@ const sendRoutingEvent = (url) => _emitEvent([
     'trackdynamic',
     {
         url,
-        ref: refUrl,
+        // On `history.back()`/`history.forward()` the URL change happens before
+        // `routeChangeStart`, so `refUrl` and `url` become the same.
+        // in that case we suppress the `ref`
+        ref: refUrl !== url ? refUrl : undefined,
         title: document.title,
     },
 ]);
 // ---------------------------------------------------------------------------
+const logOutboundLinks = () => {
+    const captureLinkClicks = (e) => {
+        const link = e.target.closest('a[href]');
+        if (!link || link.$$bound) {
+            return;
+        }
+        link.$$bound = true;
+        // Waiting for the bubble phase allows other click handlers to preventDefault()
+        link.addEventListener('click', (e) => {
+            var _a, _b;
+            if (e.defaultPrevented) {
+                return;
+            }
+            // Skip logging outbound request if SiteImprove has already done so.
+            // BTW, SiteImprove binds its autoonclick handlers on "mousedown"
+            // so they're guaranteed to have run before our "click" listener.
+            const events = (_b = (_a = window._sz) === null || _a === void 0 ? void 0 : _a.core) === null || _b === void 0 ? void 0 : _b.data;
+            const [type, data] = (events && events[events.length - 1]) || [];
+            if (type === 'request' && data.autoonclick && data.ourl === link.href) {
+                return;
+            }
+            (0, exports.pingSiteImproveOutbound)(link.href);
+        });
+    };
+    const { body } = document;
+    // bind 'click' listener to the capture phase
+    body.addEventListener('click', captureLinkClicks, true);
+    return () => body.removeEventListener('click', captureLinkClicks, true);
+};
+// ---------------------------------------------------------------------------
 const idToken = '[ACCOUNT_ID]';
 const scriptUrlTemplate = `https://siteimproveanalytics.com/js/siteanalyze_${idToken}.js`;
 /**
@@ -96,12 +129,14 @@ const SiteImprove = (props) => {
                     }, 300);
                 }
             }
-            const routerEvents = router_1.Router.events;
+            const routerEvents = router_js_1.Router.events;
             routerEvents.on('routeChangeStart', captureRefUrl);
             routerEvents.on('routeChangeComplete', sendRoutingEvent);
+            const stopLoggingOutboundLinks = logOutboundLinks();
             return () => {
                 routerEvents.off('routeChangeStart', captureRefUrl);
                 routerEvents.off('routeChangeComplete', sendRoutingEvent);
+                stopLoggingOutboundLinks();
             };
         }
     }, 
@@ -113,7 +148,7 @@ const SiteImprove = (props) => {
     const scriptUrl = props.scriptUrl != null
         ? props.scriptUrl
         : scriptUrlTemplate.replace(idToken, props.accountId);
-    return (react_1.default.createElement(script_1.default, { type: "text/javascript", strategy: "afterInteractive", src: scriptUrl, onLoad: props.onLoad, onError: props.onError }));
+    return (react_1.default.createElement(script_js_1.default, { type: "text/javascript", strategy: "afterInteractive", src: scriptUrl, onLoad: props.onLoad, onError: props.onError }));
 };
 exports.SiteImprove = SiteImprove;
 // ---------------------------------------------------------------------------
@@ -125,8 +160,23 @@ exports.SiteImprove = SiteImprove;
 const pingSiteImprove = (category, action, label) => {
     if (process.env.NODE_ENV === 'development' &&
         (!window._sz || window._sz._jit_defined_)) {
-        console.warn('`pingSiteImprove` Was called before SiteImprove script was loaded.');
+        console.warn('`pingSiteImprove` was called before SiteImprove script was loaded.');
     }
     _emitEvent(['event', category, action, label]);
 };
 exports.pingSiteImprove = pingSiteImprove;
+// ---------------------------------------------------------------------------
+/**
+ * A small helper for reporting to SiteImrove when the user is programmatically
+ * being sent to a different URL/resource.
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1##pingsiteimproveoutbound-helper
+ */
+const pingSiteImproveOutbound = (ourl) => {
+    if (process.env.NODE_ENV === 'development' &&
+        (!window._sz || window._sz._jit_defined_)) {
+        console.warn('`pingSiteImproveOutbound` was called before SiteImprove script was loaded.');
+    }
+    _emitEvent(['request', { ourl, ref: document.location.href }]);
+};
+exports.pingSiteImproveOutbound = pingSiteImproveOutbound;

package/next/http.d.ts

@@ -2,21 +2,20 @@
 import React, { FunctionComponent } from 'react';
 import { Cleanup } from '@reykjavik/hanna-utils';
 import { ServerResponse } from 'http';
-import type { AppType } from 'next/app';
-import type { HTTP_418_ImATeapot, HTTP_ERROR, TTLConfig } from '../http.js';
-type HTTP_ERROR_all = HTTP_ERROR | typeof HTTP_418_ImATeapot;
+import type { AppType } from 'next/app.js';
+import type { HTTP_ERROR_ALL, TTLConfig } from '../http.js';
 export * from '../http.js';
 type NextContextLike = {
     res: ServerResponse;
 };
 export type ErrorProps = {
-    statusCode: HTTP_ERROR_all;
+    statusCode: HTTP_ERROR_ALL;
     message?: string;
 };
 type ErrorizedPageProps<EP extends ErrorProps = ErrorProps> = {
     __error: ErrorProps;
 } & Omit<EP, keyof ErrorProps>;
-type ShowErrorPageFn<EP extends ErrorProps = ErrorProps> = (response: ServerResponse | NextContextLike, error: (ErrorProps extends EP ? HTTP_ERROR_all : never) | EP, 
+type ShowErrorPageFn<EP extends ErrorProps = ErrorProps> = (response: ServerResponse | NextContextLike, error: (ErrorProps extends EP ? HTTP_ERROR_ALL : never) | EP, 
 /** Defaults to `"2s"`. Gets forwarded on to the `cacheControl` helper from `@reykjavik/webtools/http` */
 ttl?: TTLConfig) => {
     props: ErrorizedPageProps<EP>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@reykjavik/webtools",
-	"version": "0.1.6",
+	"version": "0.1.7",
 	"description": "Misc. JS/TS helpers used by Reykjavík City's web dev teams.",
 	"main": "index.js",
 	"repository": "ssh://git@github.com:reykjavikcity/webtools.git",