Follow

Integrating the Apmetrix Unity SDK (Addendum for Virtual Reality Applications)

** Platforms Officially Supported For VR **

  • Editor
  • Windows PC

** Important Note **

  • This document is intended to be an addendum to the base document "Integrating the Apmetrix Unity SDK", where we describe the steps necessary to integrate the Apmetrix Unity SDK into your Virtual Reality application.  Those API methods unique to VR application analytics will be discussed in detail here.  Please refer to "Integrating the Apmetrix Unity SDK" for detail on all other API methods. 
  • In addition this document describes integration for Revisions 2.1.4 or greater of the Apmetrix Unity SDK. 
  • Prior to revision 2.1.4, offline caching of VR application analytic events was not supported.  That is no longer the case starting with revision 2.1.4. 

Table of Contents

 

1. Getting the ApmetrixUnity SDK (for Virtual Reality Applications)

 Untitled1.png

  • Navigate to the downloaded extracted zip archive that contains the ApmetrixUnityPack(VR) Unity Package file, select it and click Open. 

  • This will bring up the Importing Package window.

  • Make sure all the checkboxes are selected by pressing "All" and then press "Import".  This will import the required files/folder structure into your Unity project.
  • You should now see the following folder structure in your Assets Directory.

 

2. Getting the SteamVR Plugin

If you're already using the SteamVR plug-in in your virtual reality application then you're ready for Integrating the ApmetrixUnity Plugin.

With your project open in the Unity Editor click on the Asset Store tab at the top of the editor.  Search for "SteamVR Plugin".  Once found double click on the icon to initiate the download/import of the plugin.

  • This will bring up the Importing Package window.

  • Make sure all of the checkboxes are selected by pressing "All" and then press "Import". This will import the required files/folder structure into your Unity Project.
  • You should now see the following folder structure in your Assets Directory.

 

3. Integrating the ApmetrixUnity Plugin

Add the [ApmetrixVR] Prefab to the Scene

  • To begin using the ApmetrixUnity plugin, find the ApmetrixVR prefab in the Assets->Apmetrix->Prefabs directory.

  • Drag an instance of this prefab into the hierarchy window for the scene where you want to start using analytics.  
  • An example of this can be seen in one of the provided sample test scenes.  Save your scene first then in the Project Tab, click Assets->Apmetrix->Samples and double click VRTestScene to open up the Apmetrix Unity VRTestScene.    
      

  • *Note: This object will need to persist throughout your game/app.
  • Do not re-create this object for each scene or you may experience oddities when using the SDK.

Add the [CameraRig] Prefab to the Scene

  • To begin using the CameraRig plugin, find the CameraRig prefab in the Assets->SteamVR->Prefabs directory.

  • Drag an instance of this prefab into the hierarchy window for the scene where you want to start using VR analytics.  With the VRTestScene still open you can see an example of how the "[CameraRig]" prefab was added to the scene.

Setting up GameObjects to be Tracked

If you have game objects in your scene that you would like to know whether they're being looked at, how many times they were looked at and for how long, you'll need to do the following.

Either statically or dynamically, for each game object you want to track:

  • add the ApmetrixVRTrackedObject script as a component,
  • enable the game object,
  • enable Object Tracking,
  • if desired, assign a tag name to the tracked object  

Adding the Apmetrix VR Tracked Object Script to GameObjects

With the VRTestScene open notice how the Capsule, Cube, Cylinder and Sphere game objects in the scene each have the ApmetrixVRTrackedObject script added.   

This is a case of statically adding the ApmetrixVRTrackedObject script to the game object.  To be able to do the same for game objects in your scene, click Assets->Apmetrix->Scripts and drag ApmetrixVRTrackedObject.cs onto each game object you want to track.

To dynamically add this script to your game object during game play you would include the following code in at least one of the game objects's MonoBehavior scripts:

gameObject.addComponent<ApmetrixVRTrackedObject>();

Enabling the GameObject

When a game object is enabled the added script registers it as a possible "tracked game object".   Conversely when a tracked game object is disabled it is de-registered as a possible tracked game object.

*NOTE: If the ApmetrixVRTrackedObject script is added dynamically during game play then it must be done before the game object is enabled.    

Enabling Object Tracking

