Skip to content

Getting Started with the WebXR SDK

Step 1: Sign up

If you don't already have a Cognitive3D organization, please sign up for free at our dashboard.

Step 2: Install the NPM package

npm install @cognitive3d/analytics

Step 3: Create a Settings File

To initialize the package properly, C3DAnalytics needs to be instantiated with settings.

We recommend creating a settings file that you can then import to your files:

//settings.js

export default {
  config: {
    APIKey: "ASDF1234ASDF", // Application Key is available on the dashboard
    gazeBatchSize: 64, // Number of Gaze snapshots stored in a batch before sending to server
    dynamicDataLimit: 64, // Number of Dynamic Object snapshots stored in a batch before sending to server
    customEventBatchSize: 64, // Number of Custom Event snapshots stored in a batch before sending to server
    sensorDataLimit: 64, // Number of Sensor snapshots stored in a batch before sending to server
    HMDType: "Meta Quest 3", // Defaut HMD Type set in Metadata for this project. You can overwrite this at run time via Metadata methods.
    allSceneData: [
      // Scene data can be found on the Dashboard
      {
        sceneName: "test_scene1",
        sceneId: "test_id1",
        versionNumber: "1",
      },
      {
        sceneName: "tutorial",
        sceneId: "b9d33399-1e13-428e-9559-7d15f28e9683",
        versionNumber: "3",
      },
    ],
  },
};

Step 4: Import plugin and settings

//app.js
import C3DAnalytics from "cognitive-3d-analytics/lib";
import mySettings from "./settings.js";

const c3d = new C3DAnalytics(mySettings);

Step 5: Add user metadata

c3d.userId = "myUserId"; // Required
c3d.setUserName("John Smith"); // A friendly name to label this user session

//User properties & metadata can be set using the following method: setUserProperty('property', 'value);
c3d.setUserProperty("Age", 21);
c3d.setUserProperty("SomeGroup", "someValue");
c3d.setUserProperty("HairColor", "Brown");

//Device specific properties work the same:
c3d.setDeviceName("Meta Quest 3");
c3d.setDeviceProperty("AppName", "myTestApp");

A full list of all device properties that can found on the metadata page.

Step 6: Start a Session

Choose which scene is currently active, and start the session:

c3d.setScene("test_scene1");

//add these 4 required property names to the session
c3d.setUserProperty("c3d.version", "0.1");
c3d.setUserProperty("c3d.app.version", "0.1");
c3d.setUserProperty("c3d.app.engine", "threejs");
c3d.setUserProperty("c3d.deviceid", "asdf-1234");

c3d.startSession();

Step 7: Record User Gaze

We provide a simple API to record users' Gaze data:

c3d.gaze.recordGaze(pos, rot, gaze, objectId /*optional*/);

// pos:      position array [x,y,z] of the the current position of the user. The HMD position in worldspace.
// rot:      quaternion rotation [x, y, z, w] of the user's head.
// gaze:     position array [x,y,z] in local object space where the user is gazing at
// objectId: objectId when gazing at a Dynamic Object. If this is not set, assumption is made that user is looking at some point on the static scene object.

In practice:

//app.js
import C3DAnalytics from 'cognitive-3d-analytics/lib'
import settings from './settings.js'

...

const c3d = new C3DAnalytics(settings);
c3d.setScene('test_scene1');
c3d.startSession();

const pos = [0, 0, 0];
const point = [0, 0, 1];
const rot = [0, 0, 0, 1];

c3d.gaze.recordGaze(pos, rot);
//or
c3d.gaze.recordGaze(pos, rot, point, 'object_id');

We support recording the user gaze at 10Hz (10 times per second).

For custom events, sensor data, and more features please see the feature tabs on the left.

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.