Skip to content

Getting Started with the WebXR SDK

Requirement(s)

  • Cognitive3D Account: You'll need an active Cognitive3D account to obtain your API key and set up your project. You can sign up on the Cognitive3D website.
  • Node.js 20.0+: This SDK requires Node.js version 20.0 or higher to ensure compatibility with modern JavaScript features and optimal performance. To check your current version: node --version

Install the NPM package

npm install @cognitive3d/analytics

Using the SDK

Scenes are used to contain recorded session data. For instructions to create a Scene and generating a SceneId, see the Scenes page.

To initialize the package properly, C3DAnalytics needs to be instantiated with settings. This following example is assuming you are using threeJS as your framework/engine.

Sample Code

// MyApp.js 
import C3D from '@cognitive3d/analytics'; // main sdk 
import C3DThreeAdapter from "@cognitive3d/analytics/adapters/threejs"; // threejs adapter  

// 1. CONFIGURE YOUR SETTINGS
const settings = {
  config: {
    APIKey: "YOUR_API_KEY_HERE", // Application Key, we recommend storing this key in a .env file 
    allSceneData: [
      // Your scene data can be found on the Dashboard
      {
        sceneName: "Scene1",
        sceneId: "SCENE_ID_1",
        versionNumber: "1",
      },
    ],
  },
};

// 2. INITIALIZE C3D ANALYTICS
// Pass the renderer to enable automatic performance profiling
const c3d = new C3D(settings /*, renderer */);

// 3. INITIALIZE THE THREE.JS ADAPTER
// This enables engine-specific features
const c3dAdapter = new C3DThreeAdapter(c3d);

// 4. SET SCENE AND REQUIRED PROPERTIES
c3d.setScene('Scene1'); // Replace with your Scene Name
c3d.setUserProperty("c3d.app.version", "0.2"); // REQUIRED: Set your app's version
c3d.setUserProperty("c3d.deviceid", 'threejs_windows_device_' + Date.now()); // REQUIRED: Set a unique device ID

// 5. START THE C3D SESSION
// The best practice is to tie the session to WebXR events
renderer.xr.addEventListener('sessionstart', async () => {
    const xrSession = renderer.xr.getSession();
    // Pass the XR session to enable automatic gaze tracking
    await c3d.startSession(xrSession);
    console.log("Cognitive3D Session Started Successfully!");
});

// 6. END THE C3D SESSION
// This ensures all remaining data is sent before the user leaves
renderer.xr.addEventListener('sessionend', () => {
    c3d.endSession();
    console.log("Cognitive3D Session Ended.");
});

Note: Ensure all properties are included as shown above, otherwise you may not see a valid session on the Cognitive3D dashboard. Check browser console for logs.

Next Steps

The WebXR SDK is designed to work with an engine/ framework, to dive further please read: Framework Support

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.