@v.ersions/analytics v1.0.0.0

Production-ready Versions Analytics overlay package for web applications.

Install

npm install @v.ersions/analytics

Initialize deterministic version manifest template (optional but recommended):

npx @v.ersions/analytics init

This creates public/versions.json with empty values if the file does not already exist.

React usage

import { VersionsAnalytics } from '@v.ersions/analytics'

<VersionsAnalytics applicationId="550e8400-e29b-41d4-a716-446655440000" />

Optional explicit React alias:

import { VersionsAnalyticsReact } from '@v.ersions/analytics'

<VersionsAnalyticsReact applicationId="550e8400-e29b-41d4-a716-446655440000" />

Function API

import { initVersionsAnalytics } from '@v.ersions/analytics'

initVersionsAnalytics({
  applicationId: '550e8400-e29b-41d4-a716-446655440000',
})

Optional auth helpers for host apps:

initVersionsAnalytics({
  applicationId: '550e8400-e29b-41d4-a716-446655440000',
  helperUrl: '/auth-helper',
  // Optional: only set if your app exposes this endpoint.
  accessTokenResolverUrl: '/api/auth/access-token',
})

Vue usage

The package exports a Vue component object:

import { VersionsAnalyticsVue } from '@v.ersions/analytics'

Functionality

• Token-gated UI rendering: overlay only renders when a valid analytics token is obtained.
• Hidden auth flow: the package resolves access token sources and performs the iframe handshake automatically.
• Auth helper handshake: requests analytics token using helperUrl flow and nonce validation.
• Visit registration: calls POST /api/analytics/authenticated with the analytics token and applicationId.
• Version badge rendering: shows returned version metadata in a compact badge.
• Floating overlay UI: renders a circular action button and a frosted modal panel.
• Safe cleanup: removes overlay UI and badge on component unmount or destroy().
• SSR safe: all browser-only behavior no-ops on server environments.

Defaults

• mode: defaults to auto.
• environment: defaults to preview.

Required input

Only applicationId is required for standard usage.

Version Identity (Important)

The overlay currently shows the latest known version for a system. That is useful, but it does not by itself prove that the browser is running that exact version.

To deterministically identify what the user is actually seeing, the runtime must expose a build identity that can be compared to what was registered from CI/CD.

Recommended model

Use two identifiers:

• releaseVersion: semantic version shown to users (for example 1.8.12).
• buildId: immutable deployment artifact identity (for example commit SHA, Next.js build ID, container image digest, or a generated release UUID).

Pipeline responsibilities:

• Increment/register releaseVersion.
• Register buildId and optional metadata (commit, branch, pipelineRunId, deployedAt).

Runtime responsibilities:

• Expose the same buildId to browser code (for example window.__VERSIONS_BUILD_ID__, <meta name="versions-build-id">, /version.json, or response header x-versions-build-id).
• Send buildId with analytics authenticated call.

Overlay behavior responsibilities:

• Display both:
  • "Latest registered" version
  • "Current runtime" build identity
• Evaluate state:
  • match: runtime build is the expected deployed build
  • drift: runtime build differs from latest registered/deployed build
  • unknown: runtime build identity missing

Why this works

• It avoids fragile file checksums over all post-build files.
• It does not depend on reading Git metadata at runtime.
• It is deterministic as long as the same immutable buildId is written by CI and exposed by the app.

What is not deterministic

• Comparing only semantic version labels.
• Inferring runtime version from "latest" registry state.
• Assuming CDN/browser caches always serve the newest assets.

Practical runtime exposure options

1. HTML-injected global variable: set window.__VERSIONS_BUILD_ID__ in server-rendered layout.
2. Version manifest endpoint: serve /version.json containing { releaseVersion, buildId, commit }.
3. Response header: include x-versions-build-id on document responses.

Option 1 plus Option 2 is usually easiest to validate and debug.

Notes

• For browser apps that use authenticated analytics flow, ensure /auth-helper and /api/analytics-token endpoints exist in the host app.
• accessTokenResolverUrl is optional and disabled by default. If your app does not implement /api/auth/access-token, no request is made.
• If token retrieval fails, the overlay remains hidden by design.

Troubleshooting

• Cross-domain iframe handshake: the helper page receives postMessage from the parent site. External parent origins are allowed when using https, while local development over http is limited to localhost and 127.0.0.1.
• Domain authorization: helper-origin acceptance is not the final auth boundary. Backend analytics-token still validates applicationId with allowedDomains.
• Useful logs:
  • [versions/analytics/handshake] ... in the parent page for iframe lifecycle and timeout diagnostics.
  • [auth-helper] ... in helper page for origin acceptance/rejection and token-postback steps.
  • [analytics-token] ... for route-level auth and upstream token exchange.

If you see Overlay creation skipped { hasVisitData: false }, check for a preceding handshake timeout or helper-origin rejection log first.