VadR - VR Analytics (Docs)

Getting Started

Collecting Data

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.


Registering App
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.


App List
Fig. App List.

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.
Plugin Directory
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.
        PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "VadRAnalytics"});
        PrivateDependencyModuleNames.AddRange(new string[] {"Json","JsonUtilities","VadRAnalytics"});
        PrivateIncludePathModuleNames.AddRange(new string[] {"VadRAnalytics"});
  • Add the VadRAnalytics Source file in "YourProject.h" file.
       #include "IVadRAnalytics.h"
  • Open "YourProject.uproject" with a text editor and add the following Plugins to it.
    {
        "FileVersion": 3,
        "EngineAssociation": "4.15",
        "Category": "",
        "Description": "",
        "Modules": [
            {
                "Name": "YourProject",
                "Type": "Runtime",
                "LoadingPhase": "Default",
                "AdditionalDependencies": [
                    "Engine"
                ]
            }
        ],
        "Plugins": [
            ...
            {
                "Name": "VadRAnalytics",
                "Enabled": true
            }
            ... 
        ]
    }
  • 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.

  • VadR Analytics Plugin
    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).
DataCollector
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.

  • DataCollector Details
    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;
  • Event with no Info or Filters
    IVadRAnalytics::Get().RegisterEvent(<Event-Name>, <Event-Position>, <scene-time>);
  • Event with Info but no Filters
    IVadRAnalytics::Get().RegisterEvent(<Event-Name>, <Event-Position>, <Info>, <scene-time>);
    Here Info is a Dictionary with key as FString and value as float.
  • Event with no Info but Filters
    IVadRAnalytics::Get().RegisterEvent(<Event-Name>, <Event-Position>, <Filters>, <scene-time>);
    Here Filters is a Dictionary with key and value as FString.
  • Event with both Info and Filters
    IVadRAnalytics::Get().RegisterEvent(<Event-Name>, <Event-Position>, <Info>, <Filters>, <scene-time>);
    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).

  • Register Event Blueprint
    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).

  • Register Event with Info Blueprint
    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).

  • Register Event with Filters Blueprint
    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).

  • Register Event with Info and Filters Blueprint
    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.

C++ Code

  • Starting Event
            FString eventId = IVadRAnalytics::Get().StartEvent(<Event-Name>);
  • Starting Event With Filter
            FString eventId = IVadRAnalytics::Get().StartEvent(<Event-Name>, <Filters>);
    Here Filters is a TMap with key and value as FString.
  • Starting Event With Info
            FString eventId = IVadRAnalytics::Get().StartEvent(<Event-Name>, <Info>);
    Here Info is a TMap with key as FString and value as float.
  • Starting Event With Info and Filter
            FString eventId = IVadRAnalytics::Get().StartEvent(<Event-Name>, <Info>, <Filters>);
    Here Info is a TMap with key as FString and value as float, Filter is a TMap with key and value as FString.
  • Ending Event
            IVadRAnalytics::Get().EndEvent(<Event-Id>, <Event-End-Position>, <scene-time>);
    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.

  • Start Event
    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)

  • Start Event with Info
    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).

  • Start Event with Filters
    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).

  • Start Event with Info and Filters
    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.

  • End 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.

  • Export Scene
    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
      •    IVadRAnalytics::Get().ExportLevel(<actor-pointer>);
        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.

    • Export Scene
      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)

    • Export Scene
      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.
  • SDK Integration: Import Package
    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.
  • SDK Integration: Import Package
    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;
  • Event with no Info or Filters
            AnalyticsManager.registerEvent(<Event-Name>, <Event-Position>);
  • Event with Info but no Filters
            AnalyticsManager.registerEvent(<Event-Name>, <Event-Position>, <Info>);
    Here Info is a Dictionary with key as string and value as float.
  • Event with no Info but Filters
            AnalyticsManager.registerEvent(<Event-Name>, <Event-Position>, <Filters>);
    Here Filters is a Dictionary with key and value as string.
  • Event with both Info and Filters
            AnalyticsManager.registerEvent(<Event-Name>, <Event-Position>, <Info>, <Filters>);
    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

  • Starting Event With No Filter
            string eventId = AnalyticsManager.startEvent(<Event-Name>);
  • Starting Event With Filter
            string eventId = AnalyticsManager.startEvent(<Event-Name>, <Filters>);
    Here Filters is a Dictionary with key and value as string.
  • Ending Event
            AnalyticsManager.endEvent(<Event-Id>, <Event-End-Position>);
    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.
SDK Integration: Scene Exporter
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.
        VadrSceneExporter.ExportModel("<Directory-Name>");

Changes In Manifest

For Analytics SDK to work on Android you need to following lines to your android manifest file.
    <activity android:name="com.vadrnet.unitysdk.MainActivity" 
              android:label="@string/app_name">
    </activity>
    <activity android:name="com.vadrnet.unitysdk.WebViewActivity" 
              android:label="@string/app_name" 
              android:screenOrientation="landscape" 
              android:hardwareAccelerated="true" 
              android:exported="true">
    </activity>
Also add the following permissions
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

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.

  • SDK Integration: Import Package
    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
    SDK Integration: Configuration Options
    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.
    SDK Integration: VadRManager Inspector
    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;
    • Event with no Info or Filters
              VadRAnalyticsManager.RegisterEvent(<Event-Name>, <Event-Position>);
    • Event with Info but no Filters
              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);
    • Event with Filters but no 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);
    • Event with both Info and Filters
              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", "contactus@vadr.io");
        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.

SDK Integration: Scene Exporter
Fig. SDK Integration: Scene Exporter.

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.


Settings
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.


Sample Heatmaps
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.

  • Line Graph v/s Scene
    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.

  • Line Graph v/s Date
    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.

  • Bar Graph v/s Filters
    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.

  • Pie Graph v/s Filters
    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.


Adding Panels
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.

  • Gaze Heatmap
    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.
    Movement Heatmap
    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.
    Custom Heatmap
    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.

  • Expanded Heatmap
    Fig. Expanded Heatmap.