DOCS LLMs

SDK Telemetry & Version Adoption

SDK Telemetry & Version Adoption

How the dashboard's version-adoption and runtime-environment charts get their data, what the SDKs actually send, and the one mistake that turns this feature into a legal problem.

The pipeline

SDK (telemetry enabled)                LicenseSeat                Dashboard
┌──────────────────────┐   body     ┌──────────────┐   rows    ┌──────────┐
│ activate / validate  │──field────▶│ maps to      │──────────▶│ adoption │
│ / heartbeat carry a  │ "telemetry"│ footprint    │           │ + env    │
│ `telemetry` object   │            │ columns      │           │ charts   │
└──────────────────────┘            └──────────────┘           └──────────┘

The telemetry rides inside the request body of calls the SDK already makes — no extra requests, no separate analytics endpoint.

What is collected (exactly)

OS name and version · platform (native/web) · device type (desktop/phone/tablet/tv/watch) · CPU architecture and core count · memory (GB) · locale, language, timezone · SDK name and version · app_version and app_build (the two YOU supply).

What is never collected by telemetry: hostname, hardware serial numbers, raw hardware identifiers (fingerprint components are a separate, independently-gated setting), or any of your app's user content.

Enabling it

Telemetry is a client-side compile/config decision — the server accepts whatever arrives; blank fields simply leave blank columns.

  • Rust / Tauri: telemetry_enabled: true in the SDK/plugin config, and set app_version (e.g. from CARGO_PKG_VERSION) — without it the adoption chart has nothing to group by. app_build is a good place for a git sha. (Rust ≥ 0.6.1 reports real macOS OS version and memory; 0.6.0 sent "unknown"/blank for both on Macs — if a dashboard shows "macOS unknown", that's the SDK version, not a wiring bug.)
  • Swift: on by default (telemetryEnabled = true) — an app that wants it off must opt out explicitly. app_version/app_build auto-fill from the bundle's CFBundleShortVersionString/CFBundleVersion, overridable via appVersion/appBuild in the config for non-bundle hosts. Swift also reports device_model, screen_resolution, and display_scale — a superset of the Rust field list.
  • Other SDKs: the flag is named equivalently; the field list is identical.

Verify it works the same way you verify everything else — by looking at the data: after one activation from a telemetry-enabled build, the product's newest footprint rows should carry os_name, app_version, device_type. Blank columns with correct geo = telemetry disabled or an old build.

⚠️ The trap: your privacy policy is part of this feature

Telemetry ships environment data off the user's machine, and your privacy policy must say so before a telemetry-enabled build does. The failure mode is subtle and real: a privacy-first draft that proudly states "the licensing SDK's telemetry is disabled" becomes a live false statement the moment you flip the flag — and a knowingly false privacy claim impeaches the whole document.

The safe order, always:

  1. Amend the policy (enumerate the field list; keep your hard negatives — "no hostname, no serials" — they remain true).
  2. Publish the amended policy on your site.
  3. Then ship the first telemetry-enabled build.

Also remember the flip is per-BUILD: versions already installed never start sending. Adoption data begins with the first enabled release — which, pleasantly, means watching that release roll out through your own update feed is itself the first thing the adoption chart shows you.

For coding agents

  • Grep the client for the telemetry flag BEFORE promising dashboard charts; a privacy-era false is common and is a product decision plus a legal edit, not a bug fix.
  • Never flip the flag in the same change that ships a release; the policy gate is a hard sequencing constraint, not a formality.
  • The wire contract is one JSON object under the "telemetry" key in the body of activate/validate/heartbeat — if columns are blank server-side, diff what the client sends against the field list above.