@device-router/probe

A ~1 KB (gzipped) client-side probe that collects device capability signals via browser APIs for DeviceRouter.

Installation

pnpm add @device-router/probe

How it works

The probe runs once per session in the browser. It collects device signals using standard browser APIs, then POSTs them to your server's probe endpoint. A session cookie prevents repeated collection.

Browser                                      Server
  │                                            │
  │  collectSignals()                          │
  │  getBattery()                              │
  │                                            │
  │  POST /device-router/probe                 │
  │  ─────────────────────────────────────>    │
  │  { hardwareConcurrency: 8,                 │
  │    deviceMemory: 8, ... }                  │
  │                                            │
  │  { sessionToken: "abc123" }                │
  │  <─────────────────────────────────────    │
  │                                            │
  │  Set cookie: device-router-session=abc123  │
  └────────────────────────────────────────────┘

Usage

Script tag (IIFE)

The simplest approach — include the pre-built bundle:

<script src="/device-router-probe.min.js"></script>

The probe auto-executes on load. Serve the file from dist/device-router-probe.min.js.

Auto-injection

Middleware packages can auto-inject the probe into HTML responses:

const { middleware, probeEndpoint, injectionMiddleware } = createDeviceRouter({
  storage,
  injectProbe: true,
});

Programmatic

import { runProbe } from '@device-router/probe';

await runProbe({
  endpoint: '/device-router/probe', // default
  cookieName: 'device-router-session', // default
  cookiePath: '/', // default
});

Programmatic with retry

import { runProbeWithRetry } from '@device-router/probe';

await runProbeWithRetry({
  endpoint: '/device-router/probe',
  retry: {
    maxRetries: 3, // default: 3
    baseDelay: 500, // default: 500ms
    maxDelay: 5000, // default: 5000ms
  },
});

Uses exponential backoff with jitter on network failure. Signals are collected once before the retry loop. Does not affect the IIFE bundle size.

Signals collected

| Signal | API | Browser Support | | ---------------------- | -------------------------- | ------------------- | | CPU cores | hardwareConcurrency | All modern browsers | | Device memory | deviceMemory | Chromium | | Connection info | navigator.connection | Chromium | | User agent | navigator.userAgent | All browsers | | Viewport dimensions | window.innerWidth/Height | All browsers | | Pixel ratio | devicePixelRatio | All browsers | | Prefers reduced motion | matchMedia | All modern browsers | | Color scheme | matchMedia | All modern browsers | | GPU renderer | WebGL debug info | Most browsers | | Battery status | navigator.getBattery() | Chromium |

All signals are optional — the probe gracefully degrades based on what the browser supports. Unavailable APIs are silently skipped.

Bundle size

The IIFE bundle is strictly capped at 1024 bytes gzipped. This is enforced at build time — the build fails if the limit is exceeded.

Exports

• runProbe(options?) — Run the probe (async, idempotent per session)
• collectSignals() — Collect all synchronous device signals
• ProbeSignals — Type for the collected signal object
• ProbeOptions — Configuration type for runProbe
• runProbeWithRetry(options?) — Run the probe with retry on failure
• RetryOptions — Retry configuration type
• ProbeWithRetryOptions — Configuration type for runProbeWithRetry

Individual collectors are also exported for selective use:

• collectHardwareConcurrency()
• collectDeviceMemory()
• collectConnection()
• collectUserAgent()
• collectViewport()
• collectPixelRatio()
• collectPrefersReducedMotion()
• collectPrefersColorScheme()
• collectGpuRenderer()

License

MIT