@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

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')

initialize() is synchronous because the SDK is statically imported.

Usage — config only (lazy / inert loaders)

Sites that lazy-load the SDK themselves (to stay inert when telemetry is unconfigured) can import just the config — no SDK is pulled in:

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()

API

| Export | Description | | --- | --- | | useTelemetry(options?) | Full composable: initialize, trackEvent, trackPageView, trackCtaClick, trackException, trackMetric, trackDependency, flush, startTrackPage, stopTrackPage, plus isEnabled / isInitialized / initializationError refs. | | createTelemetryConfig(options?) | Builds the App Insights config with DCS defaults + the disablePageUnloadEvents: ['unload'] fix. Pure, no SDK import. | | DEFAULT_DISABLE_PAGE_UNLOAD_EVENTS | ['unload'] — the disabled-events default. | | DEFAULT_CLOUD_ROLE | 'dcs-site'. | | types | TelemetryOptions, TelemetryConfigOptions, ApplicationInsightsConfig, TelemetryEvent, TelemetryPageView, TelemetryException, TelemetryDependency, TelemetryMetric. |

TelemetryOptions

| Option | Default | Notes | | --- | --- | --- | | connectionString / instrumentationKey | — | at least one enables telemetry | | cloudRole | 'dcs-site' | ai.cloud.role + app_name property | | appVersion | window.__APP_VERSION__ ?? 'unknown' | stamped on every event | | environment | 'unknown' | e.g. import.meta.env.MODE | | dev | false | verbose SDK logging when true | | enableAutoRouteTracking | true | SDK built-in SPA route tracking | | disablePageUnloadEvents | ['unload'] | the fix — override only if you know why | | overrides | — | deep Partial<ApplicationInsightsConfig>, applied last |

License

MIT © Duff Cloud Services