Unity tracker

This code belongs to RAGE project and sends analytics information to a server; or, if the server is currently unavailable, stores them locally until it becomes available again.

After a game is developed, a common need is to know how the players play, what interactions they follow within the game and how much time they spend in a game session; collectively, these are known as game analytics. Analytics are used to locate gameplay bottlenecks and assess game effectiveness and learning outcomes, among other tasks.

Installation

1. Clone the repository in your Assets folder inside your Unity project
2. Add the Tracker MonoBehaviour into an empty object in your first scene (the component will be kept across scenes)
3. Configure the component parameters
4. Flush interval: time between each flush of the tracker to the server. If this is set to -1, it will be necessary to call T().RequestFlush() to send traces to the server.
5. Storage type: can be net, to send traces to a server, o local, to store them locally.
6. Trace format: the format of the traces. Can be csv, json or xapi.
7. Host: If storage type is set to net, this should have the host for the analysis server
8. Tracking code: If storage type is set to net, this is the tracking code identifying the game
9. Debug: Enable to see tracker messages in the Unity console.
10. Send traces

Note: The traces file are saved in C:/Users/[username]/AppData/LocalLow/[Company Name]/[Product Name] under the name [UNIX Timestamp].log

If you are not sure or you don’t know your company and product name, you can check and change it the path using the Unity menu: Edit > Project Settings > Player

About Unity tracker core (csharp-tracker)

Unity tracker has been unified with the DotNET tracker in a project called csharp tracker. This project (Unity tracker) contains a wrapper and a prefab that make easier the usage of the tracker, in a similar way as it was in the previous versions of this project. If the features of this wrapper don't fit your needs, you can develop your own wrapper by directly using the csharp-tracker.

The API has changed slightly, but the previous API still is supported (as deprecated) in the newest version of the tracker. If a method is deprecated, the new method that support that call will be shown in the deprecated comment.

MonoBehaviour Example

using UnityEngine;
using System.Collections;

public class TraceGeneratorsScript : MonoBehaviour {

	void Start () {
		Tracker.T.accessible.Accessed("Scene1");
		Tracker.T.setScore(0);
	}

	void Update () {	
	}
}

Detailed Feature List

1. Configurable flush intervals (via T().SetFlushInterval(); use -1 to entirely avoid auto-flush). If flushing fails, for example due to transient network problems, the tracker will periodically attempt to re-send the data.
2. Different storage types:
   1. net: sends data to a trace-server, such as the rage-analytics Backend. If set, a hostname should be specified via the host property.
   2. local, to store them locally for later retrieval. Un-sent traces are always persisted locally before being sent through the net, to support intermittent internet access.
3. Different trace formats:
   1. csv: allow processing in MS Excel or other spreadsheets. Also supported by many analytics environments.
   2. json: especially intended for programmatic analysis, for instance using python or java/javascript or
   3. xapi: an upcoming standard for student activity. Note that, if the tracker's storage type is net it is required to use the xapi trace format since the rage-analytics Backend expects xAPI Statements. The xAPI tracking model that the backend expects is composed of Completables, Reachables, Variables and Alternatives.
4. Tracker messages can be displayed in the Unity console by setting the Debug property
5. Uses Unity's in-built facilities to handle connections, files and timing.

User Guide

The tracker requires (if net mode is on) the RAGE Analytics infrastructure up and running. Check out the Quickstart guide and follow the developer and teacher steps in order to create a game and setup a class. It also requires a:

• Host: where the server is at. This value usually looks like <rage_server_hostmane>/api/proxy/gleaner/collector/. The collector is an endpoint designed to retrieve traces and send them to the analysis pipeline.
• Tracking code: an unique tracking code identifying the game. This code is created in the frontend, when creating a new game.

The tracker exposes an API designed to collect, analyze and visualize the data. The API consists on defining a set of game objects. A game object represents an element of the game on which players can perform one or several types of interactions. Some examples of player's interactions are:

• start or complete (interaction) a level (game object)
• increase or decrease (interaction) the number of coins (game object)
• select or unlock (interaction) a power-up (game object)

A gameplay is the flow of interactions that a player performs over these game objects in a sequential order.

The main typed of game objects supported are:

• Completable - for Game, Session, Level, Quest, Stage, Combat, StoryNode, Race or any other generic Completable. Methods: Initialized, Progressed and Completed.
• Accessible - for Screen, Area, Zone, Cutscene or any other generic Accessible. Methods: Accessed and Skipped.
• Alternative - for Question, Menu, Dialog, Path, Arena or any other generic Alternative. Methods: Selected and Unlocked.
• TrackedGameObject for Enemy, Npc, Item or any other generic GameObject. Methods: Interacted and Used.

Completable

Usage example for the tracking of an in-game quest. We decided to use a Completable game object for this use-case as the most suitable option:

	// Completable
	// Initialized
	Tracker.T.Completable.Initialized("MyGameQuestId", Completable.Quest);
	
	//...
	
	// Progressed
	Tracker.T.Completable.Progressed("MyGameQuestId", Completable.Quest, 0.8);
	
	//...
	
	// Progressed
	bool success = true;
	Tracker.T.Completable.Completed("MyGameQuestId", Completed, success);

Accessible

Usage example for the tracking the player's movement through some in-game screens and skipping the Intro cutscene:

	
	// Accessible
	// The player accessed the 'MainMenu' screen
	Tracker.T.Accessible.Accessed("MainMenu", Accessible.Screen);
	
	//...
	
	// The player skipped a cutscene
	Tracker.T.Accessible.Skipped("Intro", Accessible.Cutscene);

Alternative

Usage example for the tracking the player's choices during a conversation:

	
	// Alternative
	// The player selected the 'Dan' answer for the question 'What's his name?'
	Tracker.T.Alternative.Selected("What's his name?", "Dan", Alternative.Question);
	
	//...
	
	// The player selected 'OK' for the question 'Do you want it?'
	Tracker.T.Alternative.Selected("Do you want to start right now?", "OK", Alternative.Question);

	//...
	
	// The player unlocked 'Combat Mode' for the menu 'Menues/Start'
	Tracker.T.Alternative.Unlocked("Menues/Start", "Combat Mode", Alternative.Menu);
	

Tracked Game Object

Usage example for the tracking the player's with a NPC villager and using a health potion (item):

	
	// Tracked Game Object
	// The player interacted with a Non Playable Character
	Tracker.T.TrackedGameObject.Interacted("NPC/Villager", TrackedGameObject.Npc);
	
	//...
	
	// The player used a health potion
	Tracker.T.TrackedGameObject.Used("Item/HealthPotion", TrackedGameObject.Item);
	

Note that in order to track other type of user interactions it is required to perform a previous analysis to identify the most suitable game objects (Completable, Accessible, Alternative, TrackedGameObject) for the given case. For instance, in order to track conversations alternatives are the best choice.

Tracker and Collector Flow

If the storage type is net, the tracker will try to connect to a Collector endpoint, exposed by the rage-analytics Backend.

More information about the tracker can be found in the official documentation of rage-analytics.