Skip to content

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.

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.