Skip to content

Feature Overview

C++ Setup

To use the C++ examples, make sure to include:

  • PublicDependencyModuleNames.Add("Cognitive3D"); in YourProject.Build.cs
  • #include "Cognitive3D/Public/Cognitive3D.h" in your header file

Start and End Sessions

A Session will begin automatically from the BP_Cognitive3DActor in your scene. This is implemented with Blueprints so you can easily modify the behaviour if needed.

A Session can be started with various Properties or you can add Properties later from the SDK while the Session is recording data. 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 (multiple Sessions) 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<FAnalyticsProviderCognitive3D> cognitive = FAnalyticsCognitive3D::Get().GetCognitive3DProvider();
    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<FAnalyticsProviderCognitive3D> cognitive = FAnalyticsCognitive3D::Get().GetCognitive3DProvider();
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 have some variable starting parameters, this could be a good place to record those conditions. You can set Session Properties at any time during the experience - but they will overwrite any property with the same name.

session properties

TWeakPtr<FAnalyticsProviderCognitive3D> cognitive = FAnalyticsCognitive3D::Get().GetCognitive3DProvider();
if (cognitive.IsValid())
{
 cognitive.Pin()->SetSessionProperty("starting currency",25.0);
 cognitive.Pin()->SetSessionProperty("store","main street");
}

Session Tags

Session Tags are similar to Properties, but can be used to isolate metrics for specific Sessions. For example, if you are doing A/B testing on a focus group, Tags would be ideal for analyzing a single group at a time. Tags can also be changed on the Dashboard after the Session is complete.

session tags

TWeakPtr<FAnalyticsProviderCognitive3D> cognitive = FAnalyticsCognitive3D::Get().GetCognitive3DProvider();
if (cognitive.IsValid())
{
 cognitive.Pin()->SetSessionTag("group_a");
}

Participants

See Participants for more details.

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<FAnalyticsProviderCognitive3D> cognitive = FAnalyticsCognitive3D::Get().GetCognitive3DProvider();
if (cognitive.IsValid())
{
 cognitive.Pin()->SetParticipantId("UniqueID_0001");
 cognitive.Pin()->SetParticipantName("Jane Doe");
}

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 Cognitive3D Actor. Otherwise, there are no special requirements to use this feature.

If you are using level streaming to cull geometry in a larger level, it is recommended to make all the sublevels visible when exporting your persistent scene from the Scene Setup Window.

all sublevels visible

Gaze and Fixation

Gaze is automatically recorded on a set interval from the Participant's point of view. This uses the Player Tracker component on the Cognitive3D Actor. When using an Eye Tracking SDK, the Fixation Recorder component on the Cognitive3D Actor is used as well. See Gaze and Fixations for details 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<FAnalyticsProviderCognitive3D> cognitive = FAnalyticsCognitive3D::Get().GetCognitive3DProvider();
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<FAnalyticsProviderCognitive3D> provider = FAnalyticsCognitive3D::Get().GetCognitive3DProvider();
float oxygen = FMath::FRandRange(75.0, 100.0);
provider->sensors->RecordSensor("Heart.Blood Oxygen", oxygen);

Multiplayer

To see more info on multiplayer, see the Multiplayer or 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<FAnalyticsProviderCognitive3D> cognitive = FAnalyticsCognitive3D::Get().GetCognitive3DProvider();
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 = FAnalyticsCognitive3D::Get().GetCognitive3DProvider();
if (cognitive.IsValid())
{
    FString parameters = cognitive.Pin()->GetAttributionParameters();
    FString url = FString("www.example.com/product_005" + parameters);
    FString Error;
    FPlatformProcess::LaunchURL(*url, nullptr, &Error);
}

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.