Device Classification Fields

Cognitive3D classifies every session's device in the analytics pipeline — not in the SDK — so classifications are consistent across engines, correctable without app updates, and improve retroactively as rules evolve. Cognitive3D SDKs report raw device signals; the pipeline's Device Resolution Service maps them onto a canonical taxonomy and stamps each session with derived fields.

The following diagram shows how device data flows from your app to the API and dashboard:

All derived fields are session properties under the reserved namespace c3d.device.derived.*. Raw SDK signals remain unprefixed under c3d.device.* — session endpoints return both; use the derived fields for analytics and filtering, and raw signals only when you need the original values the device reported.

Fields whose value cannot be determined behave as follows:

• category, family, and runtime_host are always present on classified sessions, falling back to unknown.
• model_family is unknown when the device belongs to a family whose generation could not be resolved, and omitted entirely for families without generational classification.
• model is omitted whenever the exact SKU cannot be determined.
• Absence of the whole c3d.device.derived.* namespace means the session predates enrichment.

category — closed vocabulary

hmd · glasses · mobile · tablet · desktop · console · emulator · unknown

Hardware and runtime are deliberately orthogonal: a session from a Quest headset's 2D web browser is category: hmd with runtime_host: web_browser — the device is what it physically is, regardless of how the app runs on it.

The same headset produces different runtime_host values depending on how the app runs:

runtime_host — closed vocabulary

native_standalone · native_tethered · native_mobile · native_desktop · web_browser · webxr · editor · unknown

webxr means an immersive WebXR session; web_browser means non-immersive web content. editor covers engine editors, simulators, and emulators.

Open vs closed vocabularies

The closed vocabularies above only change with a taxonomy version bump — new values will be announced. The open vocabularies (family, model_family, model) grow additively as new devices ship; do not build integrations that reject unrecognized values.

taxonomy_version

Classifications are versioned. When classification rules change materially, the version increments and newly processed sessions carry the new number; historical sessions retain the version that produced them until reprocessed. Use it to interpret mixed-version data during transitions.

To see the latest taxonomy version active for your project, read it from your most recent session's properties. Authenticate with your organization API key:

curl -s -X POST "https://api.cognitive3d.com/v0/datasets/sessions/paginatedListQueries" \
  -H "Authorization: YOUR_ORGANIZATION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sessionType":"project","entityFilters":{"projectId":YOUR_PROJECT_ID},
       "page":0,"limit":1,"sort":"desc",
       "orderBy":{"fieldName":"date","fieldParent":"session"}}' \
  | jq '.results[0].properties["c3d.device.derived.taxonomy_version"]'

Querying the fields

Session endpoints

Session endpoints (e.g. POST /v0/datasets/sessions/singleProjectSessionQueries) return the derived fields inside the session's properties object alongside all other session properties — no special handling needed.

Analytics queries

Analytics (slicer) queries filter and aggregate the derived fields as textual or numerical session properties. This example counts sessions from headsets, grouped by device family:

{
  "sessionType": "project",
  "entityFilters": { "projectId": 123 },
  "sessionFilters": [
    { "field": { "fieldParent": "session", "nestedFieldName": "textualSessionProp",
                 "path": "c3d.device.derived.category" },
      "op": "eq", "value": "hmd" }
  ],
  "aggregations": [
    { "name": "by_family", "outputType": "json0_key_y",
      "operations": [{ "name": "sessions", "type": "sessionCount" }],
      "sliceBys": [{ "name": "x", "maxTerms": 32,
        "field": { "fieldParent": "session", "nestedFieldName": "textualSessionProp",
                   "path": "c3d.device.derived.family" } }] }
  ]
}

Use numericalSessionProp for taxonomy_version and memory_gb.

Legacy c3d.device.type

The legacy c3d.device.type property (Desktop / Mobile) is now computed from the canonical classification and dual-written for backward compatibility. It is deprecated: prefer c3d.device.derived.category, which distinguishes headsets, glasses, tablets, consoles, and emulators that the legacy two-value field cannot. Existing integrations reading c3d.device.type keep working during the deprecation window; a retirement review is scheduled for 2026-12-12, and no removal will happen without advance notice.

Internal diagnostic properties

Session responses may include c3d.device.derived._rule.* properties recording which classification rule produced each field. These are internal diagnostics: undocumented, unversioned, and subject to change without notice — do not build on them.

Seeing a device that isn't classified?

If sessions from a device you care about come back with category: unknown or a missing model_family, tell us — new headsets, glasses, and browsers ship constantly, and adding a classification rule is fast once we can see the device's signals. Reach us through the in-app Intercom chat or the Cognitive3D Discord, ideally with a session ID from the device in question, and we'll add it to the taxonomy.

If you have a question or any feedback about our documentation please use the Intercom button (purple circle) in the lower right corner of any web page or join our Discord.