The Cognitive3D SDK for Javascript, TypeScript and WebXR

Welcome! This SDK allows you to integrate your JavaScript/ TypeScript/ 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. To check your current version:

node --version

🔧 Installation

You can add Cognitive3D to your project in two ways.

Option 1. Install from NPM

Inside your 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 and generate type definitions into a /types 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

📂 Project Structure

Here's an overview of the key files and directories in the project:

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.
├── assets/           # Contains images and logos used in the readme.
├── 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).

🚀 Usage

The SDK is flexible and integrates seamlessly with various frameworks/ web engines such as ThreeJS, Wonderland Engine, PlayCanvas, and more.

It supports both immersive VR and immersive AR WebXR sessions, including mobile AR flows built on Three.js and Mattercraft. For immersive AR sessions, the SDK automatically prefers a local reference space and falls back to local-floor when needed, while boundary tracking stays disabled unless the platform exposes a bounded reference space.

It supports a wide range of development environments by providing multiple module formats in the /lib folder:

• UMD: Universal format for direct use in browsers via a <script> tag.
• ES Module: Modern module standard, used by most bundlers and modern Node.js.
• CommonJS: Compatible with older Node.js environments.

Using the core SDK without an engine adapter

When you use an engine adapter (Three.js, Babylon.js, PlayCanvas, Wonderland), the adapter sets c3d.app.engine for you. If you use the core SDK directly with no adapter (plain WebXR/WebGL), the SDK now defaults c3d.app.engine to "WebXR" so your sessions are accepted by the analytics pipeline — its enrichment layer treats c3d.app.engine as a required property and drops sessions that omit it.

As belt-and-suspenders, you can also set it yourself to better identify your integration (this overrides the default):

c3d.setDeviceProperty('AppEngine', 'YourEngineName');
c3d.setDeviceProperty('AppEngineVersion', '1.0.0');

📚 Documentation

The Cognitive3D WebXR SDK documentation explains how to integrate the SDK, track user experiences, export scenes, track dynamic objects, and more.

🎮 Sample Projects

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

Coding Agent Skills

This repo ships reusable skills under .claude/skills/ — self-contained helpers (instructions plus a script) that a coding agent auto-discovers when you open the repo, so you can invoke them by name. The SKILL.md format originated with Claude Code and is now supported by a growing number of coding agents.

Not using a coding agent (or yours doesn't support skills)? Each skill's SKILL.md documents the underlying script so you can run it directly.

Skill

What it does

validate-c3d-session

Verify your session data has actually landed on the Cognitive3D platform. Give it your organization API key (dashboard → Organization Settings → API Keys — the organization ID is derived for you) and, optionally, a project ID; it reports whether recent sessions arrived plus a few top-level details (duration, name, participant, captured data types, device, test/junk tags). Read-only, works for any SDK/host, needs curl + jq.

Example:

export C3D_ORG_API_KEY='orgkey-…'   # keeps the key out of shell history
.claude/skills/validate-c3d-session/scripts/validate-c3d-session.sh --project 1234