Skip to content

PlayCanvas Integration

Cognitive3D integrates with PlayCanvas through the @cognitive3d/analytics and its C3DPlayCanvasAdapter. The PlayCanvas integration supports the core WebXR SDK features — session management, automatic WebXR gaze tracking, performance profiling, custom events, sensors, exit polls, and properties.

Limitations

Scene export, object export, dynamic objects, and per-object heatmaps are currently not supported. Support for these features may come at a later time.

Requirements

  • Cognitive3D Account: You'll need an active Cognitive3D account to obtain your API keys and set up your project. You can sign up at the Cognitive3D platform website.

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

  • PlayCanvas project: playcanvas >= 1.50.0 is the supported peer version.

Step 1: Add the Cognitive3D Bundle to Your Project

PlayCanvas projects are typically authored in the online editor, so the easiest way to add the SDK is to upload the pre-built UMD bundle from the /lib folder of the SDK package:

  • c3d-bundle-playcanvas.umd.js — a single file containing both the core SDK and the PlayCanvas adapter.

Upload that file as an asset in the PlayCanvas Editor and make sure it's included in your scene's loading order so both C3D and C3DPlayCanvasAdapter are available as globals before your scripts run.

Step 2: Create a Settings File

Keep your config outside your script component so it's easy to update.

// settings.js (or inline inside your script)
export default {
  config: {
    APIKey: "YOUR_APPLICATION_API_KEY",
    allSceneData: [
      {
        sceneName: "MyPlayCanvasScene",
        sceneId: "",        // filled in after scene upload
        versionNumber: "1",
      },
    ],
  },
};

Step 3: Initialize the SDK in a Script Component

Pass this.app (the pc.Application instance) as the renderer argument to the C3D constructor. This enables the automatic performance profiler, which records draw calls, memory, frame time, and FPS sensors once the session is active.

var C3DAnalytics = pc.createScript("c3dAnalytics");

C3DAnalytics.attributes.add("apiKey", { type: "string", default: "YOUR_APPLICATION_API_KEY" });
C3DAnalytics.attributes.add("sceneName", { type: "string", default: "MyPlayCanvasScene" });
C3DAnalytics.attributes.add("sceneId", { type: "string", default: "" });
C3DAnalytics.attributes.add("versionNumber", { type: "string", default: "1" });

C3DAnalytics.prototype.initialize = function () {
    const settings = {
        config: {
            APIKey: this.apiKey,
            allSceneData: [{
                sceneName: this.sceneName,
                sceneId: this.sceneId,
                versionNumber: this.versionNumber,
            }],
        },
    };

    // 1. Initialize the SDK. Passing 'this.app' enables the profiler.
    this.c3d = new C3D(settings, this.app);

    // 2. Initialize the PlayCanvas adapter (sets AppEngine / AppEngineVersion).
    this.c3dAdapter = new C3DPlayCanvasAdapter(this.c3d);

    // 3. Set the active scene.
    this.c3d.setScene(this.sceneName);

    // 4. Set the required app version property.
    this.c3d.setUserProperty("c3d.app.version", "1.0"); // REQUIRED
};

The adapter automatically sets AppEngine = "PlayCanvas" and AppEngineVersion = pc.version on the session's device properties.

Step 4: Session Lifecycle

Wire up session start/end to PlayCanvas's XR events, and call c3d.endSession() when the user exits VR so batched data is flushed.

C3DAnalytics.prototype.postInitialize = function () {
    const xr = this.app.xr;

    xr.on("start", async () => {
        const xrSession = xr.session;
        await this.c3d.startSession(xrSession);
        console.log("Cognitive3D: session started");
    });

    xr.on("end", () => {
        this.c3d.endSession().then(status => {
            console.log("Cognitive3D: session ended with status", status);
        });
    });
};

Step 5: Uploading Your Scene

Currently not supported by Cognitive3D, you'll need to produce your scene geometry another way — for example, by exporting your scene to glTF from a DCC tool (Blender, Maya, etc.) and using the four required files (scene.gltf, scene.bin, settings.json, screenshot.png).

Upload these using the Cognitive3D Upload Web App. This requires your Developer Key.

After upload, copy the returned Scene ID and version into your script attributes or settings:

✅ Scene uploaded successfully!
   Scene ID:      a1b2c3d4-e5f6-g7h8i9j0
   Version:       1
   Scene Name:    MyPlayCanvasScene

Step 6: Events and Sensors

Anywhere in your PlayCanvas scripts you can record custom events and sensor readings through the SDK:

// Custom event with a 3D position and optional properties
this.c3d.customEvent.send("tutorial_step_completed", [0, 1, 0], { step: 3 });

// Sensor value over time (number or boolean)
this.c3d.sensor.recordSensor("heartRate", 85);

See the Custom Events and Sensors pages for details.

Not Yet Supported

The following features are currently not available with the PlayCanvas adapter.

  • Scene Export
  • Object Export
  • Dynamic Objects (per-object heatmaps, engagement events)

The WebXR SDK is actively being developed. Support for these features may arrive in a later release.

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.