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 * as THREE from 'three';
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",
      },
    ],
  },
};

// --- Three.js Setup (Pre-XR) ---
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.xr.enabled = true;

// This group holds all dynamic (interactive/trackable) objects. The adapter will scan its children.
const interactableGroup = new THREE.Group();
scene.add(interactableGroup);

// --- C3D Initialization ---
// 2. INITIALIZE C3D ANALYTICS
// Pass the renderer to enable the built-in Performance Profiler
const c3d = new C3D(settings, renderer);

// 3. INITIALIZE THE THREE.JS ADAPTER
const c3dAdapter = new C3DThreeAdapter(c3d);

// 4. SET SCENE AND REQUIRED PROPERTIES
c3d.setScene('Scene1'); // Replace with your Scene Name
c3d.setUserProperty("c3d.app.version", "1.0"); // REQUIRED: Set your app's version

// 5. DEFINE YOUR ORIGINAL RENDER FUNCTION
// This function will be wrapped by the adapter's tracking logic.
const userRenderFn = (timestamp, frame) => {
    // Your application's original render logic goes here
    renderer.render(scene, camera);
};

// 6. HOOK INTO THE RENDER LOOP AND START TRACKING
renderer.xr.addEventListener('sessionstart', async () => {
    const xrSession = renderer.xr.getSession();

    // Start the C3D session (enables data streaming and unique device ID generation)
    await c3d.startSession(xrSession);

    // This call will:
    // a) Stops default FPS tracking and enables XR-synced FPS.
    // b) Sets up Gaze raycasting against objects in interactableGroup.
    // c) Finds and starts tracking all dynamic objects in interactableGroup.
    // d) Starts the animated render loop.
    c3dAdapter.startTracking(renderer, camera, interactableGroup, userRenderFn);

    console.log("Cognitive3D Session Started Successfully!");
});

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