Skip to content

Plain JavaScript / No Framework

You can use the @cognitive3d/analytics SDK in any WebXR application without an engine adapter.

The core feature set — session management, automatic WebXR gaze tracking, custom events, sensors, exit polls, and all the properties APIs — works as soon as you hand the SDK your XRSession.

Requirements

  • Cognitive3D Account: You'll need an active Cognitive3D account to obtain your API keys and set up your project. You can sign up at the Cognitive3D platform website.

Note

You can quickly find your API keys on Cognitive3D with ctrl/cmd + K to pull up the search menu and then searching for Manage Developer Key. Note the difference between the Developer Key (Used for uploading assets to Cognitive3D) and the Application Key (Used in your Applications to allow your project to send data to our servers).

  • A WebXR-capable page that requests an XRSession — from raw WebXR APIs, an <a-scene>, or any framework we don't provide an adapter for.

Step 1: Install the Cognitive3D NPM Package

npm install @cognitive3d/analytics

If you're not using a bundler, the UMD build is also available at node_modules/@cognitive3d/analytics/lib/c3d.umd.js and can be loaded via a <script> tag. It exposes C3D as a global.

Step 2: Create a Settings Object

// settings.js
export default {
  config: {
    APIKey: "YOUR_APPLICATION_API_KEY",
    allSceneData: [
      {
        sceneName: "MyRawWebXRScene",
        sceneId: "",        // filled in after scene upload (if you have one)
        versionNumber: "1",
      },
    ],
  },
};

Step 3: Initialize the SDK

import C3D from "@cognitive3d/analytics";
import settings from "./settings";

const c3d = new C3D(settings);

// Required device / user properties when you're not using an engine adapter.
c3d.setDeviceProperty("AppEngine", "None"); // REQUIRED without an adapter
c3d.setUserProperty("c3d.app.version", "1.0"); // REQUIRED

c3d.setScene("MyRawWebXRScene");

Step 4: Start and End the Session

Pass the XRSession you obtain from navigator.xr.requestSession(...) to c3d.startSession(xrSession). Doing so enables the XR session manager, which handles gaze sampling, HMD orientation sensors, controller tracking, and boundary events automatically. If you call startSession() with no argument, only the non-XR parts of the SDK run.

// On enter-VR
const xrSession = await navigator.xr.requestSession("immersive-vr", {
    requiredFeatures: ["local-floor"],
    optionalFeatures: ["bounded-floor", "hand-tracking"],
});
await c3d.startSession(xrSession);

// ... your app runs ...

// On exit-VR
xrSession.addEventListener("end", () => {
    c3d.endSession().then(status => {
        console.log("Cognitive3D: session ended with status", status);
    });
});

Step 5: Record Data During the Session

// Custom event — name, 3D position, optional properties
c3d.customEvent.send("tutorial_step_completed", [0, 1, 0], { step: 3 });

// Sensor — name, numeric or boolean value
c3d.sensor.recordSensor("heartRate", 85);

See the Custom Events, Sensors, Exit Poll, and Properties pages for the full API.

Step 6: (Optional) Uploading a Scene

You can still ship your participants' sessions without a 3D scene attached — the data just won't be visualized against geometry in Session Replay. If you want a scene:

  1. Produce the four required files (scene.gltf, scene.bin, settings.json, screenshot.png) from your toolchain of choice — for example, a Blender export for a hand-authored environment.
  2. Upload via the Cognitive3D Upload Web App with your Developer Key.
  3. Paste the returned Scene ID and version into settings.allSceneData and re-run.

Supported Features

With the core SDK alone you get:

  • Session management (startSession, endSession, setScene).
  • Automatic WebXR gaze tracking, HMD orientation sensors, controller tracking, and boundary events (when you pass an XRSession).
  • Custom events, sensors, exit polls.
  • All session, user, device, and participant properties.

Not Available Without an Adapter

  • Engine-driven gaze (gazeTrackingSource: "engine") — the webxr source still works, but engine-based raycasting requires an adapter.
  • Per-object gaze raycasting and heatmaps.
  • Dynamic object transform tracking via isDynamic/c3dId userData scanning. (You can still drive the c3d.dynamicObject APIs manually if you're willing to manage registration and snapshots yourself.)
  • Automatic performance profiler (draw calls, memory, frame time) — this depends on an engine renderer with renderer.info.render.calls.
  • Scene and object export helpers.

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.