NOTE: CognitiveVR has been rebranded to Cognitive3D. Code references, methods, menus, and variables remain untouched.

Using the Cognitive3D SDK for Unreal

Welcome! This SDK for Unreal provides analytics and insights about your project. In addition, Cognitive3D empowers you to take actions that will improve users' engagement with your experience.

This SDK is in development and changes should be expected! Please get in touch if you experience any issues.

This plugin has been tested with Unreal verion 4.14.3. If you are using a newer version, please check Troubleshooting. It has only been tested on Windows 10.


Step 1: Sign up

If you have not already done so, please book a demo at cognitive3d.com.

Step 2: Download the SDK

Our package is available on our Github Release page.

Step 3: Import the SDK

These instructions will help you install the C++ API as well as Blueprint nodes

Note

Your Unreal project must be a C++ project to use plugins. To convert from a Blueprint project, see Troubleshooting first

  • Close Unreal
  • Copy the plugins folder into your project root. This is the directory with Binaries, Intermediate and Source folders and YourProjectName.uproject file

root

  • Open Source/YourProjectName/YourProjectName.Build.cs. Add the following line:

    PublicDependencyModuleNames.AddRange(new string[] {"CognitiveVR", "Json", "JsonUtilities"});
    

  • Delete the Binary folder in your project. This is regenerated when you recompile

  • Add the following Plugins section to YourProjectName.uproject to enable Analytics Blueprints if they are not yet enabled. You will need to open YourProjectName.uproject with a text editor. This is an example of a completed .uproject file:
{
    "FileVersion": 3,
    "EngineAssociation": "4.14",
    "Category": "",
    "Description": "",
    "Modules": [
        {
            "Name": "YourProjectName",
            "Type": "Runtime",
            "LoadingPhase": "Default"
        }
    ],
    "Plugins": [
        {
            "Name": "AnalyticsBlueprintLibrary",
            "Enabled": true
        }
    ]
}
  • Right-click on YourProjectName.uproject and select Generate Visual Studio project files
  • When you open your project through the Epic Games Launcher, you will be prompted to recompile your project and the cognitiveVR Plugin

  • If the plugin is loaded correctly, it should be visible in the Plugins window

Plugins Window

Step 4: Log In

Open the Project Settings window and select the Cognitive VR section. Select your organization and product from the dropdown menus. The Test and Production buttons allow you to separate your data so internal development does not affect the data from your live application.

Login Panel

Save your selection. This will write the appropriate data to DefaultEngine.ini. You must restart Unreal to reload the changes to your config file.

Step 5: Basic Setup

Blueprint

  • Analytics Blueprints should be enabled already. This was done when "AnalyticsBlueprintLibrary" was added to YourProjectName.uproject
  • Open the Blueprint Editor. We recommend initializing cognitiveVR Analytics in the Level Blueprint
  • Set Age, Set Gender, Set UserID must be called before Start Session
  • Start Session will automatically send basic information about the computer. Note that Start Session does not immediately connect with the analytics server
  • Record Event, Record Event with Attribute, and Record Event with Attributes are for your general gameplay events
  • End Session is recommended but not required

Blueprint Startup

Blueprint Events

C++

You can access the analytics from either IAnalyticsProvide methods or FAnalyticsProviderCognitiveVR methods. These methods can be called from any source file in your project. You must add #include "CognitiveVR.h" in your source file.

This is a short example of how to initialize the CognitiveVR Analytics SDK in C++. See the Code Reference page for more examples and how to use the API.

From the Content Browser add a C++ class. Call it 'AnalyticsInitExample'. This will generate AnalyticsInitExample.h and AnalyticsInitExample.cpp files. The complete AnalyticsInitExample.h and AnalyticsInitExample.cpp files are shown below

AnalyticsInitExample.h

#pragma once

#include "GameFramework/Actor.h"
#include "FloatingActor.generated.h"

UCLASS()
class YOURPROJECTNAME_API AAnalyticsInitExample : public AActor
{
    GENERATED_BODY()

public: 
    // Sets default values for this actor's properties
    AAnalyticsInitExample();

    // Called when the game starts or when spawned
    virtual void BeginPlay() override;
};

AnalyticsInitExample.cpp

#include "YourProjectName.h"
#include "AnalyticsInitExample.h"

// Sets default values
AAnalyticsInitExample::AAnalyticsInitExample()
{
}

// Called when the game starts or when spawned
void AAnalyticsInitExample::BeginPlay()
{
    Super::BeginPlay();
    TSharedPtr<IAnalyticsProvider> Analytics = FAnalytics::Get().GetDefaultConfiguredProvider();
    if (Analytics.IsValid())
        Analytics->StartSession();
    else
        GLog->Log("AAnalyticsInitExample::BeginPlay could not get default configured analytics provider!");
}

Add this actor to your Unreal level and rebuild your project - this may require closing the editor.

Step 6: Send data!

Open the cognitive3D dashboard or press the Open On Dashboard... button and select the Debugger tab.

Integrations Tab

Integrations Data

Run your Unreal project. There is a short delay before 'batches' of data are sent, but you should see events arriving on this page.

Done!

That's it! You are now tracking your user's basic data including engine version, CPU brand, RAM, GPU, HMD and OS