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: truein the SDK/plugin config, and setapp_version(e.g. fromCARGO_PKG_VERSION) — without it the adoption chart has nothing to group by.app_buildis 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_buildauto-fill from the bundle'sCFBundleShortVersionString/CFBundleVersion, overridable viaappVersion/appBuildin the config for non-bundle hosts. Swift also reportsdevice_model,screen_resolution, anddisplay_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:
- Amend the policy (enumerate the field list; keep your hard negatives — "no hostname, no serials" — they remain true).
- Publish the amended policy on your site.
- 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
falseis 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.