Skip to content

Properties

Every session the SDK records is annotated with a set of properties — metadata about the user, their device, the session, and any research / experimental context. Properties are how you filter, segment, and compare sessions on the Cognitive3D dashboard. This page documents the property APIs for the WebXR SDK as a whole; each framework integration uses the same APIs.

User Identification

Identifying users is key to tracking behavior across multiple sessions and applications. None of these are required, but at least one of them should be set for any session you want to correlate with a specific person or participant.

User ID — a unique, persistent identifier you control.

// The SDK also automatically captures a fingerprinted device id (c3d.deviceid)
// for cross-session analysis; that fingerprint isn't guaranteed to be stable
// across devices or browsers, so a user id is more reliable.
c3d.userId = "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6";

Participant Full Name — a friendly, human-readable label shown on the dashboard.

c3d.setParticipantFullName("John Smith");

Participant ID — a cross-session identifier for research participants.

c3d.setParticipantId("p-alpha-42");

Custom Participant Properties — keys are automatically prefixed with c3d.participant. and are intended for research or cohort tracking.

c3d.setParticipantProperty("cohort", "GroupA");

c3d.setParticipantProperties({
    experimental_group: "Trained",
    pre_test_score: 85,
});

Session Properties

Session properties describe a single session. Under the hood, they ride out with the gaze stream and are only re-sent if their value changes. If you set the same key multiple times during a session, the dashboard reflects the most recent value.

Session Name — a descriptive label useful for A/B testing or identifying specific playthroughs.

c3d.setSessionName("Onboarding Tutorial - Version B");

Lobby ID — for multiplayer / shared spaces, groups every participant who was in the same lobby.

c3d.setLobbyId("Lobby-Alpha-42");

Session Tag — a short boolean tag (max 12 characters) attached to the session. Useful for quick filtering.

c3d.setSessionTag("beta");            // c3d.sessiontag.beta = true
c3d.setSessionTag("tutorial", false); // explicit value

Arbitrary Session Properties — any key/value pair scoped to the current session.

c3d.setSessionProperty("difficulty", "hard");
c3d.setSessionProperty({
    map_seed: 42,
    run_mode: "timed",
});

Custom User Properties

Attach arbitrary key/value data to the user (as opposed to the session). Useful for demographics, progression, or experimental groups.

// Key is a string; value can be a string, number, or boolean.
c3d.setUserProperty("Age", 34);
c3d.setUserProperty("PlayerClass", "Mage");
c3d.setUserProperty("HasCompletedTutorial", true);

// Set several at once
c3d.setUserProperty({
    PlayerClass: "Mage",
    Level: 12,
});

Device Properties

The SDK infers a lot of device information automatically (see Standard Properties below), but you can add your own or override.

// A friendly name for the headset / device being used
c3d.setDeviceName("My Custom VR Rig");

// Explicit device-scoped properties
c3d.setDeviceProperty("AppName", "VR-Training-Sim");
c3d.setDeviceProperty("AppVersion", "2.1.0");

// Bulk set
c3d.setDeviceProperty({
    AppName: "VR-Training-Sim",
    AppVersion: "2.1.0",
});

Note

c3d.setUserProperty("c3d.app.version", "1.0") is required for every session. If you don't use an engine adapter, c3d.setDeviceProperty("AppEngine", "None") is also required.

Retrieving Properties

At runtime you can read back what's currently attached to the session:

const userProps   = c3d.getUserProperties();    // { PlayerClass: "Mage", ... }
const deviceProps = c3d.getDeviceProperties();  // { c3d.app.engine: "Three.js", ... }

Standard (Automatic) Properties

The SDK attempts to retrieve or infer the following automatically:

  • AppEngine and AppEngineVersion (set by the active adapter — Three.js, Babylon.js, PlayCanvas, Wonderland Engine, Mattercraft)
  • AvailableDeviceCPUCores, DeviceMemory
  • Boundary Type (Stationary / Room Scale)
  • DeviceType, DeviceModel, DeviceOS, DevicePlatform
  • DeviceID (FingerprintJS visitor id) and DeviceID Confidence
  • DeviceCPU, DeviceCPUVendor, DeviceGPU, DeviceGPUVendor
  • DeviceScreenWidth, DeviceScreenHeight
  • NetworkEffectiveType, NetworkDownlink, NetworkRTT
  • Room Size (area in m²) and Room Dimensions (length × width)
  • VRModel and VRVendor (inferred from the XR input sources)
  • EyeTracking, HandTracking (enabled based on the WebXR session features requested)

The analytics pipeline classifies these raw device properties into canonical device fields for filtering and reporting — see Device classification fields.

intercom 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.