@duffcloudservices/telemetry

@duffcloudservices/telemetry

Shared Azure Application Insights telemetry for DCS Vue sites. One place owns the App Insights config and the useTelemetry composable, so every DCS surface (marketing web/, generated customer sites) gets the same behavior — including the fleet-wide bfcache / Lighthouse unload fix.

Why this package exists

The App Insights JavaScript SDK, by default, registers a listener on the deprecated unload event. That:

• makes pages ineligible for the browser back/forward cache (bfcache), and
• trips the Lighthouse "avoid unload event listeners" best-practices audit (~19 points — enough to pin flagship sites at Best-Practices 54).

The fix is a single config field — disablePageUnloadEvents: ['unload'] — which tells the SDK to skip the unload hook while still flushing telemetry on pagehide / visibilitychange (the supported path). This package bakes that into the default config so no consumer can forget it.

Install

pnpm add @duffcloudservices/telemetry
# peers you already have on a DCS Vue site:
pnpm add @microsoft/applicationinsights-web vue

The SDK loads lazily — adoption does not move it onto your entry chunk

Importing useTelemetry costs your entry chunk nothing but this package's own code (~6–7KB raw / ~2KB gzip minified). The ~192KB raw / ~78KB gzip App Insights web SDK is reached through a dynamic import() inside initialize(), so your bundler emits it as its own async chunk, fetched only when initialize() runs.

This is not a micro-optimisation, it is the reason the package is adoptable. Before 0.3.0 the composable imported the SDK statically. Measured on a live customer site (bryans-handyman-solutions, 2026-08-11), adopting 0.2.1 in place of the site's hand-rolled lazy composable moved the whole SDK onto the entry chunk:

Total transferred JS barely moved in the middle row — the SDK simply relocated onto the critical path and defeated the site's deliberate requestIdleCallback deferral.

Laziness costs you no telemetry:

• Calls made during the load are buffered, with their call-time properties, and replayed in order once the SDK lands (bounded at 100 calls). A landing pageView or a boot-time trackException is not lost.
• initialize() is still synchronous and still returns boolean — "telemetry is enabled and the SDK load has started". Nothing about the call site changes.
• Concurrent initialize() callers share one load and one SDK instance.
• whenReady(): Promise<boolean> is available for the rare caller that must sequence work after the SDK exists. You should not need it to avoid losing events.

Usage — composable (SPA / eager)

The connection string, cloud role, environment and app version are supplied by the consumer (read your own import.meta.env / build defines and pass plain values in), keeping this package portable.

import { useTelemetry } from '@duffcloudservices/telemetry'

const telemetry = useTelemetry({
  connectionString: import.meta.env.VITE_APP_INSIGHTS_CONNECTION_STRING,
  instrumentationKey: import.meta.env.VITE_APP_INSIGHTS_INSTRUMENT_KEY,
  cloudRole: 'dcs-web',
  dev: import.meta.env.DEV,
  environment: import.meta.env.MODE,
  appVersion: __APP_VERSION__,
})

telemetry.initialize() // synchronous; no-op (with a loud one-shot warn) when unconfigured
telemetry.trackCtaClick('hero-cta', '/contact') // buffered if the SDK is still loading

// Only when you must sequence work after the SDK itself exists:
void telemetry.whenReady().then(() => telemetry.trackPageView())

initialize() returns boolean synchronously — the SDK loads in the background (see above). Events fired before it lands are buffered, not dropped, so the common case needs no await at all.

Migrating from a site-local composable? The site versions were async initialize(): Promise<boolean>, so void initialize().then(…) must become initialize(); void whenReady().then(…). TypeScript flags the old form (Property 'then' does not exist on type 'boolean'), so this cannot slip through a site's type-check.

Usage — config only (lazy / inert loaders)

useTelemetry already loads the SDK lazily, so most sites no longer need this. It remains for consumers that construct the SDK themselves — a bespoke boot, or a non-Vue surface — and want the shared config without the composable:

import { createTelemetryConfig } from '@duffcloudservices/telemetry/config'

const { ApplicationInsights } = await import('@microsoft/applicationinsights-web')
const ai = new ApplicationInsights({
  config: createTelemetryConfig({ connectionString: cs, enableAutoRouteTracking: false }),
})
ai.loadAppInsights()

Usage — visitor journey on form submissions

A stored form submission and the site's telemetry describe the same visit, but nothing joins them. getJourneyContext() returns the join key: the App Insights visitor/session ids, the submit-time page, and the session's first-touch referrer / landing path / utm_*.

First-touch is snapshotted into sessionStorage by initialize(), not read at submit time — document.referrer is destroyed the moment a client-side router takes over, so capture-at-submit is structurally empty for exactly the multi-page journeys worth attributing.

The module imports nothing, so a consumer with its own telemetry boot can use it SDK-free:

import {
  captureJourneyFirstTouch,
  toJourneyTelemetryPayload,
} from '@duffcloudservices/telemetry/journey'

captureJourneyFirstTouch()          // once, at app boot, before any navigation

const telemetry = toJourneyTelemetryPayload()   // undefined when nothing to report
if (telemetry) payload.telemetry = telemetry    // omit the field, never send {}

A telemetry failure must never cost a lead. Every entry point swallows its own errors and degrades to an empty result; senders wrap the call and omit the field entirely rather than block a submission.

API

TelemetryOptions

License

MIT © Duff Cloud Services