VadR Analytics can be used to collect a wide range of data from a user session. By default some data like user position, gaze, etc; are collected, though it can be customised to collect any data in your application. Events are the primary way through which data is collected. Each datapoint contains an event name, position of event occurence and optionally filters and info associated with the event.
Events
Events are the primary way to through which VadR Analytics collect data from your application. Events can be discrete or continuous. Killing an enemy is an example of discrete event whereas position of the user is an example of continous event. There is no need to register events on the dashboard before using them in the application. You can directly start sending the data. Every datapoint contains an event and also a position of where the event occur in the application. This enables us to present the same data as both heatmaps and graphs. Events are case-sensitive that means “position” and “Position” would be separate events.
Filters
Filters are key-value pair that can be associated with an event. These are used to filter the data of an event. For Ex; For the event Enemy Kill, you might be interested in knowing the gun used for killing. So in that case the Filter Key can be “Gun” and value could be Type of Gun(say “machine gun”). Multiple filters can be associated with an event. Filters are case sensitive.
Info
Info are key-value pair (values are float) that are associated with an event to provide them some quantity. For ex; To know the time spent by user in different rooms a Info whose value corresponds to total time in a room can be associated with the event. Or for Enemy hit, damage dealed could be an info that could be used. Multiple Info can be associated with an event. Info are case sensitive.
Registering An App
To start using the VadR’s analytics platform you need to first register your application on the dashboard.
For registering an Application some basic details are required.
Name – Name of the application that you want to register.
Type of VR App – The category of your application. Different categories are Game, Entertainment, Education, Travel and Local, Experience and Others.
Application Scenes – Scenes or Levels are the different Unity Scenes in your application for which you want to add analytics. Multiple scenes can be added for an Application. Scenes can also be added to the application later.
Fig. Registering An App.
After the application is registered, you can see it in the list of all apps. You also have an option to share the registered application with other users. The added users can then view the analytics data or even modify the settings of the application based on their permission level. The list of apps have all the applications added by you or to which you are added as an Admin/Viewer.
Fig. App List.
ThreeJS Integration
Importing Package
To integrate VadR Analytics, depending on how you are creating your application, you can either include our analytics module using npm or directly include our prebuild script in your html code.
Using npm
Install our npm module using the following command.
npm install --save vadr-three-vr
Import our package into your code using the below code. You can then access our apis using the 'VADR' keyword.
import VADR from 'vadr-three-vr'
Using script
You can also directly include our script in your html file using the below script tag. You can then access our apis using the 'VADR' keyword.
appId: application id provided to you by the platform
appToken: application token provided to you on the platform
sceneId: scene id of the scene for which data needs to be collected
testMode: set this to true during development. This is done so that the data collected during application development does not interfare with production data. Default value is false.
version: set this to your current application version. This is done so that collected data can be viewed based on your application versions. Default value is "1.0.0".
appParams: dictionary containing the configuration paramters for data collection and extra meta data about the current session.
{
'defaultEvents': [
{
'name': 'orientation',
'status': true,
'timePeriod': 300
},
{
'name': 'gaze',
'status': true,
'timePeriod': 300
},
{
'name': 'performance',
'status': true,
'timePeriod': 300
}
],
'sessionInfo': [
{
'key': 'demo place'
'value': 'San Francisco office'
}
],
'pauseOnHeadsetRemove': true // to pause the data collection when headset is removed,
'ignoreWindowStateChange': true // when user wishes to manage the state of the window to play or pause data collection
}
You can provide any or all the fields above based on your requirement. For default events a list of default events can be found in the VADR.enums dictionary.
camera: threejs camera object which is being used as the primary camera
scene: threejs scene object which contains the main content of the application.
Animate command
You need to call the below command in your animate loop so that analytics data is properly and continuously captured.
VADR.tick();
Setting Camera
If you are resetting the camera after initialization, you need to register it using the following function.
VADR.setCamera(AFrameCameraObject);
Default Events
There are some default events common to most of the applications that can be collected by VadRAnalytics. These events are
Position - This is the user (or Main Camera) position in the environment. You can plot heatmap of this event to know distribution of user's position in the scene.
Gaze - This is the point where user (or Main Camera) is directly looking. You can plot heatmap of this event to know distribution of user's gaze in the scene.
FPS - Frame Per Seconds(FPS) is the performance metrics of your application. Higher the FPS the better is user experience. This event is registered with an Info Value, use this info to get the FPS in the scene.
Collection Frequency
By default Position and Gaze events are collected every 300 milliseconds while the FPS is collected every one second(1000 milliseconds). You can customize which event should be collected and with what time interval either during initialization as shown above or during runtime. Setting too low a value for the Time Interval would lead to your application getting busy in collecting the data. On the other hand setting too high a value might lead to loss of precision. A good value for the time interval is 300 milliseconds.
The above code informs the SDK that orientation and gaze need to be collected every 500 milliseconds. The last line directs the SDK to not collect FPS (performance) data.
Custom Events
Beside these Default Events, developers can register any number of custom events. Each event datapoint consists of an event name, position of event occurence and optionally Filters & Info. There are some conventions to followed while naming Events, Filters and Info.
Naming Convention
Events
Event name shouldn’t start with “vadr”. It is a reserved key word.
Length of an event name should be less than 20 characters.
Event Name shouldn’t contain special characters or “ - ” symbol. Though “_” can be used.
Event Name is case sensitive.
Filters and Info
Length of Filter Key and Info Key should be less than 20 characters.
Length of Filter Value should be less than 30 characters.
Filter Key and Info Key shouldn’t contain special characters. Though “_” can be used.
All Key-Value pairs are case sensitive.
Registering Custom Events
Any custom event can be registered by calling the registerEvent function. It takes three parameters as input, event name, 3D position array of the form [x,y,z] and an extra dictionary containing filter and info key value pairs. If the provided value is a float, it is considered as information and if the provided value is a string, it is considered as a filter.
VADR.registerEvent(eventName, position, extra);
The following examples should clarify the funtions behaviour.
Here we provide two key-value pairs in the extra dict. Similar to second and third examples, 'damage' is taken as information and 'gunUsed' is considered as filter.
Scenes and Media
The scenes and 360 media for which data is being collected can be changed on the fly using functions exposed by the SDK. One thing to note is 360 media exist within scene, therefore a scene must exist in scope before a media is registered.
Scenes
The following functions are used to manage scenes. The add scene function takes sceneId as input and starts data collection for the new scene. You can also optionally provide a scene name. The close scene closes data collection for the current scene.
You can start and close data collection to 360 media anytime. You should also register events such play, pause and seek change for proper data collection.
mediaId: Unique id with which you identify the media within your application
media Name: Name of the media which should be displayed while viewing the data
type: Type of media. Use 'Video' for 360 video and 'Image' for 360 image.
url: Optional url which can be used to retreive the media when viewing data. If not provided at runtime, you can also mention the url or upload the media from our dashboard.
You can close the media by calling the following function:
VADR.media.closeMedia();
To register events such as play, pause and change seek use the following functions. Keep in mind, these functions should be called with actual play, pause, seek change events for correct data collection.
Extra information and the current session can be set using the below functions. These are supplied in the form of string key value pairs. The maximum length of the key can be 50 characters, while the maximum length of value strings can be 256 characters. You also assign a specific id to the user, to identify him while visualizing information. If not specified, the SDK itself generates a random userid.
Events such as headset applied and headset removed are automatically handled. By default data collection is paused on headset removal and resumed when headset is applied bcak. You can change this behaviour by calling the pauseOnHeadsetRemove and dontPauseOnHeadsetRemove functions. Note that the below commands need to be called to indicate headset applied/ headset removed instructions. Other events such as when application is paused, or when it is resumed, need to be trigger to pause/resume data collection and show the correct timing.
VADR.playState.appInFocus(); // to start data collection
VADR.playState.appOutOfFocus(); // to pause data collection
VADR.playState.headsetApplied(); // to show headset is applied
VADR.playState.headsetRemoved(); // to show headset is removed
VADR.playState.pauseOnHeadsetRemove(); // data collection pauses on headset removal, default behaviour
VADR.playState.dontPauseOnHeadsetRemove(); // data collection continues on headset removal
360 Image Special case
There might be cases where you have some objects (such as text, hotspots etc.) being displayed over the 360 Image. Media heatmaps in this case will only displayed on the equirectangular projection of the 360 image, and any impact of the overlying objects on the heatmaps will not be visible.
Such cases can be handled by using an alternate 360 image to display heatmaps. The alternate 360 image is extracted from within your ThreeJs scene and contains the objects displayed on top of the original. VadR provides a modified version of Jaume Sanchez Elias' script which makes it easy to take out such 360 images.
const equirectangularExtractor = new CubemapToEquirectangular( renderer, true );
Step 3 - When your scene is ready, point your main camera to direction which is the center point in your original 360 image, and call the following funciton.
equirectangularExtractor.update( camera, scene );
ThreeJS Integration
Importing Package
To integrate VadR Analytics, depending on how you are creating your application, you can either include our analytics module using npm or directly include our prebuild script in your html code.
Using npm
Install our npm module using the following command.
npm install --save vadr-three-vr
Import our package into your code using the below code. You can then access our apis using the 'VADR' keyword.
import VADR from 'vadr-three-vr'
Using script
You can also directly include our script in your html file using the below script tag. You can then access our apis using the 'VADR' keyword.
appId: application id provided to you by the platform
appToken: application token provided to you on the platform
sceneId: scene id of the scene for which data needs to be collected
testMode: set this to true during development. This is done so that the data collected during application development does not interfare with production data. Default value is false.
version: set this to your current application version. This is done so that collected data can be viewed based on your application versions. Default value is "1.0.0".
appParams: dictionary containing the configuration paramters for data collection and extra meta data about the current session.
{
'defaultEvents': [
{
'name': 'orientation',
'status': true,
'timePeriod': 300
},
{
'name': 'gaze',
'status': true,
'timePeriod': 300
},
{
'name': 'performance',
'status': true,
'timePeriod': 300
}
],
'sessionInfo': [
{
'key': 'demo place'
'value': 'San Francisco office'
}
],
'pauseOnHeadsetRemove': true // to pause the data collection when headset is removed,
'ignoreWindowStateChange': true // when user wishes to manage the state of the window to play or pause data collection
}
You can provide any or all the fields above based on your requirement. For default events a list of default events can be found in the VADR.enums dictionary.
camera: threejs camera object which is being used as the primary camera
scene: threejs scene object which contains the main content of the application.
Animate command
You need to call the below command in your animate loop so that analytics data is properly and continuously captured.
VADR.tick();
Setting Camera
If you are resetting the camera after initialization, you need to register it using the following function.
VADR.setCamera(AFrameCameraObject);
Default Events
There are some default events common to most of the applications that can be collected by VadRAnalytics. These events are
Position - This is the user (or Main Camera) position in the environment. You can plot heatmap of this event to know distribution of user's position in the scene.
Gaze - This is the point where user (or Main Camera) is directly looking. You can plot heatmap of this event to know distribution of user's gaze in the scene.
FPS - Frame Per Seconds(FPS) is the performance metrics of your application. Higher the FPS the better is user experience. This event is registered with an Info Value, use this info to get the FPS in the scene.
Collection Frequency
By default Position and Gaze events are collected every 300 milliseconds while the FPS is collected every one second(1000 milliseconds). You can customize which event should be collected and with what time interval either during initialization as shown above or during runtime. Setting too low a value for the Time Interval would lead to your application getting busy in collecting the data. On the other hand setting too high a value might lead to loss of precision. A good value for the time interval is 300 milliseconds.
The above code informs the SDK that orientation and gaze need to be collected every 500 milliseconds. The last line directs the SDK to not collect FPS (performance) data.
Custom Events
Beside these Default Events, developers can register any number of custom events. Each event datapoint consists of an event name, position of event occurence and optionally Filters & Info. There are some conventions to followed while naming Events, Filters and Info.
Naming Convention
Events
Event name shouldn’t start with “vadr”. It is a reserved key word.
Length of an event name should be less than 20 characters.
Event Name shouldn’t contain special characters or “ - ” symbol. Though “_” can be used.
Event Name is case sensitive.
Filters and Info
Length of Filter Key and Info Key should be less than 20 characters.
Length of Filter Value should be less than 30 characters.
Filter Key and Info Key shouldn’t contain special characters. Though “_” can be used.
All Key-Value pairs are case sensitive.
Registering Custom Events
Any custom event can be registered by calling the registerEvent function. It takes three parameters as input, event name, 3D position array of the form [x,y,z] and an extra dictionary containing filter and info key value pairs. If the provided value is a float, it is considered as information and if the provided value is a string, it is considered as a filter.
VADR.registerEvent(eventName, position, extra);
The following examples should clarify the funtions behaviour.
Here we provide two key-value pairs in the extra dict. Similar to second and third examples, 'damage' is taken as information and 'gunUsed' is considered as filter.
Scenes and Media
The scenes and 360 media for which data is being collected can be changed on the fly using functions exposed by the SDK. One thing to note is 360 media exist within scene, therefore a scene must exist in scope before a media is registered.
Scenes
The following functions are used to manage scenes. The add scene function takes sceneId as input and starts data collection for the new scene. You can also optionally provide a scene name. The close scene closes data collection for the current scene.
You can start and close data collection to 360 media anytime. You should also register events such play, pause and seek change for proper data collection.
mediaId: Unique id with which you identify the media within your application
media Name: Name of the media which should be displayed while viewing the data
type: Type of media. Use 'Video' for 360 video and 'Image' for 360 image.
url: Optional url which can be used to retreive the media when viewing data. If not provided at runtime, you can also mention the url or upload the media from our dashboard.
You can close the media by calling the following function:
VADR.media.closeMedia();
To register events such as play, pause and change seek use the following functions. Keep in mind, these functions should be called with actual play, pause, seek change events for correct data collection.
Extra information and the current session can be set using the below functions. These are supplied in the form of string key value pairs. The maximum length of the key can be 50 characters, while the maximum length of value strings can be 256 characters. You also assign a specific id to the user, to identify him while visualizing information. If not specified, the SDK itself generates a random userid.
Events such as headset applied and headset removed are automatically handled. By default data collection is paused on headset removal and resumed when headset is applied bcak. You can change this behaviour by calling the pauseOnHeadsetRemove and dontPauseOnHeadsetRemove functions. Note that the below commands need to be called to indicate headset applied/ headset removed instructions. Other events such as when application is paused, or when it is resumed, need to be trigger to pause/resume data collection and show the correct timing.
VADR.playState.appInFocus(); // to start data collection
VADR.playState.appOutOfFocus(); // to pause data collection
VADR.playState.headsetApplied(); // to show headset is applied
VADR.playState.headsetRemoved(); // to show headset is removed
VADR.playState.pauseOnHeadsetRemove(); // data collection pauses on headset removal, default behaviour
VADR.playState.dontPauseOnHeadsetRemove(); // data collection continues on headset removal
360 Image Special case
There might be cases where you have some objects (such as text, hotspots etc.) being displayed over the 360 Image. Media heatmaps in this case will only displayed on the equirectangular projection of the 360 image, and any impact of the overlying objects on the heatmaps will not be visible.
Such cases can be handled by using an alternate 360 image to display heatmaps. The alternate 360 image is extracted from within your ThreeJs scene and contains the objects displayed on top of the original. VadR provides a modified version of Jaume Sanchez Elias' script which makes it easy to take out such 360 images.
const equirectangularExtractor = new CubemapToEquirectangular( renderer, true );
Step 3 - When your scene is ready, point your main camera to direction which is the center point in your original 360 image, and call the following funciton.
equirectangularExtractor.update( camera, scene );
Unreal Integration
Importing Plugin
Grab the latest Unreal Plugin by VadR. Unzip it and copy the VadRAnalytics directory to the Plugins directory in your Project root directory. This directory contains YourProject.uproject file. Note the plugin only works in a C++ Project and not Blueprint Project.
Fig. - A Sample Unreal Project root directory.
Adding Dependencies
Once the plugin is copied
Open "YourProject.build.cs" it should be in "YourProject/Source" directory and add the following dependencies.
Now Delete the Binaries directory in "YourProject" directory. They should be recompiled.
Right Click on "YourProject.uproject" file and select "Generate Visual Studio project Files".
Now when you open the project it shall ask you to create the compile Binaries files again. Select yes.
If the package is imported successfully you be able to see it in Plugins window.
Fig. - Plugin Window with VadR Analytics Plugin.
Default Events
There are some default events common to most of the applications that can be collected by VadRAnalytics. To enable them you need toAdd "DataCollector" as the child component of your Main Camera(or any other camera you want to track). Add "DataCollector" as the child component of your Main Camera(or any other camera you want to track).
Fig. - Datacollector component added to camera needed to be tracked.
Position - This is the user (or Main Camera) position in the environment. You can plot heatmap of this event to know distribution of user's position in the scene.
Gaze - This is the point where user (or Main Camera) is directly looking. You can plot heatmap of this event to know distribution of user's gaze in the scene.
FPS - Frame Per Seconds(FPS) is the performance metrics of your application. Higher the FPS the better is user experience. This event is registered with an Info Value, use this info to get the FPS in the scene.
Track Objects - Sometimes you might need to track user gaze over multiple objects. For ex; In a real estate scene how long a user is seeing a sofa. You can provide multiple objects(Game Objects and Name you want to give them) to track them. This event is registered with an Information Key(Time) Value(time for which object is viewed) pair and two filter key-value pairs, Filter Key(Objects) - Value(name of the gameobjects given by developer) and Filter Key(Viewing Range) - Value(Whether the object is viewed from close or far range).
Setting DataCollector
Add "DataCollector" as the child component of your Main Camera(or any other camera you want to track).
After adding "DataCollector", fill the information in details panel of the DataCollector component.
App Id - Application Id Obtained from the dashboard.
App Token - Application Token obtained from the dashboard.
Version No. - Version of the application
Scene Id - Id corresponding to scene/level obtained from the dashboard.
Collection Interval - The time interval (in seconds) between collection of each datapoint. A good value for Collection Interval is 0.3 (300 milliseconds).
Events - Boolean flag for collection of data for a paticular default event (Position, Gaze, FPS).
Hit Range - The range for counting the gaze. This value may depend on your application.
Test Mode - A boolean value to select whether the data collected is for test (or develepment) or is it Live mode.
Track Objects - A Map of objects that you want to track. Specify the "key" (name of the objects) and Actor (objects) that you want to track.
Fig. - Details entered in the Datacollector component.
Custom Events
Beside these Default Events, developer can register any number of custom events. Each datapoint consists of an event, position of event occurence, optionally Filters and Info can also be associated with it. There are some conventions to followed while naming Events, Filters and Info.
Naming Convention
Events
Event name shouldn’t start with “vadr”. It is a reserved key word.
Length of an event name should be less than 20 characters.
Event Name shouldn’t contain special characters or “ - ” symbol. Though “_” can be used.
Event Name is case sensitive.
Filters and Info
Length of Filter Key and Info Key should be less than 20 characters.
Length of Filter Value should be less than 30 characters.
Filter Key and Info Key shouldn’t contain special characters. Though “_” can be used.
All Key-Value pairs are case sensitive.
Code Reference
Registering a Custom Event is just one line of code. To register a custom event;
Here Scene-Time is time in seconds since the start of the scene. Scene-Time can be obtained by
UGameplayStatics::GetRealTimeSeconds(GetWorld());
Info is a TMap with key as FString and value as float and Filters is a TMap with key and value as FString.
Blueprint Reference
Any custom event can also be registered using blueprint. Events can be registered using also. To register an event using blueprint the following nodes are present
Register Event - This node requires event name, position of event occurrence and scene time (Time since beginning of the scene).
Fig. - A sample blueprint to register event.
Register Event With Info - This node requires event name, position of event occurrence and scene time (Time since beginning of the scene) and Info which is an array of DataInfo structure. This accept keys and value (keys should be unique).
Fig. - A sample blueprint to register event with info.
Register Event With Filters - This node requires event name, position of event occurrence and scene time (Time since beginning of the scene) and Filter which is an array of DataFilter structure. This accept keys and value (keys should be unique).
Fig. - A sample blueprint to register event with filters.
Register Event With Info and Filter - This node requires event name, position of event occurrence and scene time (Time since beginning of the scene), Info which is an array of DataInfo structure. This accept keys and value (keys should be unique) and Filter which is an array of DataFilter structure. This accept keys and value (keys should be unique).
Fig. - A sample blueprint to register event with info and filters.
Start-End Events
Sometimes it might be required to get the duration of occurence of an event. For ex; duration since user enter and leaves the room, or duration since an enemy spawned and and got killed. Such kind of events can also be registered by. To register such event you need to start the event. Starting an event gives a unique event id. An event can be ended by providing this event id.
Event-Id is the "Id" obtained while starting the event. Position is the FVector giving position of event occurence. Scene-Time is the time event ended since the begining
For these events an Info "Time" is also registered which gives the duration of the occurence of the event.
Blueprint
StatrtEnd events can also be registered using blueprints. The following nodes can be used
Start Event - This takes Event Name as input.
Fig. - A sample blueprint to start event.
Start Event with Info - This takes Event Name and Info as input. Info is an array of DataInfo structure. This accept keys and value (keys should be unique)
Fig. - A sample blueprint to start event with info.
Start Event with Filter - This takes Event Name and Filter as input. Filter is an array of DataFilter structure. This accept keys and value (keys should be unique).
Fig. - A sample blueprint to start event with filters.
Start Event with Info and Filter - This takes Event Name, Info and Filter as input. Info is an array of DataInfo structure. This accept keys and value (keys should be unique). Filter is an array of DataFilter structure. This accept keys and value (keys should be unique).
Fig. - A sample blueprint to start event.
End Event - This takes Event Id, Position and Game time as input. Event Id is obtained while starting the event.
Fig. - A sample blueprint to end event.
Note: An Event that is started must be ended for it to be registered.
Scene Exporter
VadR Scene Exporter lets you export your scene to visualize all your heatmaps at one location. Just upload all the files generated by Scene Exporter on the dashboard. A scene can be exported from the editor options or dynamically while game is playing in the editor.
Editor Option - To Export Scene using editor options
Select all the objects that you want in the exported scene.
From the "File Menu" Select "Export Selected" option. If you want to include all objects in the Exported Scene then select "Export All".
Select the file type as Object(*.obj)
A Message dialog may appear "Do you want to export material as images?" Select "Yes".
Select the location where you want to save the exported scene files.
Fig. - Exporting a sample Scene using "File -> Export Selected".
Dynamically Exporting - In case you are generating scene dynamically and want to export it, then it is possible to export it using C++ code or Blueprint. To Export Code dynamically
Call ExportLevel
C++ Code - A scene can be exported from C++ code by
Here actor-pointer is a pointer to any actor present in the scene.
Blueprint - To export a scene using blueprint there is node Export Level, which takes actor pointer as input.
After calling ExportLevel, it asks whether you want to export selected objects or all objects. Select "Yes" for Selected Objects and "No" for all objects.
Fig. - Exporting a Sample Scene dynamically.
If "No" was selected in the previous step, then scene exporter will start.
If "Yes" was selected in the previous step, then select all the objects you want to include in exported scene and click "Export Scene". The scene exporter will start. (You may need to press Shift+F1 to get mouse control)
Fig. - Select Objects and click "Export Scene".
Once the Scene Exporter is completed you should be able to see the Scene files in "Content/VadrLevelExport_
" directory in your project root.
Note : While scene exporter is running "Editor" might be a little unresponsive.
Post Scene Exporter - After exporting the scene
Grab "SceneExporter.py" script and place it in the directory where your scene files are present. This is the directory that contains ".mtl" and ".obj" files.
Run the "SceneExporter.py". You need to have Python and Pillow library installed. This script optimises your material images.
After successfully running the script all your scene files to be uploaded are created in "VadrSceneExport" directory. Upload all files in "VadrSceneExport" directory to the dashboard.
Unity Integration
Importing Package
To start using VadR's VR analytic you need to grab the latest unity package from here.
Go to Assets->Import Package->Custom Package and select the VadRAnalytics package. You would see a VadrAnalytics directory created in your Assets folder.
Fig. SDK Integration: Import Package.
From the "VadrAnalytics/Prefabs" directory drag the VadrAnalyticsManager prefab in your scene.
Select the VadrAnalyticsManager prefab and in the inspector you would see DataCollection Script. Provide the AppId, AppToken and SceneId that you get after registering the app.
Select the default events that you want to register for you application. Provide the time interval for collecting these events.
Fig. SDK Integration: Import Package.
You should now be ready to start collecting the data.
Default Events
There are some default events common to most of the applications that can be collected by VadRAnalyticsManager. You just need to enable them. These events are
Position - This is the user (or Main Camera) position in the environment. You can plot heatmap of this event to know distribution of user's position in the scene.
Gaze - This is the point where user (or Main Camera) is directly looking. You can plot heatmap of this event to know distribution of user's gaze in the scene.
FPS - Frame Per Seconds(FPS) is the performance metrics of your application. Higher the FPS the better is user experience. This event is registered with an Info Value, use this info to get the FPS in the scene.
Track Objects - Sometimes you might need to track user gaze over multiple objects. For ex; In a real estate scene how long a user is seeing a sofa. You can provide multiple objects(Game Objects and Name you want to give them) to track them. If your objects are generated real time, then also you can add them in tracking list. This event is registered with an Information Key(Time) Value(time for which object is viewed) pair and two filter key-value pairs, Filter Key(Objects) - Value(name of the gameobjects given by developer) and Filter Key(Viewing Range) - Value(Whether the object is viewed from close or far range). To add objects to tracking list at runtime -
GameObject vadrAnalytics = GameObject.Find("VadrAnalyticsManager");
DataCollection data = vadrAnalytics.GetComponent<DataCollection>();
data.addTrackObject(<gameObject>,<gameObject-name>);
To remove gameObjects from tracking list
data.removeTrackObject(<gameObject>)
Cpu Usage - This is also a performance metrics of your application. This gives the percentage CPU consumption by your application. Lower the Cpu Usage better it is. This event is registered with an Info "Usage", use this info to get Cpu Usage of your application.
Battery Usage - This event gives the average battery usage by your application. This event is registered with an Info "Usage", use this info to get Battery Usage of your application.
Memory Usage - This event gives the memory(RAM) usage by your application. This event is registered with two info :-
Resident Usage - This is an accurate representation of how much actual physical memory a process is consuming
Swap Usage - Swap Usage is space on your hard drive that is reserved to supplement your memory. When there is not enough physical memory in to store all the running programs, then programs that aren't being actively used are moved to the swap space.
Collection Frequency
The Collection Frequency for the default events can be changed by specifying the Time Interval (in seconds) on VadRAnalyticsManager prefab. Default Value is 0.3sec (300 milliseconds). Setting too low a value for the Time Interval would lead to your application getting busy in collecting the data. On the other hand setting too high a value might lead to loss of precision. A good value for the time interval is 0.3 (300 milliseconds).
Custom Events
Beside these Default Events, developer can register any number of custom events. Each datapoint consists of an event, position of event occurence, optionally Filters and Info can also be associated with it. There are some conventions to followed while naming Events, Filters and Info.
Naming Convention
Events
Event name shouldn’t start with “vadr”. It is a reserved key word.
Length of an event name should be less than 20 characters.
Event Name shouldn’t contain special characters or “ - ” symbol. Though “_” can be used.
Event Name is case sensitive.
Filters and Info
Length of Filter Key and Info Key should be less than 20 characters.
Length of Filter Value should be less than 30 characters.
Filter Key and Info Key shouldn’t contain special characters. Though “_” can be used.
All Key-Value pairs are case sensitive.
Code Reference
Registering a Custom Event is just one line of code. To register a custom event;
Here Info is a Dictionary with key as string and value as float and Filters is a Dictionary with key and value as string.
Start-End Events
Sometimes it might be required to get the duration of occurence of an event. For ex; duration since user enter and leaves the room, or duration since an enemy spawned and and got killed. Such kind of events can also be registered by
Event-Id is the "Id" obtained while starting the event. If "Event-End-Position" is not given, then position of Main Camera is taken.
For these events an Info "Time" is also registered which gives the duration of the occurence of the event.
Scene Exporter
VadR Scene Exporter lets you export your scene to visualize all your heatmaps on the dashboard. Just upload all the files generated by Scene Exporter on the dashboard. To export a scene
Click on the VadR option in the menu bar and select SceneExporter.
Enter the "Directory Name" where you want to save the exported files and click on Export Scene.
After the export is complete, you can see your directory in the VadrSceneExporter directory in your project.
Fig. SDK Integration: Scene Exporter.
In certain cases scene objects might be generated at runtime. In such scenario, if you want those objects in your Scene you can export the scene at real time while playing in Unity Editor. To Export Scene in real time just call the following code when your scene is completely loaded and is ready to be exported.
To start using VadR's analytics you need to grab the latest unity package from here.
Go to Assets->Import Package->Custom Package and select the VadRAnalytics package. You would see a VadrAnalytics directory created in your Assets folder.
Fig. SDK Integration: Import Package.
Note :- If you've any previous version of VadRAnalytics package please remove it before importing the new version.
Default Events
There are some default events common to most of the applications that can be collected by VadRAnalyticsManager. You just need to enable them. These events are
Orientation Metrics - This is the user (or Main Camera) orientation or position in the environment. You can plot heatmap of this event to know distribution of user's position in the scene.
Gaze Metrics - This is the point where user (or Main Camera) is directly looking. You can plot heatmap of this event to know distribution of user's gaze in the scene. For collecting Gaze Data you have an option to ignore certain layers where you don't want the gaze data. For example while user is sitting in a car you might be interested in where he is looking outside the car. In such case you can ignore the layer of car glasses. Once you have configured the manager you can ignore the layers by
Select "VadRManager" from the Hierarchy tab and see the "Inspector Tab".
In the "Inspector Tab" locate the "Track Objects" script.
Now in the "Track Objects" option of the script specify the number of objects you want to track.
Specify all the gameobjects that you want to add to the track objects list.
Performane Metrics - This metrics corresponds to how your application is perfroming on different devices. It stores Performance parameters like FPS (Frame Per Seconds), Cpu Usage, Memory Usage, etc. for the application. This event is registered with the name "Performance" and different "info-value" corresponding to each performance parameter.
Object Tracker - Sometimes you might need to track user attention over multiple objects. For ex; In a real estate scene how long a user is seeing a sofa or did users noticed an advertisement placed in the scene. You can provide multiple game objects which you want to track. The object you want to track must have collider enabled. This creates two event "Object Focus" which shows how much attention user have given to the object and second "Object Gaze" which shows whether user have directly looked at the object. Once you have configured the manager you can add objects that you want to track by
Select "VadRManager" from the Hierarchy tab and see the "Inspector Tab".
In the "Inspector Tab" locate the "Gaze Collector" script.
Now select the layers to ignore in the "Ignore Layer" option of the GazeCollector.
Gear VR Controller Metrics - This event is specific to Gear VR and stores the events when an user interact with "Gear VR Controller" like pressing a button etc. This requires Oculus Utilities for Unity.
Collection Frequency
The Collection Frequency for the default events can be changed by specifying the Time Interval (in seconds). Default Value is 0.2sec (or 200 milliseconds). Setting too low a value for the Time Interval would lead to your application getting busy in collecting the data. On the other hand setting too high a value might lead to loss of precision. A good value for the time interval is 0.2s (or 200 milliseconds).
Configuring Manager
You can configure "VadRManager" automatically to start collecting data for all the scenes together or you can configure it for each scene manually.
Auto Configuring
To configure "VadRManager" automatically follow these steps Select the "VadR" -> "Configure Manager" option from the menu bar. Once you select the option a configuration window will open. The configuration window has various configuration sections as follows
App Settings - These options are specific to the entire application. The various options are :-
App Id - Specify the "App Id" obtained from VadR's web dashboard.
App Token - Specify the "App Token" obtained from VadR's web dashboard.
Dev Mode - Specify whether the data collected should be marked as "Test (Dev)" data or "Live (Prod)" data.
Sending Data - This section specifies when the data needs to be send on the VadR's server for storing and further processing. In case the device is not connected to the internet the data is cached and is send whenever the device becomes online.
Send Periodically - This sends data periodically(after every 20s of application use) to the server.
Send on Pause and Level Load - This sends data on pausing and loading of a level.
Scene Settings - This list all the scenes added to "Build Configuration" of your application. Specify "Scene Id" obtained form VadR's dashboard for each scene.
Select Events - This option is to select all the default event for which you want to collect data. Select all the events that you want to collect data and specify the collection frequency
Fig. SDK Integration: Scene Exporter.
Manually Configuring
"VadRManager" can be configure manually for each scene also. To configure it manually.
Drag "VadRManager.prefab" from "VadRAnalytics->Resources->Prefab" folder in your scene.
Select "VadRManager" from "Heirarchy" tab. Make sure only one "VadRManager" prefab is added to the scene.
From the "Inspector" tab locate "Data Colection Manager" scripts and provide the configuration parameters.
User Camera - The camera responsible for user view. If nothing is specified by default it would take "Camera.Main"
Log Level - Set the "Log Level" to be displayed on console.
Configure Manager - Click on "Configure Manager" and specify other configurations.
The configuration to specify are same as the one in Auto Configure section.
Fig. SDK Integration: Scene Exporter.
Custom Events
Beside the Default Events, developer can register any number of custom events. Each datapoint consists of an event, position of event occurence, optionally Filters and Info can also be associated with it. There are some conventions to be followed while naming Events, Filters and Info.
Naming Convention
Events
Event name shouldn’t start with “vadr”. It is a reserved key word.
Length of an event name should be less than 50 characters.
Event Name shouldn’t contain special characters or “ - ” symbol. Though “_” can be used.
Event Name is case sensitive.
Filters and Info
Length of Filter Key and Info Key should be less than 50 characters.
Length of Filter Value should be less than 50 characters.
Filter Key and Info Key shouldn’t contain special characters. Though “_” can be used.
All Key-Value pairs are case sensitive.
Code Reference
Registering a Custom Event is just small piece of code. You need to use namespace "VadRAnalytics". To register a custom event;
Infos info = new Infos(); //You can also specify the capacity of the Infos.
info.Add(<Info-Key>, <Info-Value>); //Add all the info keys you want to add.
//Note Each Info Key should be unique.
VadRAnalyticsManager.RegisterEvent(<Event-Name>, <Event-Position>, info);
Filters filter = new Filters(); //You can also specify the capacity of the Infos.
filter.Add(<Filter-Key>, <Filter-String>); //Add all the filter keys you want to add.
//Note Each Filter Key should be unique.
VadRAnalyticsManager.RegisterEvent(<Event-Name>, <Event-Position>, filter);
Infos info = new Infos(); //You can also specify the capacity of the Infos.
info.Add(<Info-Key>, <Info-Value>); //Add all the info keys you want to add.
//Note Each Info Key should be unique.
Filters filter = new Filters(); //You can also specify the capacity of the Infos.
filter.Add(<Filter-Key>, <Filter-String>); //Add all the filter keys you want to add.
//Note Each Filter Key should be unique.
VadRAnalyticsManager.RegisterEvent(<Event-Name>, <Event-Position>, filter, info);
360 Videos/Images
From the version "0.2.0" of "VadR Analytics Unity Package" it is possible to collect analytics data for 360 video and images also. For "360 Videos and Images" it is important to know where the users are looking.
In the context of "VadRAnalytics" 360 Video and Images are referred to as "Media". Each "Media" have some properties associated with it. These are
Media Id - Id associated with media. Media Id should be unique for different media in a scene. This is used to identify your medias.
Name - Name provided to the media.
Url - A public url from which this media can be accessed. If there is no such URL then media can be uploaded on VadR's web dashboard latter.
Note :- If an url is specified then make sure CORS Headers are set on the resource to allow "vadr.io" to access it.
Start Media
To start collecting analytics data for 360 Video or Image you need to tell the "VadRAnalyticsManager" when your media has started. This can be done by a single line of code.
VadRAnalyticsManager.StartNewMedia(<Media-Id>, <Media-Name>, <Media-Type>);
//Here Media-Type is an enum and it's possible values can be Media.Type.Video or Media.Type.Image.
Optionally, Media Url can also be provided by using an overloaded method.
VadRAnalyticsManager.StartNewMedia(<Media-Id>,<Media-Url>, <Media-Name>, <Media-Type>);
//Here Media-Type is an enum and it's possible values can be Media.Type.Video or Media.Type.Image.
End Media
When your 360 video or 360 Image has ended you need to tell the "VadRAnalyticsManager" to stop collecting data for that media. This can be done by :
VadRAnalyticsManager.EndMedia();
Other Media Events
In case of 360 Video your video player can have other interactions like pausing, resuming, forwarding. "VadRAnayticsManager" provide support for all those events.
Start Video - To start the video for the first time.
VadRAnalyticsManager.StartVideo();
Pause Video - To pause a video.
VadRAnalyticsManager.PauseVideo();
Resume Video - To resume a video.
VadRAnalyticsManager.ResumeVideo();
Replay Video - To play a video again from the start.
VadRAnalyticsManager.ReplayVideo();
Seek Video - To move (or seek) video to a specific time
VadRAnalyticsManager.SeekVideo(<time>);
//Here time is float variable.
Set Playback Speed - If there is option to increase or decrease the playback speed.
VadRAnalyticsManager.SetVideoPlaybackSpeed(<speed>);
//Here speed is float variable.
User Demographics
Besides all the analytics data that is collected, you can also specify certian data about the user and even for a session of an application to latter segment users on that basis. The data that can be specified is
Id - A unique id associated with the user. If no id is provided then device-id is taken as the unique id.
VadRAnalyticsManager.SetUserId(<userId>);
Age - Age of the user.
VadRAnalyticsManager.SetUserAge(<age>);
Gender - Gender of the user.
VadRAnalyticsManager.SetUserGender(<gender>);
// Here gender is an enum with possible values as User.Gender.MALE, User.Gender.FEMALE, User.Gender.OTHER, User.Gender.UNKNOWN.
Interests - A comma separated list of user interests.
VadRAnalyticsManager.SetUserInterests(<interests>);
// Here interests is comma separated list of user interests.
User Metadata - Besides the above field any custom metadata can also be provided like name, email, etc.
VadRAnalyticsManager.SetUserMetadata(<user-metadata>); // Here metadata is dictionary with key and value as string.
// For Ex;
Dictionary<string, string> userMetadata = new Dictionary<string, string>();
userMetadata.Add("email", "[email protected]");
VadRAnalyticsManager.SetUserMetadata(userMetadata);
Session Metadata - Any custom metadata can also be provided to a specific session. This can be useful in multiplayer scenario when you want to relate sessions for different player in a single game.
VadRAnalyticsManager.SetSessionMetadata(<session-metadata>); // Here metadata is dictionary with key and value as string.
// For Ex;
Dictionary<string, string> sessionMetadata = new Dictionary<string, string>();
sessionMetadata.Add("id", "session_id_1");
VadRAnalyticsManager.SetUserMetadata(sessionMetadata);
Scene Exporter
VadR Scene Exporter lets you export your scene to visualize all your data as heatmaps overlaid on your model. From version "0.2.0" for "VadR Analytics Unity Package" models can be exported and uploaded automatically from Unity itself.
To export and upload scenes from the Unity.
Click on the VadR option in the menu bar and select SceneExporter.
A SceneExporter window should open. Provide "AppToken" obtained from VadR's web dashboard.
Select the option to select the current scene or export multiple scenes together.
In case of exporting multiple scenes select the scenes to be exported. Mention their SceneIds obtained from VadR's web dashboard.
Click on export and Upload. The scenes export process should start.
In case of some error in uploading the scene or if you are not connected to the internet, then scene model can be uploaded manually VadR's web dashboard. The exported file should be loacted in "VadRSceneExporter" folder in your Project Home Folder.
Fig. SDK Integration: Scene Exporter.
Unity Integration
Importing Package
To start using VadR's analytics you need to grab the latest unity package from here.
Go to Assets->Import Package->Custom Package and select the VadRAnalytics package. You would see a VadrAnalytics directory created in your Assets folder.
Fig. SDK Integration: Import Package.
Note :- If you've any previous version of VadRAnalytics package please remove it before importing the new version.
Default Events
There are some default events common to most of the applications that can be collected by VadRAnalyticsManager. You just need to enable them. These events are
Orientation Metrics - This is the user (or Main Camera) orientation or position in the environment. You can plot heatmap of this event to know distribution of user's position in the scene.
Gaze Metrics - This is the point where user (or Main Camera) is directly looking. You can plot heatmap of this event to know distribution of user's gaze in the scene. For collecting Gaze Data you have an option to ignore certain layers where you don't want the gaze data. For example while user is sitting in a car you might be interested in where he is looking outside the car. In such case you can ignore the layer of car glasses. Once you have configured the manager you can ignore the layers by
Select "VadRManager" from the Hierarchy tab and see the "Inspector Tab".
In the "Inspector Tab" locate the "Track Objects" script.
Now in the "Track Objects" option of the script specify the number of objects you want to track.
Specify all the gameobjects that you want to add to the track objects list.
Performane Metrics - This metrics corresponds to how your application is perfroming on different devices. It stores Performance parameters like FPS (Frame Per Seconds), Cpu Usage, Memory Usage, etc. for the application. This event is registered with the name "Performance" and different "info-value" corresponding to each performance parameter.
Object Tracker - Sometimes you might need to track user attention over multiple objects. For ex; In a real estate scene how long a user is seeing a sofa or did users noticed an advertisement placed in the scene. You can provide multiple game objects which you want to track. The object you want to track must have collider enabled. This creates two event "Object Focus" which shows how much attention user have given to the object and second "Object Gaze" which shows whether user have directly looked at the object. Once you have configured the manager you can add objects that you want to track by
Select "VadRManager" from the Hierarchy tab and see the "Inspector Tab".
In the "Inspector Tab" locate the "Gaze Collector" script.
Now select the layers to ignore in the "Ignore Layer" option of the GazeCollector.
Gear VR Controller Metrics - This event is specific to Gear VR and stores the events when an user interact with "Gear VR Controller" like pressing a button etc. This requires Oculus Utilities for Unity.
Rift Controller Metrics - These metrics are specific to Oculus Rift and collects events like Headset Removal, Button Presses, Tracking Lost, etc. Supports pausing data on headset removal. This requires Oculus Utilities for Unity.
Collection Frequency
The Collection Frequency for the default events can be changed by specifying the Time Interval (in seconds). Default Value is 0.2sec (or 200 milliseconds). Setting too low a value for the Time Interval would lead to your application getting busy in collecting the data. On the other hand setting too high a value might lead to loss of precision. A good value for the time interval is 0.2s (or 200 milliseconds).
Configuring Manager
You can configure "VadRManager" automatically to start collecting data for all the scenes together or you can configure it for each scene manually.
Auto Configuring
To configure "VadRManager" automatically follow these steps Select the "VadR" -> "Configure Manager" option from the menu bar. Once you select the option a configuration window will open. The configuration window has various configuration sections as follows
App Settings - These options are specific to the entire application. The various options are :-
App Id - Specify the "App Id" obtained from VadR's web dashboard.
App Token - Specify the "App Token" obtained from VadR's web dashboard.
Dev Mode - Specify whether the data collected should be marked as "Test (Dev)" data or "Live (Prod)" data.
Sending Data - This section specifies when the data needs to be send on the VadR's server for storing and further processing. In case the device is not connected to the internet the data is cached and is send whenever the device becomes online.
Send Periodically - This sends data periodically(after every 20s of application use) to the server.
Send on Pause and Level Load - This sends data on pausing and loading of a level.
Scene Settings - This list all the scenes added to "Build Configuration" of your application. Specify "Scene Id" obtained form VadR's dashboard for each scene.
Select Events - This option is to select all the default event for which you want to collect data. Select all the events that you want to collect data and specify the collection frequency
Fig. SDK Integration: Scene Exporter.
Manually Configuring
"VadRManager" can be configure manually for each scene also. To configure it manually.
Drag "VadRManager.prefab" from "VadRAnalytics->Resources->Prefab" folder in your scene.
Select "VadRManager" from "Heirarchy" tab. Make sure only one "VadRManager" prefab is added to the scene.
From the "Inspector" tab locate "Data Colection Manager" scripts and provide the configuration parameters.
User Camera - The camera responsible for user view. If nothing is specified by default it would take "Camera.Main"
Log Level - Set the "Log Level" to be displayed on console.
Configure Manager - Click on "Configure Manager" and specify other configurations.
The configuration to specify are same as the one in Auto Configure section.
Fig. SDK Integration: Scene Exporter.
Custom Events
Beside the Default Events, developer can register any number of custom events. Each datapoint consists of an event, position of event occurence, optionally Filters and Info can also be associated with it. There are some conventions to be followed while naming Events, Filters and Info.
Naming Convention
Events
Event name shouldn’t start with “vadr”. It is a reserved key word.
Length of an event name should be less than 50 characters.
Event Name shouldn’t contain special characters or “ - ” symbol. Though “_” can be used.
Event Name is case sensitive.
Filters and Info
Length of Filter Key and Info Key should be less than 50 characters.
Length of Filter Value should be less than 50 characters.
Filter Key and Info Key shouldn’t contain special characters. Though “_” can be used.
All Key-Value pairs are case sensitive.
Code Reference
Registering a Custom Event is just small piece of code. You need to use namespace "VadRAnalytics". To register a custom event;
Infos info = new Infos(); //You can also specify the capacity of the Infos.
info.Add(<Info-Key>, <Info-Value>); //Add all the info keys you want to add.
//Note Each Info Key should be unique.
VadRAnalyticsManager.RegisterEvent(<Event-Name>, <Event-Position>, info);
Filters filter = new Filters(); //You can also specify the capacity of the Infos.
filter.Add(<Filter-Key>, <Filter-String>); //Add all the filter keys you want to add.
//Note Each Filter Key should be unique.
VadRAnalyticsManager.RegisterEvent(<Event-Name>, <Event-Position>, filter);
Infos info = new Infos(); //You can also specify the capacity of the Infos.
info.Add(<Info-Key>, <Info-Value>); //Add all the info keys you want to add.
//Note Each Info Key should be unique.
Filters filter = new Filters(); //You can also specify the capacity of the Infos.
filter.Add(<Filter-Key>, <Filter-String>); //Add all the filter keys you want to add.
//Note Each Filter Key should be unique.
VadRAnalyticsManager.RegisterEvent(<Event-Name>, <Event-Position>, filter, info);
360 Videos/Images
From the version "0.2.0" of "VadR Analytics Unity Package" it is possible to collect analytics data for 360 video and images also. For "360 Videos and Images" it is important to know where the users are looking.
In the context of "VadRAnalytics" 360 Video and Images are referred to as "Media". Each "Media" have some properties associated with it. These are
Media Id - Id associated with media. Media Id should be unique for different media in a scene. This is used to identify your medias.
Name - Name provided to the media.
Url - A public url from which this media can be accessed. If there is no such URL then media can be uploaded on VadR's web dashboard latter.
Note :- If an url is specified then make sure CORS Headers are set on the resource to allow "vadr.io" to access it.
Start Media
To start collecting analytics data for 360 Video or Image you need to tell the "VadRAnalyticsManager" when your media has started. This can be done by a single line of code.
VadRAnalyticsManager.StartNewMedia(<Media-Id>, <Media-Name>, <Media-Type>);
//Here Media-Type is an enum and it's possible values can be Media.Type.Video or Media.Type.Image.
Optionally, Media Url can also be provided by using an overloaded method.
VadRAnalyticsManager.StartNewMedia(<Media-Id>,<Media-Url>, <Media-Name>, <Media-Type>);
//Here Media-Type is an enum and it's possible values can be Media.Type.Video or Media.Type.Image.
End Media
When your 360 video or 360 Image has ended you need to tell the "VadRAnalyticsManager" to stop collecting data for that media. This can be done by :
VadRAnalyticsManager.EndMedia();
Other Media Events
In case of 360 Video your video player can have other interactions like pausing, resuming, forwarding. "VadRAnayticsManager" provide support for all those events.
Start Video - To start the video for the first time.
VadRAnalyticsManager.StartVideo();
Pause Video - To pause a video.
VadRAnalyticsManager.PauseVideo();
Resume Video - To resume a video.
VadRAnalyticsManager.ResumeVideo();
Replay Video - To play a video again from the start.
VadRAnalyticsManager.ReplayVideo();
Seek Video - To move (or seek) video to a specific time
VadRAnalyticsManager.SeekVideo(<time>);
//Here time is float variable.
Set Playback Speed - If there is option to increase or decrease the playback speed.
VadRAnalyticsManager.SetVideoPlaybackSpeed(<speed>);
//Here speed is float variable.
User Demographics
Besides all the analytics data that is collected, you can also specify certian data about the user and even for a session of an application to latter segment users on that basis. The data that can be specified is
Id - A unique id associated with the user. If no id is provided then device-id is taken as the unique id.
VadRAnalyticsManager.SetUserId(<userId>);
Age - Age of the user.
VadRAnalyticsManager.SetUserAge(<age>);
Gender - Gender of the user.
VadRAnalyticsManager.SetUserGender(<gender>);
// Here gender is an enum with possible values as User.Gender.MALE, User.Gender.FEMALE, User.Gender.OTHER, User.Gender.UNKNOWN.
Interests - A comma separated list of user interests.
VadRAnalyticsManager.SetUserInterests(<interests>);
// Here interests is comma separated list of user interests.
User Metadata - Besides the above field any custom metadata can also be provided like name, email, etc.
VadRAnalyticsManager.AddUserMetadata(<user-metadata>); // Here metadata is dictionary with key and value as string.
// For Ex;
Dictionary<string, string> userMetadata = new Dictionary<string, string>();
userMetadata.Add("email", "[email protected]");
VadRAnalyticsManager.AddUserMetadata(userMetadata);
// This adds the field email to user metadata
Session Metadata - Any custom metadata can also be provided to a specific session. Metadata is a key-value pair. Here key can be string or float. This can be useful in multiplayer scenario when you want to relate sessions for different player in a single game.
VadRAnalyticsManager.AddSessionMetadata(<session-metadata>); // Here metadata is dictionary with key as string and value can be string or float.
// For Ex;
Dictionary<string, string> sessionMetadata = new Dictionary<string, string>();
sessionMetadata.Add("id", "session_id_1");
VadRAnalyticsManager.AddSessionMetadata(sessionMetadata);
// This adds the metadata "id" to the session.
Scene Exporter
VadR Scene Exporter lets you export your scene to visualize all your data as heatmaps overlaid on your model. From version "0.2.0" for "VadR Analytics Unity Package" models can be exported and uploaded automatically from Unity itself.
To export and upload scenes from the Unity.
Click on the VadR option in the menu bar and select SceneExporter.
A SceneExporter window should open. Provide "AppToken" obtained from VadR's web dashboard.
Select the option to select the current scene or export multiple scenes together.
In case of exporting multiple scenes select the scenes to be exported. Mention their SceneIds obtained from VadR's web dashboard.
Click on export and Upload. The scenes export process should start.
In case of some error in uploading the scene or if you are not connected to the internet, then scene model can be uploaded manually VadR's web dashboard. The exported file should be loacted in "VadRSceneExporter" folder in your Project Home Folder.
Fig. SDK Integration: Scene Exporter.
AFrame Integration
Importing Package
To integrate VadR Analytics, depending on how you are creating your application, you can either include our analytics module using npm or directly include our prebuild script in your html code.
Using npm
Install our npm module using the following command.
npm install --save vadr-aframe-vr
Import our package into your code using the below code. You can then access our apis using the 'VADR' keyword.
import VADR from 'vadr-aframe-vr'
Using script
You can also directly include our script in your html file using the below script tag. You can then access our apis using the 'VADR' keyword.
The above script registers our custom component with AFrame. Therefore make sure that the script is included after AFrames script.
Once our SDK is included, you can start collecting data by creating an a-entity with our custom component 'vadr-analytics' within your a-scene. This can be done by specifying our component within your scenes HTML or at runtime using javascript. Make sure that VadRs script is available before you add our custom component. When included our custom component should look like below.
Our component needs the following parameters to inititalize:
appId: application id provided to you after registering your application on our platform
appToken: application token provided to you on the platform
sceneId: scene id of the scene for which data needs to be collected, if registered from VadRs dashboaard
sceneName: scene name of the scene for which data needs to be collected, scene auto registers if no scene id is provided
testMode: set this to true during development. This is done so that the data collected during application development does not interfare with production data. Default value is false.
version: set this to your current application version. This is done so that collected data can be viewed based on your application versions. Default value is "1.0.0".
Setting Camera
The SDK fetches the default camera set the AFrame. If you are creating VadRs AFrame component using javascript or are manually setting the camera, you need to register it using the following function.
VADR.setCamera(AFrameCameraObject);
Default Events
There are some default events common to most of the applications that can be collected by VadRAnalytics. These events are
Position - This is the user (or Main Camera) position in the environment. You can plot heatmap of this event to know distribution of user's position in the scene.
Gaze - This is the point where user (or Main Camera) is directly looking. You can plot heatmap of this event to know distribution of user's gaze in the scene.
FPS - Frame Per Seconds(FPS) is the performance metrics of your application. Higher the FPS the better is user experience. This event is registered with an Info Value, use this info to get the FPS in the scene.
Collection Frequency
By default Position and Gaze events are collected every 300 milliseconds while the FPS is collected every one seconds. You can customize which event should be collected and with what time interval. Setting too low a value for the Time Interval would lead to your application getting busy in collecting the data. On the other hand setting too high a value might lead to loss of precision. A good value for the time interval is 300 milliseconds.
The above code specifies informs the SDK that orientation and gaze need to be collected every 500 milliseconds. The last line directs the SDK to not collect FPS (performance) data.
Custom Events
Beside these Default Events, developers can register any number of custom events. Each event datapoint consists of an event name, position of event occurence and optionally Filters & Info. There are some conventions to followed while naming Events, Filters and Info.
Naming Convention
Events
Event name shouldn’t start with “vadr”. It is a reserved key word.
Length of an event name should be less than 20 characters.
Event Name shouldn’t contain special characters or “ - ” symbol. Though “_” can be used.
Event Name is case sensitive.
Filters and Info
Length of Filter Key and Info Key should be less than 20 characters.
Length of Filter Value should be less than 30 characters.
Filter Key and Info Key shouldn’t contain special characters. Though “_” can be used.
All Key-Value pairs are case sensitive.
Registering Custom Events
Any custom event can be registered by calling the registerEvent function. It takes three parameters as input, event name, 3D position array of the form [x,y,z] and an extra dictionary containing filter and info key value pairs. If the provided value is a float, it is considered as information and if the provided value is a string, it is considered as a filter.
VADR.registerEvent(eventName, position, extra);
The following examples should clarify the funtions behaviour.
Here we provide two key-value pairs in the extra dict. Similar to second and third examples, 'damage' is taken as information and 'gunUsed' is considered as filter.
Scenes and Media
The scenes and 360 media for which data is being collected can be changed on the fly using functions exposed by the SDK. One thing to note is 360 media exist within scene, therefore a scene must exist in scope before a media is registered.
Scenes
The following functions are used to manage scenes. The add scene function takes sceneId as input and starts data collection for the new scene. You can also optionally provide a scene name. The close scene closes data collection for the current scene.
You can start and close data collection to 360 media anytime. You should also register events such play, pause and seek change for proper data collection.
mediaId: Unique id with which you identify the media within your application
media Name: Name of the media which should be displayed while viewing the data
type: Type of media. Use 'Video' for 360 video and 'Image' for 360 image.
url: Optional url which can be used to retreive the media when viewing data. If not provided at runtime, you can also mention the url or upload the media from our dashboard.
You can close the media by calling the following function:
VADR.media.closeMedia();
To register events such as play, pause and change seek use the following functions. Keep in mind, these functions should be called with actual play, pause, seek change events for correct data collection.
Extra information and the current session can be set using the below functions. These are supplied in the form of string key value pairs. The maximum length of the key can be 50 characters, while the maximum length of value strings can be 256 characters. You also assign a specific id to the user, to identify him while visualizing information. If not specified, the SDK itself generates a random userid.
Events such as headset applied and headset removed are automatically handled. By default data collection is paused on headset removal and resumed when headset is applied bcak. You can change this behaviour by calling the pauseOnHeadsetRemove and dontPauseOnHeadsetRemove functions. Other events such as when application is paused, or when it is resumed, need to be trigger to pause/resume data collection and show the correct timing.
There might be cases where you have some objects (such as text, hotspots etc.) being displayed over the 360 Image. Media heatmaps in this case will only displayed on the equirectangular projection of the 360 image, and any impact of the overlying objects on the heatmaps will not be visible.
Such cases can be handled by using an alternate 360 image to display heatmaps. The alternate 360 image is extracted from within your ThreeJs scene and contains the objects displayed on top of the original. VadR provides a modified version of Jaume Sanchez Elias' script which makes it easy to take out such 360 images.
const equirectangularExtractor = new CubemapToEquirectangular( renderer, true );
Step 3 - When your scene is ready, point your main camera to direction which is the center point in your original 360 image, and call the following funciton.
equirectangularExtractor.update( camera, scene );
Accessing Data
Quick Reports
This contains the most important metrics and information of an application for a quick access. This also contains settings to upload scene model or add more scene.
Metrics
Users – These are the unique users (for each day) who used your application in the given time frame.
New Users – These are the unique users who used your app for the first time in the given time frame.
Sessions – These are the total number of times your application was used in the given time frame. If a user uses the application again within ten minutes of previous session it is counted as the same session.
Avg. Time – This the average length of time for which your application was used in the given period.
Monthly Users – This is the number of unique users who were active in your application for a given month over the last one year.
User Retention – It is the ratio of daily active users and monthly active user (MAU) for the month corresponding to that day. This ratio helps in understanding your app retention. A ratio of 1 means the same set of users were using your application again and again in the month or 100 percent retention.
Session Locations – This shows the locations of your application users (sessions) in an interactive map. You can know where your application is used the most and geography where you need to focus.
Session by Operating System – This shows the comparative session of your applications use on different operating systems.
Application Scenes (or Levels)
List of all the scenes registered for your application with important details like number of sessions for the scene, number of users and average playing time for the scene. This gives a quick overview of which scenes your users are most interested and where they seems to be dropping off.
Settings
It contains information required for integrating the SDK and give access to other users registered with Vadr to view your application reports.
Application Id – Your application Id. To be used in unity for integration.
Application Token – A unique token for your application, to be used for integration.
Scenes – A list of scenes registered for the application, with their scene ids (Use these ids for SDK integration).
There is an option for uploading your scene for visualizing the heatmap of your model. Scenes can be uploaded manually or directly from the SDK.
Media files can also be added for the corresponding scene for overlaying heatmaps on them.
You can add more scenes to your application later.
Access Control – A place to control the access to your application. You can invite new users to view your application stats and give them either Admin or Viewer roles. You can also remove user access.
Admin – An admin user has all access to your application. He can add or remove users, add new scenes, add or remove graphs/heatmaps, etc.
Viewer – A viewer has only viewing authority on an application. He can’t modify or change anything. If you are not sure of what role to provide to a new user, it’s safe to make him a viewer.
Fig. Settings of an Application.
Data Visualisation
We provide customizable Graphs and Heatmaps to help you visualize your data in depth. Some of the terminologies associated with them are
Panels - An individual heatmap/graph is known as a panel. An admin can add, delete or edit a panel. Each panel have a few options
Title - Title of the panel for easy identification.
Settings - Settings are visible to only admin users. You can edit or delete a panel from here.
Expand - This option is available only in Heatmaps. It is use to see expanded version of the heatmap for easier access.
Tab - Tabs are used to group similar kind of panels together. An admin can add, delete a tab.
Time Frame- The time frame for which data is shown. By default the time frame is last 7 days. Any user can change this to visualize data for a custom time frame.
Fig. Sample Heatmaps of an Application with Screen Details.
Graphs
2D Graphs are the best ways to quantitatively visualize and compare all your app data. There are different types of graphs that can be plotted
Graph Types
Line Graph v/s Scene Time - In this kind of Line graph you can visualize how data is changing with respect to the time since start of the scene (Scene Time). Information for multiple scenes can be viewed together.
For Ex - Graph for visualizing how Frames Per Second change with respect to Scene Time.
Fig. Line Graph v/s Scene Time.
Line Graph v/s Date - In this kind of Line Graph you can visualize how data is changing with respect to calender date of application usage. Information for multiple scenes can be viewed together.
For Ex - Graph for visualizing the In App Purchases with respect to Actual Time.
Fig. Line Graph v/s Date.
Bar Graph v/s Filters - In this kind of graph we can plot any information associated with an event on a bar graph for different Filter Values to compare them quantitatively. In this kind of graphs only a single Filter Key can be applied(but there could be multiple Filter Values). Information for multiple scenes can be viewed together.
For Ex - Graph for comparing the time a user stays at different location.
Fig. Bar Graph v/s Filters.
Pie Graph v/s Filters - In this kind of graph we can plot any information associated with an event on a pie chart for different Filter Values to compare them qualitatively. In this kind of graphs only a single Filter Key can be applied(but there could be multiple Filter Values). Information can be viewed for a single scene only, or all the scenes combined.
For Ex - Graph for comparing the time a user stays at different location.
Fig. Pie Graph v/s Filters.
Download Data
Data can be downloaded for a given graph panel as a ".csv". This data then can be used for further analysis in tools like Excel, Tableau, etc. To dowload the data for a panel just click on settings button on a panel and select "Download Data" option.
Add / Edit Graphs
An admin user can add or edit a graph panel.
Options involved for add/editing graphs are
Panel Title - The title of the panel that you want to show.
Information - The information that you want to show. It is the combination of Event Name and Event Info separated by “-”. For visualizing the number of occurrence of the event select “<Event-Name> - Count”.
Plot Type - The type of plot that you want to show. Different plot types are explained here.
Aggregate - Function to aggregate different datapoints in the same bucket. For ex - Aggregating data over a day. The different aggregating functions are
Sum - It’s a simple sum over all datapoints. For ex; Graph for visualizing total revenue from the In App Purchases.
Average - It’s a simple Average over all datapoints. For ex; Graph for visualizing the average revenue earned (or the average amount) from each in-app purchase made by the user.
Average Over Session - This function takes sum of datapoints in each session and then takes average of the resultant values over all the sessions. For Ex; Graph for visualizing the average revenue earned (amount spent by user) via in-app purchases in each app session.
Average Over Session is not available while plotting a scene time graph.
Scenes - A list of all the scenes registered for an application for which data can be plotted. Select multiple scenes to compare between them in the same plot.
Filters - Filters(Key, Value pair) that can be applied to an information to plot data. For ex - Graph of number of enemies killed with “Machine Gun”.
Are visible only if the selected event has filters associated with it.
Using these options data for any simple or complex queries can be plotted. For Ex; Say Plot of time taken to kill “Enemy 1” from “Machine Gun” in Scene 1 and Scene 2 wrt to scene time.
Fig. Adding Panels.
Heatmaps
Heatmaps are the best way to not only visualize your data on the map but also see where the majority of your event are occuring in your scene. For ex: what are the prominent locations where users die in a game, etc.
Heatmap Types
Gaze Heatmap - Good for events which occur close to surfaces of your content's 3D model such as Gaze, which is located on the surface of objects (eg. a cars body) looked at by a user.
Fig. Gaze Heatmap.
Movement Heatmap - Use them to visualize heatmap of movement of an event within the 3D model. For example, Movement of users (Event - Position) within the model.
Fig. Movement Heatmap.
Custom Heatmap - Good for visualizing events generated in the empty spaces of the 3D model, such as flying drones shot down in the sky, or headshot kills made by the user.
Fig. Custom Heatmap.
Download Data
Data can be downloaded for a given heatmap panel as a ".csv". This data then can be used for further analysis in tools like Excel, Tableau, etc. To dowload the data for a panel just click on settings button on a panel and select "Download Data" option.
Add Heatmaps
Options to add heatmap panels are similar to options to add graph panels.
Expanding Heatmaps
The expanded version of the heatmap makes it easy to access data in detail. There are various options to make interaction with the model easy.
Map Scanner - Map Scanner is an innovative tool that allows you to quickly get the details of activity happening in a region. Select the scanner tool and move your mouse to get the instant details about percentage of sessions, average count, total count of the event in a region.
Scene Time Slider - Option to change the time of application usage to see how the event progresses with scene time/video time.
Date Selector - Select the date to see data in the given time range.
Settings - Different parameters to set heatmap. Change scale of the heatmap. Or save a pre-defined view for the heatmap.
View Selection - Select from a pre-saved view to change the orientation of the heatmap.
Panel Selection - A list of all the panels added for the same scene. Select panel to quickly jump to that heatmap at the same orientation.
