Skip to content

Working with source code

If you want the entire c3d-sdk-webxr source code, whether that be to run tests or make modifications.

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.
  • Cognitive3D Scene: 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.
  • 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 from source code

1. Clone the repo

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

2. Install the dependencies

npm install

3. Build the sdk

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

npm run build

Project Structure

Here's an overview of the key files and directories in the WebXR-SDK:

c3d-sdk-webxr/
├── src/           # Contains the source code for the SDK.
   ├── adapters/   # Modules for integrating with Three.js, Babylon.js, PlayCanvas, etc.
   └── utils/      # Utility modules for framerate tracking, HMD orientation, etc.
├── __tests__      # Contains all the Jest tests for the SDK.
├── lib/           # Generated by the build process, contains the transpiled SDK files (UMD, ESM, CJS).
└── settings.js    # Configuration file for the SDK tests (API key, scene info).

Configuration

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.

Set the API Key (Environment variable)

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"

Update SDK's Scene Information

Now that you have created and obtained an API KEY and setup a "Scene" on Cognitive3D, 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 Cognitive3D 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 entries or remove them from the array.

Testing 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 have configured your own project/ scene on the Cognitive3D platform (as mentioned in the requirements above).

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.

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

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

Run the test suites

npm run test

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

Note: 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:

Install the local sdk to your project

To install the local sdk to your project, navigate to your projects directory, and then run the following command:

npm install /pathTo/c3d-sdk-webxr

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.