Assign a Unique Tag Name to the Tracked Object

When the SDK determines the user is looking directly at a tracked game object that object's path and tag name are captured.  The game object's path will always be unique.  Assigning a unique tag name is important when tracking a group of game objects of the same type.  If the object is unique or doesn't belong to a group then the tracked object tag name can be left as it default value which is "Undefined".

Setting the Static Apmetrix Apmetrix Variables

Select the Apmetrix game object in the hierarchy and in your Inspector pane you can set the Apmetrix variables necessary to initialize your analytics session.

First make sure the Apmetrix script is enabled.  This is done by default but can be double checked by making sure the check box to the left of component name, Apmetrix (Script), is enabled.  When the Apmetrix script is enabled in this manner the session will be initialized automatically when the application launches and any paused timers (if there are any) will be resumed.
 
The values to enter in the fields for Application Dataset and Application Unifier were what was given when you registered a new account or added a game to your company.  
  • If you have already registered these values can be found in the dashboard under Tasks->Administration->Accounts and expanding Datasets, then select your dataset.  
  • If you haven't already registered you can press the "Haven't registered yet?" button where you will be directed to the Apmetrix SignIn page where you can do so.
  • The Child Safe permission will override previously made settings for GEO lookup.
  • The interval at which the frame rate is automatically logged can be set by moving the slider for Frame Rate Reporting Interval to any value between 5 and 120 seconds.  By default the frame rate is automatically logged every 30 seconds.

See the following table for more detail on the Apmetrix permission settings that can be made in the Editor:

 

Allow GEO Lookup

By default the SDK will not track GPS.

Check this permission if you wish to track Long/Lat of a customer.

Make Child Safe

 

A convenience permission that disallows GEO lookup, IP Tracking, UDID Tracking and IDFA Tracking.

Allow URL Logging

A convenience permission that should only be set to aid non-production debug testing. 

*NOTE: Make sure this permission is not set for Production.

Offline Mode

A convenience permission that should only be set to aid non-production debug testing.  If set, all Apmetrix API methods are fully functional and the SDK is fully exercised but data collected is not sent to the server.

*NOTE: Make sure this permission is not set for Production. 

Setting the Static Apmetrix VR Tracking Variables

Again select the Apmetrix game object in the hierarchy and in your Inspector pane you can set the Apmetrix VR Tracking variables necessary for both Eye Tracking and Object Tracking.  

You can choose to use the default values or you can change them to suit your application's needs.

See the following table for details on Eye Tracking Settings:

 

 

Track Eye Movement

When set, the SDK will be configured so Eye Tracking is always enabled.  

If set, any call to enable/disable Eye Tracking via the API will be ignored and the API status return value will indicate a warning.

 

 

 

Tracks Per Second

The value entered for "Tracks Per Second" is converted to a float.  Increasing this value will give finer detail in head movement at the cost of collecting an increasingly larger amount of data.  Conversely decreasing this value will result in a more coarse reflection of head movement in the data.

By default the position and orientation of the HMD is sampled once per second.  

 

 

Bounding Radius

 

The value entered for "Bounding Radius" is converted to a float.  If the difference in HMD position and orientation from one sample to the next exceeds this value then the data for that sample is saved otherwise it is ignored.  The Bounding Radius is used primarily to filter out noise.  Increasing this value means larger movement in the position and orientation of the HMD is needed before the sample is considered thus causing a more coarse reflection of head movement throughout the period data is collected.  A decrease of this value will result in more data collected that might otherwise be considered just slight head movement as opposed to conscious movement of the head.

By default the Bounding Radius is 3.  

 

Data Upload Interval (secs)

The value entered for the "Data Upload Interval" is converted to a float.  This is the maximum time in seconds between uploads of Eye Tracking data.  The quantity of data collected might cause uploads to occur more frequently therefore increasing this interval might not have any effect.  Decreasing this interval may cause an increase in data uploads 

By default the Data Upload Interval is 10 seconds.

 

Show Tracking Cursor

*NOTE: For debugging only.  Make sure this is not set for Production.

When set a cursor is displayed in the headset and on the screen to show the point within the scene that data collection is being considered.

By default the cursor is turned off. 

See the following table for details on Object Tracking Settings:

 

 

Track Game Objects Viewed

