Getting Started

Step 1: Sign up

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

Step 2: Install

Download the C++ SDK repository from GitHub

To use Cognitive3DAnalytics, copy the header and source files into your project. For organization, create a new folder named 'cognitive' to keep these files together. Alternatively, you can use CMake to build a static library and include that and the headers in your project.

In your files that need to use Cognitive3DAnalytics to record events, dynamic objects, gaze or anything else, add #include "cognitive/CognitiveVRAnalytics.h" with your other includes.

Step 3: Construct a Settings Object

Create a CognitiveSettings object. This will hold all your configurable project data required to construct CognitiveVRAnalyticsCore.

  • WebRequest is used to communicate to send https requests and receive responses.
  • AllSceneData holds information about the scenes in your application. This data is accessible from the Cognitive3D Dashboard. See SceneId for details
  • APIKey is required for authenticating data with our dashboard A full initialization looks like this:
#include "cognitive/CognitiveVRAnalytics.h"

void MakeWebRequest(std::string httpsUrl, std::string content, std::vector<std::string> headers, cognitive::WebResponse responseCallback)
{
    //make a web request to 'httpsUrl' with 'content' as the body
    //use whatever https implementation you like to send the request
    //BELOW IS PSEUDOCODE! see ClientProject.cpp for an sample synchronous implementation

    CURL* curl;
    CURLcode res;
    std::string* responseBody;

    curl->SetUrl(httpsUrl);
    curl->SetBody(content);
    curl->SetHeaders(headers);
    curl->SetResponseBody(responseBody);
    res = curl->Post();

    if (responseCallback != nullptr)
    {
        responseCallback(responseBody);
    }
}

std::unique_ptr<CognitiveVRAnalyticsCore> cog;
int main()
{
    cognitive::CoreSettings settings;
    settings.webRequest = &MakeWebRequest;
    //get the APIKey from the Dashboard
    settings.APIKey = "1234abcd5678";
    //if you have a private cloud, use the CustomGateway to change where session data is sent, ignoring https://. Otherwise, you can skip this field
    settings.CustomGateway = "data.cognitive3d.com";

    settings.loggingLevel = cognitive::LoggingLevel::kAll;
    settings.SensorDataLimit = 64;
    settings.DynamicDataLimit = 64;
    settings.CustomEventBatchSize = 64;
    settings.GazeBatchSize = 64;
    settings.GazeInterval = 0.1f;
    settings.HMDType = cognitive::ECognitiveHMDType::kRift;
    //Sets the expected file type for displaying dynamic objects on SceneExplorer. Defaults is "obj"
    settings.DynamicObjectFileType = "gltf";

    std::vector<cognitive::SceneData> scenedatas;
    //replace "asdf1234hjkl6789" with the uploaded SceneIds from the Dashboard. If you don't have a scene uploaded, get in touch!
    scenedatas.emplace_back(cognitive::SceneData("tutorial", "asdf1234hjkl6789", "1"));
    scenedatas.emplace_back(cognitive::SceneData("menu", "qwer6789zxcv1234", "1"));
    settings.AllSceneData = scenedatas;
    settings.DefaultSceneName = "tutorial";

    //....
}

Step 4: Constructor and Meta Data

You must provide a unique DeviceName or UserName. You can generate a unique id from the hardware running this session. See this link for a method. A unique UserName can also be useful to track a user across multiple play sessions.

It is recommended you include any information about the user or device that you know.

std::unique_ptr<CognitiveVRAnalyticsCore> cog;
int main()
{
    //...

    //create CognitiveVRAnalyticsCore from settings
    cog = cognitive::make_unique_cognitive<cognitive::CognitiveVRAnalyticsCore>(settings);
    //if you're using c++14, you can use this instead:
    //cog = std::make_unique<cognitive::CognitiveVRAnalyticsCore>(settings);

    //set a unique device name
    cog->SetDeviceName("7741345684915735");

    //set the user's name. this should be a unique value
    cog->SetUserName("john_1234");
    cog->SetSessionProperty("age",21);
    cog->SetSessionProperty("favouritefood","bananas");

    //set any device properties you know
    cog->SetSessionProperty("memory", 128);
    cog->SetSessionProperty("os", "chrome os 16.9f");
    cog->SetSessionProperty("gpu", "GeForce GTX 970");
    cog->SetSessionProperty("cpu", "i7-4770 CPU @ 3.40GHz");

    //...
}

Step 5: Start the Session

Before starting the session, it is recommended to set a DefaultSceneName in the CognitiveSettings. SceneData is used to send data to the correct scene on SceneExplorer. See the Advanced page

std::unique_ptr<CognitiveVRAnalyticsCore> cog;
int main()
{
    //...
    cog->StartSession();

    //you can use this code to access the instance of the CognitiveVRAnalyticsCore
    auto instance = cognitive::CognitiveVRAnalyticsCore::Instance();
    if (instance != nullptr)
        instance->SendData();

    //run your application
    //...

    cog->EndSession();
    return 0;
}

That's a very basic setup for the Cognitive3D Analytics. However, much more data can be recorded over the duration of the experience. See Recording Gaze for the next steps