Getting Started

Step 1: Sign up

If you don't have an account, please contact us at Cognitive3D.com

Step 2: Install the NPM package

npm install cognitive3d-analytics

Step 3: Create a Settings File

To initialize the package properly, C3DAnalytics needs to be instantiated with settings.

We recommend creating a settings file that you can then import to your files:

//settings.js

export default {
    config: {
        APIKey: 'ASDF1234ASDF',     // API Key is available on the dashboard
        gazeBatchSize: 64,          // Number of Gaze snapshots stored in a batch before sending to server
        dynamicDataLimit: 64,       // Number of Dynamic Object snapshots stored in a batch before sending to server
        customEventBatchSize: 64,   // Number of Custom Event snapshots stored in a batch before sending to server
        sensorDataLimit: 64,        // Number of Sensor snapshots stored in a batch before sending to server
        HMDType: 'Oculus Rift',     // Defaut HMD Type set in Metadata for this project. You can overwrite this at run time via Metadata methods.
        allSceneData: [
            // Scene data can be found on the Dashboard
            {
                sceneName: 'test_scene1',
                sceneId: 'test_id1',
                versionNumber: '1'
            },
            {
                sceneName: 'test_scene2',
                sceneId: 'test_id2',
                versionNumber: '2'
            },
            {
                sceneName: 'test_scene3',
                sceneId: 'test_scene3',
                versionNumber: '3'
            },
            {
                sceneName: 'tutorial',
                sceneId: 'b9d33399-1e13-428e-9559-7d15f28e9683',
                versionNumber: '3'
            }
        ]
    },
}

Step 4: Import plugin and settings

//app.js
import C3DAnalytics from 'cognitive-3d-analytics/lib'
import mySettings from './settings.js'

const c3d = new C3DAnalytics(mySettings);

Step 5: Add user metadata

c3d.userId = 'myUserId';        // Required
c3d.setUserName("John Smith");  // A friendly name to label this user session

//User properties & metadata can be set using the following method: setUserProperty('property', 'value);
c3d.setUserProperty('Age', 21);
c3d.setUserProperty('SomeGroup', 'someValue');
c3d.setUserProperty('HairColor', 'Brown');

//Device specific properties work the same:
c3d.setDeviceName('Samsung');
c3d.setDeviceProperty('AppName', 'myTestApp');

A full list of all device properties that can found on the metadata page.

Step 6: Start a Session

Choose which scene is currently active, and start the session:

c3d.setScene('test_scene1');
c3d.startSession();

Step 7: Record User Gaze

We provide a simple API to record users' Gaze data:

c3d.gaze.recordGaze(pos, rot, gaze, objectId /*optional*/);

// pos:      position array [x,y,z] of the the current position of the user. The HMD position in worldspace.
// rot:      quaternion rotation [x, y, z, w] of the user's head.
// gaze:     position array [x,y,z] in local object space where the user is gazing at
// objectId: objectId when gazing at a Dynamic Object. If this is not set, assumption is made that user is looking at some point on the static scene object.

In practice:

//app.js
import C3DAnalytics from 'cognitive-3d-analytics/lib'
import settings from './settings.js'

...

const c3d = new C3DAnalytics(settings);
c3d.setScene('test_scene1');
c3d.startSession();

const pos = [0, 0, 0];
const point = [0, 0, 1];
const rot = [0, 0, 0, 1];

c3d.gaze.recordGaze(pos, rot);
//or
c3d.gaze.recordGaze(pos, rot, point, 'object_id');

Generally we consider recording the user gaze at 10Hz (10 times per second).

---

For custom events, sensor data, and more features please see the feature tabs on the left.