When set, the SDK will be configured so Object Tracking is always enabled.  

If set, any call to enable/disable Object Tracking via the API will be ignored and the API status return value will indicate a warning.

 

 

 

Data Upload Interval (secs)

The value entered for the "Data Upload Interval" is converted to a float.  This is the maximum time in seconds between uploads of Object Tracking data.  The quantity of data collected might cause uploads to occur more frequently therefore increasing this interval might not have any effect.  Decreasing this interval may cause an increase in data uploads 

By default the Data Upload Interval is 10 seconds.

 

Show Tracking Cursor

 

*NOTE: For debugging only.  Make sure this is not set for Production.

When set a cursor is displayed in the headset and on the screen to show the point within the scene that data collection is being considered.

By default the cursor is turned off. 

3. Accessing the Apmetrix Interface Functions

Base Apmetrix Interface Functions

To see an example of how to access the base Apmetrix API functions in code, click Assets->Apmetrix->Samples and double click TestScene.cs to open up the script file in your IDE.  A detail description of how this script works can be found in "Integrating the Apmetrix Unity SDK"

Virtual Reality Apmetrix Interface Functions

To see an example of how to access the Apmetrix API functions for virtual reality applications, view one of the sample scenes provided.  This will require you to save the current scene you are working on first.  

  • In the Project Tab, click Assets->Apmetrix->Samples and double click VRTestScene to open up the Apmetrix Unity VRTestScene.  You'll notice the Hierarchy view includes the "[ApmetrixVR]" prefab game object discussed in the section Integrating the ApmetrixUnity Plugin.  
  • Double click VRTestScene.cs to open up the script file in your IDE.
  • Viewing VRTestScene.cs in your IDE you'll see how an instance of the Apmetrix object was obtained in the script's Start() method.  This instance was then used when making calls into the Apmetrix API.   
  • An instance of the Apmetrix object can be obtained for each of your MonoBehavior scripts where you want to make calls into the Apmetrix API.
  • It is important the instance of the Apmetrix object be obtained in your script's Start() methods rather than the Awake() methods to guarantee the instance variable has been set before your script tries to use it.
  • Below is the example of how the Instance Object was setup for VRTestScene.cs.

4. Understanding the Apmetrix Interface Functions

Base Analytics Functions

The following base analytic activity is supported in the Unity SDK.  Refer to "Integrating the Apmetrix Unity SDK" for details on the functions to call to perform these activities. 

  • Initialize Session - initializes the session, sending device information.  The function associated with this activity is called automatically when the Apmetrix script instance is loaded and therefore does not have to be called explicitly.
  • Custom Events - used to log custom events using up to 25 dimensions and 20 metrics to accurately describe the event.
  • ApTrak - used to track user interaction, logging the world coordinates for a specified event at a specified scene.
  • Set ApTrak Bundle Count - used to set how many ApTrak events to bundle before sending the data to the server.
  • In App Purchase - used to log a purchase made with real currency (as opposed to virtual currency):
  • Virtual Item - used to log virtual item transactions.
  • Virtual Currency - used to track the flow of virtual in-game currency.
  • Offers - use to log offers that are presented/accepted/declined.
  • Customer ID - used to track a customer ID so it can be correlated with the rest of the data being tracked on this device for this user.
  • Timers - used to start and stop timers needed to track how long events occurred.
  • Start Level - used to track how long a player has spent in a particular level.
  • Set Location - used to track a players movement in the application from one location to another and how long they spent at any particular location.
  • Restart Session - restarts a session when the application comes back into focus (when it returns from the background). Like the Initialize Session activity, the function associated with restarting a session does not have to be called explicitly.
  • End Session - ends a session when either the application looses focus (when it goes into the background) or when the application quits.  Like the Initialize Session and Restart Session activity, the function associated with ending a session does not have to be called explicitly.

VR Analytics Functions

Track Eye Movement

Position and orientation of the HMD (head mounted display) is tracked for as long a period of time as eye 'tracking is enabled.  If the SDK hasn't already been configured where Eye Tracking is always enabled, call the following method in the ApmetrixWrapper GameObject to enable/disable automatic eye tracking:

apmetrixObj.EnableVREyeTracking(bool enable);

