Skip to content

Feature Overview

The C++ code below assumes you have added PublicDependencyModuleNames.Add("CognitiveVR"); in YourProject.Build.cs. You will also need to add #include "CognitiveVR/Public/CognitiveVR.h" to your header file.

Start and End Sessions

You can start a Session with Session Properties or you can add properties later. End Session is automatically called when the application closes or the editor stops playing. In some cases you may want to manually End a Session - for example if a Participant makes multiple attempts on a training exercise without closing the application. Sessions will persist between different Levels.

Participants should consent to data collection as described in your privacy policy. If you do not wish to record analytics for any reason, simply do not call StartSession.

session begin

if (bAcceptedPrivacyPolicy == true)
{
    TWeakPtr<FAnalyticsProviderCognitiveVR> cognitive = FAnalyticsCognitiveVR::Get().GetCognitiveVRProvider();
    if (cognitive.IsValid())
    {
        //start session
        cognitive.Pin()->StartSession();

        //start session with properties
        TArray<FAnalyticsEventAttribute> properties;
        properties.Add(FAnalyticsEventAttribute("store", "main street"));
        cognitive.Pin()->StartSession(attributes);

        //end the session
        cognitive.Pin()->EndSession());
    }
}

Session Name

You can set a custom name for a Participant's Session. This can be useful for organizing Sessions on the Dashboard and SceneExplorer. If you do not provide a Session name, it will use the Participant Name. If that is also not provided, a Session Name will be generated for you and can be changed on the Dashboard. You can set a Session Name before or after the Session is started.

session name

TWeakPtr<FAnalyticsProviderCognitiveVR> cognitive = FAnalyticsCognitiveVR::Get().GetCognitiveVRProvider();
if (cognitive.IsValid())
{
    cognitive.Pin()->SetSessionName("VR Convention 2018");
}

Session Property

You may have some additional data to record that is relevant to the entire Session. For example, if you are doing A/B testing on a focus group, this could be a good place to record which group the Participant is in. You can set Session Properties at any time during the experience - but they will overwrite any property with the same name.

session properties

TWeakPtr<FAnalyticsProviderCognitiveVR> cognitive = FAnalyticsCognitiveVR::Get().GetCognitiveVRProvider();
if (cognitive.IsValid())
{
    cognitive.Pin()->SetSessionProperty("group",1);
    cognitive.Pin()->SetSessionProperty("starting currency",25.0);
    cognitive.Pin()->SetSessionProperty("store","main street");
}

Participants

This can be used to track a Participant across multiple Sessions. You can set the Participant name, Id and properties at any time. The Participant Id must be Unique.

participant properties

TWeakPtr<FAnalyticsProviderCognitiveVR> cognitive = FAnalyticsCognitiveVR::Get().GetCognitiveVRProvider();
if (cognitive.IsValid())
{
    cognitive.Pin()->SetParticipantId("UniqueID_0001");
    cognitive.Pin()->SetParticipantName("Jane Doe");
    cognitive.Pin()->SetGender("Female");
    cognitive.Pin()->SetAge(21);
    cognitive.Pin()->SetParticipantProperty("Height", 180);
}

Changing Levels

Data recorded by the SDK will be uploaded automatically when a Level changes. This requires the current Level to have been uploaded to the Dashboard from the Scene Setup Window and that the new Level contains a Player Actor with a Player Tracker component. Otherwise, there are no special requirements to use this feature.

Gaze and Fixation

Gaze is automatically recorded on a set interval from the Participant's point of view. This requires the Player Tracker component on the Player Actor. When using an Eye Tracking SDK, a Fixation Recorder component must be added to the Player Actor. See Fixation Recorder Settings for details about this Component or Fixations for a high level overview.

Custom Events

For more information, see Custom Events.

Custom Events allow you to record specific events during your experience. These can include position, properties, durations and related Dynamic Objects.

simple custom event

TWeakPtr<FAnalyticsProviderCognitiveVR> cognitive = FAnalyticsCognitiveVR::Get().GetCognitiveVRProvider();
if (cognitive.IsValid())
{
    //send an event with a name
    cognitive.Pin()->customEventRecorder->Send("My Event");
    //send an event with a name and a position
    cognitive.Pin()->customEventRecorder->Send("My Event With Position",FVector(0,100,0));
}

Dynamic Objects

For more information, see Dynamic Objects.

The Dynamic Object component allows you to track the positions and states of actors during the Participant's Session. In most cases, you'll simply need to:

  • Add a Dynamic Object Component to your actor
  • Press the "Export" then "Upload" buttons on the Dynamic Object Component

ExitPoll

For more information, see ExitPoll.

ExitPoll allows you to get direct answers from your Participants. There are two parts to set up:

  1. Create a Question Set and Hook on the Dashboard.
  2. Create an ExitPoll Blueprint in Unreal using the Hook.

Sensors

For more information, see Sensors.

When using biometric sensors, you can get a detailed snapshot of the participant's physical state. While we don't support specific sensors, we provide a simple API to record sensor data and display this data on SceneExplorer.

sensor blueprint

TSharedPtr<FAnalyticsProviderCognitiveVR> provider = FAnalyticsCognitiveVR::Get().GetCognitiveVRProvider();
float oxygen = FMath::FRandRange(75.0, 100.0);
provider->sensors->RecordSensor("Heart.Blood Oxygen", oxygen);

Lobby

To see more info on lobbies, go to the Lobby System page.

A LobbyId connects multiple Participant Sessions together to display a multiuser experience. Please get in contact to discuss your implementation details.

lobby id

//game server pseudocode

map<string,string> headers;
headers.Add("Authorization","APIKEY:DATA " + APIKey);
auto response = http::post("https://data.cognitive3d.com/v0/lobbies",headers);
auto json = json::parse(response.Content);
string lobbyid = json["id"];
//send lobbyid to each client

//game client
TWeakPtr<FAnalyticsProviderCognitiveVR> cognitive = FAnalyticsCognitiveVR::Get().GetCognitiveVRProvider();
if (cognitive.IsValid())
{
    cognitive.Pin()->SetLobbyId(lobbyid);
}

Attributions

For more information, see Attributions.

When opening a URL from your experience, you can append an Attribution Key. This can be captured on your webpage to identify which Session engaged with this content outside of your immersive experience.

attribution blueprint

auto cognitive = FAnalyticsCognitiveVR::Get().GetCognitiveVRProvider();
if (cognitive.IsValid())
{
    FString parameters = cognitive.Pin()->GetAttributionParameters();
    FString url = FString("www.example.com/product_005" + parameters);
    FString Error;
    FPlatformProcess::LaunchURL(*url, nullptr, &Error);
}