Skip to content

Framework Support

Integrating with 3D Frameworks

The Cognitive3D WebXR SDK is designed to work with or without a specific 3D framework. However, to unlock the most features and simplify the integration process, we provide Adapters for popular WebXR engines.

Why Use an Adapter?

Using a framework-specific adapter offers several key advantages:

  • Automatic Data Collection: Adapters can automatically hook into your engine's render loop and scene graph to collect data.

  • Performance Profiling: Adapters enable the Built-in Performance Sensors to automatically track metrics.

  • Helper Functions: Adapters provide convenient helper functions, such as the ability to export your entire scene for upload to the Cognitive3D dashboard.

  • Engine-Specific Metadata: The SDK will automatically record which engine and version you are using.

Support Features

Feature ThreeJS PlayCanvas Wonderland Engine Babylon Plain Javascript
Core API (Session Properties, Custom Events, etc... ) ✅ ✅ ✅ ✅ ✅
Automatic WebXR Gaze Tracking ✅ ✅ ✅ ✅ ❌
Automatic Performance Sensors ✅ ✅ ❌ ❌ ❌
Object Export ✅ ❌ ❌ ❌ ❌
Scene Export ✅ ❌ ❌ ❌ ❌
Dynamic Objects ✅ ❌ ❌ ❌ ❌
Sample app provided ✅ ✅ ✅ ❌ ❌

Note: The WebXR SDK is currently in development and new features are always being work on. Therefore support for above may come later.

Integration

Three.js

The Three.js adapter provides automatic gaze tracking and a powerful scene export utility.

1. Installation

In your Three.js project's terminal, install the SDK from NPM.

npm install @cognitive3d/analytics

2. Initialization and Usage

Import both the main C3D class and the C3DThreeAdapter. After creating an instance of the SDK, pass it to the adapter's constructor.

Session Management: To ensure data is captured reliably, the SDK hooks into Three.js's native WebXR session events.

Starting the Session: An event listener is attached to the renderer for the session start event. This event fires as soon as the user enters VR. Inside this listener, we call c3d.startSession(renderer.xr.getSession()). This is a crucial step that begins the analytics recording. By passing the active XRSession, the SDK can automatically handle gaze tracking without any extra code in the render loop.

Ending the Session: Similarly, an event listener is attached for the session end event, which fires when the user exits VR. Inside this listener, c3d.endSession() is called. This function ensures that all remaining batched data is sent to the server and properly finalizes the session on the Cognitive3D dashboard. This step is vital to prevent data loss.

// My ThreeJS VR app with Cognitive3D anayltics
import * as THREE from 'three';
import C3D from '@cognitive3d/analytics'; // main c3d sdk 
import C3DThreeAdapter from '@cognitive3d/analytics/adapters/threejs'; // c3d threejs adapter 
import settings from './settings'; // SDK settings file

// --- Basic Three.js VR Setup ---
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;
document.body.appendChild(renderer.domElement);
// ... add VR button and your scene objects

// --- Cognitive3D Initialization ---
// 1. Initialize the main SDK, passing the renderer to enable the profiler
const c3d = new C3D(settings, renderer);

// 2. Initialize the Three.js Adapter
const c3dAdapter = new C3DThreeAdapter(c3d);

// 3. Set your scene and user info
c3d.setScene('MyThreeJsScene');
c3d.setUserProperty("c3d.app.version", "0.2"); // REQUIRED PROPERTY, ensure this is set 
c3d.setUserProperty("c3d.deviceid", 'threejs_device_' + Date.now()); // REQUIRED PROPERTY, ensure this is set 
// ... set other user/device properties

// --- Start Session ---
renderer.xr.addEventListener('sessionstart', async () => {
    // By passing the xrsession to startSession(), gaze tracking is handled automatically.
    await c3d.startSession(renderer.xr.getSession());
    console.log("Cognitive3D Session Started!");
});

// Other code.... 

// --- End Session ---
renderer.xr.addEventListener('sessionend', () => {
        console.log('Cognitive3D: VR Session Ended');
        c3dInstance.endSession().then(status => {
            console.log('Cognitive3D SDK session ended with status:', status);
        });
    });

PlayCanvas

The PlayCanvas integration allows you to easily enable the built-in performance profiler.

1. Upload SDK Files

In the PlayCanvas Editor, upload the following files from the SDK's /lib directory:

c3d.umd.js (The main SDK library)

c3d-playcanvas-adapter.umd.js (The PlayCanvas adapter)

2. Set Script Loading Order

The adapter depends on the main SDK, so it must be loaded first.

In the PlayCanvas Editor, go to Settings -> Script Loading Order.

Drag c3d.umd.js so it appears above c3d-playcanvas-adapter.umd.js.

3. Initialization in a Script and Usage

In a PlayCanvas script component, you can now initialize the SDK and pass this.app to enable performance tracking.

var MyScript = pc.createScript('myScript');