*Note: Refer to the discussion in Setting the Static Apmetrix VR Tracking Variables  to see how to configure the SDK to always track eye movement.

Example (to start tracking head mounted display position and orientation):

apmetrixObj.EnableVREyeTracking(true);

Track GameObjects

Time spent directly gazing at Game Object's is tracked for as long a period of time as object tracking is enabled.  If the SDK hasn't already been configured where Object Tracking is always enabled, call the following method in the ApmetrixWrapper GameObject to enable/disable automatic game object tracking:

apmetrixObj.EnableVRObjectTracking(bool enable);

*Note: Refer to the discussion in Adding the Apmetrix VR Tracked Object Script to GameObjects  to see how to expressly setup which game objects can be tracked in this manner.

*Note: Refer to the discussion in Setting the Static Apmetrix VR Tracking Variables  to see how to configure the SDK to always track game objects.

Example (to stop tracking the time spent directly gazing at game objects):

apmetrixObj.EnableVRObjectTracking(false);

5. Function Return Values

Each function returns an "int" value to indicate the status of the function call and will equal one of the following:

(0) ApmetrixStatic.RETURN_STATUS.SUCCESS

Successful operation.

(101) ApmetrixStatic.RETURN_STATUS.WARNING_IGNORED_SESSION_ALREADY_OPEN

Function call was ignored because a session was already open.

(103) ApmetrixStatic.RETURN_STATUS.APMETRIX_WARNING_IGNORED_SESSION_NOT_OPEN

A session has not been initialized

(105) ApmetrixStatic.RETURN_STATUS.APMETRIX_WARNING_INVALID_GCM_ID

A session has been initialized with an invalid GCM ID

(106) ApmetrixStatic.RETURN_STATUS.APMETRIX_WARNING_IGNORED_FUNCTION_NOT_AVAILABLE

Function was ignored because the SDK was already configured for Eye or Object Tracking 

(201) ApmetrixStatic.RETURN_STATUS.ERROR_INVALID_ARGUMENTS

Operation could not be completed because the parameters passed were incorrect.

(202) ApmetrixStatic.RETURN_STATUS.ERROR_APP_CONFIG

Operation could not be completed because there was a device configuration issue (i.e. missing manifest permissions, device parameters disabled, etc.).  Check the log files to see the specific.

(203) ApmetrixStatic.RETURN_STATUS.ERROR_EVENT_DROPPED

Operation could not be completed due to a database or server error causing internal buffers to reach their maximum capacity.  Check the log files for information on the specific error.

(204) ApmetrixStatic.RETURN_STATUS.ERROR_FAILED

Operation could not be completed because of some other error.  Check the log files for information on the specific error.

 

6. Push Notifications

At the current time the ApmetrixUnity SDK does not handle push notifications for virtual reality applications that run on the Windows platform. 

7. Run In Background

Automatic pause and resume of timers / end and restart of sessions is dependent on the "Run In Background" Player Setting NOT being enabled. "Run In Background" setting can be checked by reviewing the Player Settings.  In the IDE click Edit->Project Settings->Player.  In the Player Settings Inspector pane find Resolution and Presentation.  See the figure below:

 

If there is a need to enable "Run In Background" then sessions will remain open when the application goes into the background and timer values will not be accurate because they will include that period of time the application was inactive.

8. Additional Information

This section re-iterates some of the things that the Unity SDK does automatically. These are all located in the Apmetrix.cs file and can be changed to fit your needs. This code can be found in the Start(), OnApplicationQuit() and OnApplicationPause(bool state) methods.

  • The SDK automatically inits an Apmetrix Session and resumes all paused timers (if there are paused timers) when your app starts up as long as the Apmetrix.cs script is enabled.  See Setting the Static Apmetrix Variables for details on how this is checked.
  • When your app quits, goes into the background or loses focus (the user interacts with another application) the SDK automatically pauses all active timers.  This is dependent upon "Run In Background" not being set.
  • When your app returns to the foreground the SDK resumes all paused timers (if there are paused timers).  This is also dependent on "Run In Background" not being set.
  • The SDK will delay app shutdown to allow an end session event and any buffered eye tracking or object tracking data to be sent to the Apmetrix server before finally quitting the application.  The delay of app shutdown though is only possible when the application is NOT running in editor.
Have more questions? Submit a request