Skip to content

Working with source code

Access the full c3d-sdk-webxr source code if you need to run tests or make modifications to the SDK.

Requirements

  • Cognitive3D account: An active account to obtain your API key and set up your project. Sign up on the Cognitive3D website.
  • Cognitive3D scene: A scene configured in your Cognitive3D account. You can create a scene and get the necessary Scene Name, Scene ID, and Scene Version using the Upload Web App.
  • Node.js 20.0+: Required for modern JavaScript compatibility. 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 transpiles the SDK src files into a /lib folder.

npm run build

Project Structure

The key files and directories in the c3d-sdk-webxr repository are:

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 test 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 macOS or Linux

export C3D_APPLICATION_KEY="YOUR_API_KEY"

Update SDK scene information

Now that you have an API key and a scene set up on Cognitive3D, 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. 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 are configured, rebuild 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, configure at least 2 scenes in settings.js (and on Cognitive3D). Without this, 4 tests are skipped. exitpoll-test.js also 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 project's directory and 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.