Troubleshooting C3D Configuration Issues
When integrating our Cognitive3D analytics SDK into your project, there are certain settings and configurations that are written into the Default configuration files under Project/Config, and as of SDK version 1.10.0, they are written into Project/Config/c3dlocal/Cognitive3DSettings.ini file and the Project/c3dlocal/Cognitive3DKeys.ini file as of SDK version 1.10.5
This page will cover ways to troubleshoot various known rare and uncommon issues with this system.
Identifying problems
Before we explain troubleshooting steps, lets first find out how we can identify that there is an issue with the configuration files.
The expected results of the initial steps are to set-up the project and then the scene, the former being where you will enter your developer key, retrieve or enter the application key, and set an export directory first. Before continuing on to the scene setup, this is a good point to check that the keys are in the settings page under Project Settings -> Cognitive3D under the Account section. You should be able to see your Developer Key, Application Key and Export Path populated.
Bad Endpoint Errors
If you face any issues with validating your Developer Key, with the output log indicating that the web request could not be processed due to a bad endpoint or Gateway, it would be a good point to check the configuration file.
On editor startup, and when you open the settings page or setup windows, the module checks that the Cognitive3DSettings.ini file exists and created it if it doesn't. Upon creation it will also write initial properties, which include the Gateway for the web requests.
If this file does not contain this information, particularly the Gateway, you can try restarting the editor, or manually adding them:
Cognitive3DSettings.ini
[/Script/Cognitive3D.Cognitive3DSettings]
Gateway=data.cognitive3d.com
GazeBatchSize=256
CustomEventBatchSize=256
CustomEventAutoTimer=10
DynamicDataLimit=512
DynamicAutoTimer=10
SensorDataLimit=512
SensorAutoTimer=10
EnableLocalCache=True
LocalCacheSize=100
Missing Keys
Before continuing on to the scene setup, this is a good point to check that the keys are in the settings page under Project Settings -> Cognitive3D under the Account section. You should be able to see your Developer Key, Application Key and Export Path populated. You should then check the Cognitive3DSettings.ini file for the ApiKey, which is the Application Key, and the Export Directory.
Another file is created specifically for your Developer Key called Cognitive3DKeys.ini. This file is located in the ProjectRoot/c3dlocal folder that will not be included in application builds. Check that it includes your Developer Key, if not, add it in:
Cognitive3DKeys.ini
[Analytics]
DeveloperKey=XYZ321
Note
As of SDK Version 1.10.5, we highly recommend excluding Cognitive3DKeys.ini from your version control, as it contains a unique personal key for your project.
The Application Key and Export Path are saved in the Cognitive3DSettings.ini file, where all the other C3D configurations will be. Here's what it would look like:
[Analytics]
ApiKey=ABC123
AttributionKey=
ExportPath=C:/Users/Name/Desktop/CognitiveTemp
ProviderModuleName=Cognitive3D
You can play from the editor to verify that data is being uploaded to your scene correctly. During runtime, the game will use your Application Key to associate the analytics to your scene on the dashboard. If you see any error messages about a missing Application Key, that could indicate that your configuration file is missing the ApiKey value. Make sure it is included as per the sample above.
You can also restart the editor after everything is done being set-up, exported and uploaded to make sure things are written correctly to the configuration file. Confirm this by going to the Cognitive3D section of the Project Settings.
Missing Scene Data
When you run a session, the SDK looks for the ApiKey in Cognitive3DSettings.ini as discussed above, and it also looks for the SceneData that was created during the Scene Setup process to know what scene it will send this data to inside your project.
If you run a session and you do not see it on the dashboard after waiting a few minutes, this could indicate that there was a problem from the SDK side. Keep in mind that running a session in-editor will produce sessions with the Test tag, and if they do not have headset data, they will also have the Junk tag. These sessions may not show up by default if you also have sessions from the headset, so make sure you check the tag filters before you determine it is an SDK issue. If it does happen to be missing completely, check the Cognitive3DSettings.ini file to make sure that it includes the various SceneData entires of the ones you have set up and want to track. If at this point you do not see the Scene Data in the Project Settings or the Cognitive3DSettings.ini file, you can manually add that information to the file without having to re-upload the scene, because doing so will upload a totally new scene and not increment the version number. It would look like this:
[/Script/Cognitive3D.Cognitive3DSceneSettings]
SceneData=scene_name,scene_id,scene_version,scene_version_id
You can get all these fields from your dashboard. Because you have already uploaded a scene successfully at this point in the setup, despite the configuration file errors, you will be able to see it on the dashboard. Open it up under your organization and make your way to Scenes.
From there, find your scene. Next to your scene name, there are some tabs, Scene Viewer, Object Explorer, and Media. Next to them is an icon, that when hovered over, will show you all the scene information that you need to fill into the placeholders in the configuration file from the snippet above.
You can also find the Scene Id and the version number in the URL when you are on the base page of your scene:
https://app.cognitive3d.com/v3/scenes/scene_id/v/scene_version/viewer
Add these in and save your file, then restart the editor.
Full Sample
At this point we have covered how to manually construct the configuration data in case they are not written correctly by the SDK. Sometimes the problem is fixed by restarting the editor, as is the case with most Unreal Engine configurations and settings.
For the sake of completion, here is what the Cognitive3DSetings.ini file should look, with placeholders for your actual data:
[Analytics]
ApiKey=ABC123
AttributionKey=
ExportPath=C:/Users/Name/Desktop/CognitiveTemp
ProviderModuleName=Cognitive3D
[/Script/Cognitive3D.Cognitive3DSettings]
Gateway=data.cognitive3d.com
GazeBatchSize=256
CustomEventBatchSize=256
CustomEventAutoTimer=10
DynamicDataLimit=512
DynamicAutoTimer=10
SensorDataLimit=512
SensorAutoTimer=10
EnableLocalCache=True
LocalCacheSize=100
[AnalyticsDebug]
ProviderModuleName=Cognitive3D
[AnalyticsTest]
ProviderModuleName=Cognitive3D
[AnalyticsDevelopment]
ProviderModuleName=Cognitive3D
[/Script/Cognitive3D.Cognitive3DSceneSettings]
SceneData=scene_name,scene_id,scene_version,scene_version_id