Telemetry

Supported licensing requests can include an optional telemetry object with device and app information. LicenseSeat uses this enrichment to power per-product analytics: DAU/MAU, version adoption, platform distribution, geographic breakdown, and stale device detection.

Official SDKs may attach this enrichment automatically, according to their version and configuration. If you're building a custom integration, this page describes the telemetry format and what each field is used for.

The optional telemetry object is distinct from the data required to perform licensing. Successful licensing requests still create an activity footprint containing the event, license/product context, installation fingerprint when present, request time, and source IP even when optional telemetry is disabled.

The Telemetry Object

Include a telemetry key in the JSON body of any POST request:

{
  "license_key": "XXXX-XXXX-XXXX-XXXX",
  "fingerprint": "mac-a1b2c3d4-e5f6g7h8",
  "telemetry": {
    "sdk_name": "swift",
    "sdk_version": "0.4.2",
    "os_name": "macOS",
    "os_version": "15.2.0",
    "platform": "native",
    "device_model": "MacBookPro18,1",
    "app_version": "2.1.0",
    "app_build": "42",
    "device_type": "desktop",
    "architecture": "arm64",
    "cpu_cores": 10,
    "memory_gb": 32,
    "locale": "en_US",
    "language": "en",
    "timezone": "America/New_York",
    "screen_resolution": "3456x2234",
    "display_scale": 2.0
  }
}

Fields

Promoted Columns

These fields are stored as dedicated database columns and are directly queryable in the analytics dashboard:

Additional Metadata

These fields are stored in the JSONB metadata column:

All fields are optional. Send what you have -- partial telemetry is better than none.

Which Endpoints Accept Telemetry

Telemetry is captured on these endpoints:

Every successful request to these endpoints creates a footprint with the telemetry data, the request IP (for geolocation), and the event type. See the API quickstart and interactive reference for the complete endpoint contracts.

How the SDKs Handle It

Consult the SDK-specific configuration. Several official SDKs enable telemetry by default, but availability and opt-out controls differ by SDK version.

Swift SDK

Swift 0.4.2 includes telemetry by default on supported licensing POST requests. Disable the optional object explicitly when the host application does not need LicenseSeat analytics:

LicenseSeatStore.shared.configure(
    apiKey: "pk_live_xxxxxxxx",
    productSlug: "your-product"
) { config in
    config.telemetryEnabled = false
}

// When enabled, the optional telemetry object contains:

// What gets collected:
// - sdk_name: "swift"
// - sdk_version: from LicenseSeatConfig.sdkVersion
// - os_name: "macOS", "iOS", "tvOS", "watchOS", "visionOS"
// - os_version: from ProcessInfo.operatingSystemVersion
// - platform: "native"
// - device_model: from sysctlbyname("hw.model")
// - app_version: from CFBundleShortVersionString
// - app_build: from CFBundleVersion
// - device_type: "desktop", "phone", "tablet", "watch", "tv", "headset"
// - architecture: "arm64" or "x64"
// - cpu_cores: from ProcessInfo.processorCount
// - memory_gb: from ProcessInfo.physicalMemory (rounded)
// - locale: from Locale.current.identifier
// - language: 2-letter code from locale
// - timezone: from TimeZone.current.identifier
// - screen_resolution: native pixel resolution
// - display_scale: backingScaleFactor / UIScreen.scale

The Swift SDK also creates a random app-scoped installation identifier and persists it in Keychain on Apple platforms. It sends that required seat-binding value as the top-level fingerprint, independently of telemetryEnabled. Legacy clients may still use the device_id field name, but fingerprint is the canonical wire term.

Custom Integrations

If you're building a custom SDK or integration, collect whatever fields are available on your platform and include them in the telemetry object:

import platform
import requests

requests.post(
    "https://licenseseat.com/api/v1/products/my-app/licenses/validate",
    headers={"Authorization": "Bearer pk_live_xxx"},
    json={
        "license_key": "XXXX-XXXX-XXXX-XXXX",
        "fingerprint": get_device_fingerprint(),
        "telemetry": {
            "sdk_name": "python",
            "sdk_version": "0.1.0",
            "os_name": platform.system(),
            "os_version": platform.release(),
            "platform": "native",
            "device_type": "desktop",
            "architecture": platform.machine(),
            "app_version": "1.0.0"
        }
    }
)

var body = new {
    license_key = "XXXX-XXXX-XXXX-XXXX",
    fingerprint = GetDeviceFingerprint(),
    telemetry = new {
        sdk_name = "csharp",
        sdk_version = "0.5.0",
        os_name = Environment.OSVersion.Platform.ToString(),
        os_version = Environment.OSVersion.Version.ToString(),
        platform = "native",
        device_type = "desktop",
        architecture = RuntimeInformation.ProcessArchitecture.ToString(),
        app_version = Assembly.GetExecutingAssembly().GetName().Version.ToString()
    }
};

What Powers the Analytics Dashboard

The telemetry data feeds directly into your product's analytics dashboard in LicenseSeat. The dashboard offers 7, 30, and 90 day time range selectors.

KPI Cards

• DAU — Daily Active Users (unique devices today)
• MAU — Monthly Active Users (unique devices this month)
• Unique Devices — Over selected time range
• Total Events — All telemetry events in range

Charts & Distributions

LicenseSeat Section

Geolocation

In addition to the telemetry fields you send, LicenseSeat automatically resolves geolocation from the request IP address. This provides country, city, region, coordinates, and timezone -- no extra work needed from the SDK.

Privacy

You can omit the optional telemetry object; the API's licensing decisions work the same without that enrichment. This does not make a licensing request anonymous: license/product identifiers, an installation fingerprint when applicable, event timing, and the server-visible source IP are still required or recorded for service operation, abuse prevention, and licensing analytics.

Persistent identifiers, IP-derived location, request activity, and diagnostic attributes can be personal data or data linked to a user under platform policy and privacy law even when they do not contain a person's name. Integrators remain responsible for an accurate privacy notice, lawful basis/consent where required, retention and deletion behavior, and their complete App Store or marketplace disclosures. Disabling optional telemetry alone does not establish GDPR or other legal compliance.