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 application 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 Cognitive3D Upload Web App.
  • Node.js 20.0+: Required for modern JavaScript compatibility. To check your current version: node --version

Step 1. 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.
├── types/         # Generated TypeScript declaration files (.d.ts) for Intellisense.
├── settings.js    # Configuration file for the SDK tests (API key, scene info).
└── CLAUDE.md      # AI agentic workflow and Model Context Protocol guidelines.

Step 2. Configuration

Step 2.1 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.

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

Step 2.2 Set the Application API key (environment variable)

The SDK uses dotenv to automatically load environment variables during testing. Create a .env file in the root of the c3d-sdk-webxr directory and add your application key:

# .env
C3D_APPLICATION_KEY="YOUR_API_KEY"

Alternatively, you can temporarily set it in your terminal session before running the tests.

On Windows (PowerShell)

$env:C3D_APPLICATION_KEY="YOUR_APPLICATION_API_KEY"

On macOS or Linux

export C3D_APPLICATION_KEY="YOUR_APPLICATION_API_KEY"

Step 3. Update SDK scene information

Now that you have an application 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.

Step 4. 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.

Step 4.1 Build the SDK with configured settings

Once your application API key and scene information are configured, rebuild the SDK:

npm run build

Step 4.2 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.

Step 5. Install the local SDK to your project

To install the local SDK built src files ~ /lib to your project, navigate to your project's directory and run the following command:

npm install /localPathTo/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.