MyScript.prototype.initialize = function() {
    // --- Cognitive3D Initialization ---
    // 1. Define your settings object
    const settings = { /* ... your APIKey and sceneId ... */ };

    // 2. Initialize the SDK, passing 'this.app' to enable the profiler
    const c3d = new C3D(settings, this.app);

    // 3. Initialize the PlayCanvas Adapter
    const c3dAdapter = new C3DPlayCanvasAdapter(c3d);

    // 4. Set your scene and user info
    c3d.setScene('MyPlayCanvasScene');
    c3d.setUserProperty("c3d.app.version", "0.2"); // REQUIRED PROPERTY, ensure this is set 
    c3d.setUserProperty("c3d.deviceid", 'playcanvas_device_' + Date.now()); // REQUIRED PROPERTY, ensure this is set 
    // ... set other user/device properties
};

Wonderland Engine

The Wonderland Engine integration is straightforward using NPM.

1. Wonderland Engine C3D Analytics Installation

Open a terminal inside your Wonderland Engine project's root folder and run:

npm install @cognitive3d/analytics

2. Create an Analytics Component

Create a new JavaScript file in your Wonderland project (e.g., js/c3d-analytics-component.js) and use the following code. This component handles the entire lifecycle of the SDK.

import { Component, Type } from "@wonderlandengine/api";
import C3D from "@cognitive3d/analytics";
import C3DWonderlandAdapter from "@cognitive3d/analytics/adapters/wonderland";

let c3d;

export class C3DAnalyticsComponent extends Component {
    static TypeName = "c3d-analytics-component";
    static Properties = {
        apiKey: { type: Type.String, default: "YOUR_APPLICATION_API_KEY" },
        sceneName: { type: Type.String, default: "SampleScene" },
        sceneId: { type: Type.String, default: "YOUR_SCENE_ID" },
        versionNumber: { type: Type.String, default: "1" },
    };

    start() {
        // Ensure the SDK is only initialized once
        if (c3d) return;

        // 1. Initialize the core C3D SDK using properties from the editor
        c3d = new C3D({
            config: {
                APIKey: this.apiKey,
                allSceneData: [{
                    sceneName: this.sceneName,
                    sceneId: this.sceneId,
                    versionNumber: this.versionNumber
                }]
            }
        });

        // 2. Instantiate the Wonderland Adapter, passing the c3d instance and the engine
        new C3DWonderlandAdapter(c3d, this.engine);

        // 3. Configure your session details 
        c3d.setScene(this.sceneName);
        c3d.setUserProperty("c3d.app.version", "0.2"); // REQUIRED PROPERTY, ensure this is set 
        c3d.setUserProperty("c3d.deviceid", 'wonderlandengine_device_' + Date.now()); // REQUIRED PROPERTY, ensure this is set
        // 4. Hook into the engine's session events to manage the session lifecycle
        this.engine.onXRSessionStart.add(this.onXRSessionStart.bind(this));
        this.engine.onXRSessionEnd.add(this.onXRSessionEnd.bind(this));
    }

    /**
     * Called automatically by the engine when a WebXR session starts.
     * @param {XRSession} session The active WebXR session.
     */
    async onXRSessionStart(session) {
        console.log('Cognitive3D: VR Session Started');

        // Start the analytics session, passing the XR session enables automatic gaze tracking.
        const success = await c3d.startSession(session);
        if (success) {
            console.log('Cognitive3D SDK session successfully started.');
        }
    }

    /**
     * Called automatically by the engine when a WebXR session ends.
     */
    onXRSessionEnd() {
        console.log('Cognitive3D: VR Session Ended');
        if (c3d) {
            // End the session to ensure all batched data is sent.
            c3d.endSession().then(status => {
                console.log('Cognitive3D SDK session ended with status:', status);
            });
        }
    }
}

3. Register the Component and Usage

Make sure your new C3DAnalyticsComponent is registered with the engine in your main js/index.js file.

  • Import the component: Add this line within the wle:auto-imports block to make your component's code available to the project.
import {C3DAnalyticsComponent} from './c3d-analytics-component.js';
  • Register the component with the engine: Add this line within the wle:auto-register block. This is the crucial step that makes the component appear in the editor's UI, allowing you to add it to objects in your scene.
engine.registerComponent(C3DAnalyticsComponent);

The c3d-analytics-component will be fully integrated and ready to use in your Wonderland project.

  • Within the Wonderland Engine, select an object or create a new object in the hierarchy.
  • Add the component c3d-analytics-component to the object and enter your Cognitive3D project information: API Key, sceneName, sceneID and versionNumber.

Plain Javascript / No Framework

You can use the SDK in any project without an engine/ framework. The core features like Session Properties and Custom Events will still work.

Manual Implementation Example

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

const c3d = new C3D(settings);
c3d.setScene('MyRawWebXRScene');

// ... set user/device properties
c3d.setDeviceProperty("AppEngine", "None"); // REQUIRED PROPERTY, ensure this is set if not using an engine adapter
c3d.setUserProperty("c3d.app.version", "0.2"); // REQUIRED PROPERTY, ensure this is set 
c3d.setUserProperty("c3d.deviceid", 'plainjs_device_' + Date.now()); // REQUIRED PROPERTY, ensure this is set

await c3d.startSession(); // start c3d session 


c3d.endSession(); // end session

Sample applications

For more detailed examples and complete project integrations (Playcanvas, ThreeJS, Wonderland Engine), please see our sample applications repository

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.