The Cognitive3D SDK for Javascript and WebXR

Welcome! This SDK allows you to integrate your Javascript and WebXR Applications with Cognitive3D, which provides analytics and insights about your VR/AR/MR project. In addition, Cognitive3D empowers you to take actions that will improve users' engagement with your experience.

Requirement(s)

Node.js version 20 or higher

• We currently require a version of Node.js of 20 or higher for this SDK. If this doesn't match your needs, let us know.

Cognitive3D Documentation

The documentation explains how to integrate the SDK, track your users' experience and how to export your scene to view on Cognitive3D.com.

Go to the Docs

Installation

You can add Cognitive3D to your javascript project in two ways.

Option 1. Install from NPM

Inside your javascript project's terminal, run the following command

npm install @cognitive3d/analytics

Option 2. Install from source code

If you want the entire source code, whether that be to run tests, make modifications, you can clone this repository by

A) Clone the repo

git clone https://github.com/CognitiveVR/c3d-sdk-webxr.git
cd c3d-sdk-webxr

B) Install the dependencies

npm install

C) Build the sdk

This will transpile the SDK src files into a /lib folder

npm run build

D) Install the local sdk to your project

Navigate to your projects directory, and then run the following command

npm install /pathTo/c3d-sdk-webxr

Using the SDK

The SDK comes with a full test suite using Jest. The tests are configured to run against a live project on the Cognitive3D platform. Therefore, to successfully run these tests, you must first configure your own project on the Cognitive3D platform.

1. Configuration for testing

A) Get your API Key

The SDK and tests scripts require a valid API Key to send data to a Cognitive3D project. Sign up at Cognitive3D.com, create a new project, and find your Application API Key on your dashboard.

B) Set the environment variable (API Key)

The SDK's test configuration in settings.js reads your API key from an environment variable named C3D_APPLICATION_KEY. You must set this variable in your terminal before running the tests.

On Windows (powershell)

$env:C3D_APPLICATION_KEY="YOUR_API_KEY"

On MaxOS or Linux

export C3D_APPLICATION_KEY="YOUR_API_KEY"

C) Setup a scene on the Cognitive3D Dashboard (with c3d-upload-tools)

To view your projects analytics, you also need a "Scene" set up in your Cognitive3D account. This gives our platform a place to store the data you send from your application. You can create a scene and get the necessary Scene Name, Scene ID, and Scene Version by using our command-line utility.

Please following the instructions here: https://github.com/CognitiveVR/c3d-upload-tools

D) Update SDK's Scene Information

Now that you have created and obtained an API KEY and setup a "Scene" on Cognititve3D, you now have to update settings.js to point to scenes within your own Cognitive3D Project.

Open settings.js and modify the allSceneData array to match the Scene Name, Scene ID, and Scene Version from your own Cogntitve3D dashboard. Example:

// settings.js
allSceneData: [
    { // Scene 1 
        sceneName: "YOUR_SCENE_NAME", 
        sceneId: "YOUR_SCENE_ID", 
        versionNumber: "YOUR_SCENE_VERSION",
    },
    { // Scene 2 
        sceneName: "YOUR_SECOND_SCENE_NAME",
        sceneId: "YOUR_SECOND_SCENE_ID",
        versionNumber: "YOUR_SECOND_SCENE_VERSION"
    }
],

Note: Depending on how many scenes you have, you can duplicate entrys or remove them from the array.

2. Testing the SDK

There are currently 56 tests within 9 test suites located inside of __tests__. These tests provide comprehensive coverage for the SDK's core features, including:

• Session initialization and lifecycle management.
• Sending custom events, gaze data, and sensor data.
• Registering and tracking dynamic objects.
• Requesting and submitting Exit Polls.

Note: Please be aware that to pass all 56 tests, you must configure at least 2 scenes in settings.js (as well as on Cognitive3D), otherwise (4) tests are skipped. Also exitpoll-test.js requires additional setup on the Cognitive3D dashboard:

• __tests__/exitpoll-test.js uses a specific hook named "app_test_js". Therefore, please create your own Exit Poll on your Cognitive3D dashboard and replace this hook with your own.

A) Build the SDK with configured settings

Once your API KEY and scene information is set. We have to again build the SDK:

npm run build

B) Run the test suites

npm run test

If everything is setup correctly, you should see all 9 test suites pass.

Usage

The SDK is designed to be flexible and can be integrated into various JavaScript projects. The build process creates multiple module formats in the /lib folder to support different environments.

• index.umd.js (Universal Module Definition): One-size-fits-all for direct use in browsers. It's designed to be dropped into a <script> tag on a webpage.
• index.esm.js (ES Module): The modern module standard for JavaScript. It's used by default in most web bundlers and modern Node.js.
• index.cjs.js (CommonJS): The module format for older Node.js environments.

Initializing the Cognitive3D SDK in your JavaScript project

// MyApp.js 
import C3D from '@cognitive3d/analytics';

// 1. DEFINE YOUR PROJECT'S CONFIGURATION, REPLACE VALUES WITH THE ONES FROM YOUR OWN PROJECT. 
const settings = {
    config: {
        APIKey: "YOUR_APPLICATION_KEY_HERE",
        allSceneData: [
            {
                networkHost: "data.c3ddev.com", // data.cognitive3d.com is prod, data.c3ddev.com is dev 
                sceneName: "YOUR_SCENE",
                sceneId: "YOUR_SCENE_ID_",
                versionNumber: "1"
            }
        ],
    }
};

// 2. INITIALIZE C3D ANALYTICS 
const c3d = new C3D(settings /*, renderer */); // renderer will provide additional profiler sensor recordings (if provided) 

// 3. SET PROPERTIES THAT IDENTIFY THE USER/ DEVICE

c3d.setScene('BasicScene'); // Replace with your Scene name
c3d.userId = 'userid' + Date.now();
c3d.setUserName('SDK_Test_User');
c3d.setDeviceName('WindowsPCBrowserVR');
c3d.setDeviceProperty("AppName", "ThreeJS_WebXR_SDK_Test_App");
c3d.setUserProperty("c3d.app.version", "0.2");
c3d.setUserProperty("c3d.deviceid", 'threejs_windows_device_' + Date.now());

// 4. START THE C3D SESSION, Example using a WebXR 'sessionstart' event listener:
renderer.xr.addEventListener('sessionstart', async () => {
    const xrSession = renderer.xr.getSession();

    // Use 'await' to ensure the session is fully initialized before proceeding.
    await c3d.startSession(xrSession); // Pass the XR session for gaze tracking

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

    // 5. INSERT CODE HERE TO TRACK OTHER EVENTS, SENSORS, ETC...
});

// 6. END THE C3D SESSION, Example using a WebXR 'sessionend' event listener:
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.

Playcanvas integration

1. To integrate with Playcanvas, upload the built main sdk library /lib/c3d.umd.js and the adapter script /lib/c3d-playcanvas-adapter.umd.js to your PlayCanvas project.
2. The adapter depends on the main SDK, so the SDK must be loaded first. In the PlayCanvas editor, go to Settings > Script Loading Order. Drag c3d.umd.js above c3d-playcanvas-adapter.umd.js to ensure it loads first.

ThreeJS Integration

1. Inside your ThreeJS project, run npm install @cognitive3d/analytics or if you have the sdk locally: npm install /pathTo/c3d-sdk-webxr.
2. Import the sdk and threeJS adapter within your threeJS project:

import C3DAnalytics from '@cognitive3d/analytics';
import C3DThreeAdapter from '@cognitive3d/analytics/adapters/threejs';

3. Initialize the main SDK first, then the threeJS adapter

const c3d = new C3D(your_sdk_settings);
const c3dAdapter = new C3DThreeAdapter(c3d);

Sample Projects

For more detailed examples and complete project integrations, please see our sample applications repository at: https://github.com/CognitiveVR/c3d-webxr-sample-apps