Skip to content

Latest commit

 

History

History
211 lines (149 loc) · 11.8 KB

README.md

File metadata and controls

211 lines (149 loc) · 11.8 KB
Raw

Java xAPI Tracker

Build Status Coverage Status

This code belongs to the e-UCM Research Group. The Java Tracker sends analytics information to a server or, if the server is currently not available, stores them locally until the server is available again. The traces sent by the games should comply with the xAPI for serious games specification.

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 or download repository
  2. Copy into your project folder
  3. Import the Java Tracker into your code:
import es.eucm.tracker.*;
import es.eucm.tracker.exceptions.XApiException;
import eu.rageproject.asset.manager.Severity;
  1. Create a new TrackerAsset by:
TrackerAsset tracker = TrackerAsset.getInstance();
  1. Set up a bridge for creating connects with the server
// Set bridge, for instance the one defined at the tracker tester app
tracker.setBridge(new JavaBridge());
  1. Further configuration of the tracker can be done with TrackerAssetSettings():
// Configure the options
TrackerAssetSettings settings = new TrackerAssetSettings();

settings.setHost(hostField.getText());
settings.setPort(443);
settings.setSecure(true);
settings.setTraceFormat(TrackerAsset.TraceFormats.xapi);
settings.setBasePath("/api/");

tracker.setSettings(settings);
  1. Optionally, login with user
  2. Start the tracker by using tracker.start()
  3. You can start sending traces now.

Tracker Login and Start

For tracker to send traces to the server, tracker.start() has to be called. If you want to use an authenticated user, you can login before starting the tracker.

You can login with a username and password by calling the method tracker.login(username, password).

Then, you can start the tracker with either:

  • tracker.start(userToken, trackingCode)
  • tracker.start(trackingCode) with the already extracted userToken (from login).
  • tracker.start() with an already extracted userToken (from login) and trackingCode (shown at game on A2 server).

Sending Traces to the Analytics Server

There are two possible ways for sending traces:

  1. Recomended: Using the xAPI for serious games interfaces (Accessible, Alternative, Completable and GameObject) (more info in the user guide below).
  2. Using TrackerAsset.ActionTrace(verb,target_type,target_id) method. This is not recomended unless you have clear in mind what you are doing. Remember that xAPI traces are focused on sending actions, not purely variable changes. If you want to track variables, you can add them as extensions using TrackerAsset.setVar(key, value). See below an example of use:
// Simple trace
tracker.getGameObject().used("GameObjectID", GameObjectTracker.TrackedGameObject.Item);

// Trace with extension
tracker.setVar("extension1", "value1");
tracker.getAccessible().skipped("AccesibleID2", AccessibleTracker.Accessible.Screen);

// Complex trace, including response, score, success, completion and several extensions
tracker.setResponse("TheResponse");
tracker.setScore(0.123f);
tracker.setSuccess(false);
tracker.setCompletion(true);
tracker.setVar("extension1", "value1");
tracker.setVar("extension2", "value2");
tracker.setVar("extension3", 3);
tracker.setVar("extension4", 4.56f);
tracker.actionTrace("selected", "zone", "ObjectID3");

// Sending the traces
tracker.flush();

Detailed Feature List

  1. 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. Unsent traces are always persisted locally before being sent through the net, to support intermittent internet access.
  2. 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, java or javascript.
    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.

User Guide

There are two storage types available: net and local. 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 types 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.
  • GameObject 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.getCompletable().initialized("MyGameQuestId", CompletableTracker.Completable.Quest);

// Progressed
float progress = 0.5f;
tracker.getCompletable().progressed("MyGameQuestId", CompletableTracker.Completable.Quest, progress);

// Completed
tracker.getCompletable().completed("MyGameQuestId", CompletableTracker.Completable.Quest);

// Completed with success and score
boolean success = true;
float score = 08f;
tracker.getCompletable().completed("MyGameQuestId", CompletableTracker.Completable.Quest, success, score);

Accessible

Usage example for tracking the player's movement enterging the 'MainMenu' and skipping the 'Intro' cutscene:

// Accessible

// Accessed
// The player accessed the 'MainMenu' screen
tracker.getAccessible().accessed("MainMenu", AccessibleTracker.Accessible.Screen);

// Skipped
// The player skipped the 'Intro' cutscene
tracker.getAccessible().skipped("Intro", AccessibleTracker.Accessible.Cutscene);

Alternative

Usage example for the tracking the player's choices during a conversation and unlocking an option in a menu:

// Alternative

// Selected 
// The player selected the 'Ivan' answer for the question 'What's his name?'
tracker.getAlternative().selected("what's his name?", "Ivan", AlternativeTracker.Alternative.Question);

// Unlocked
// The player unlocked 'Combat Mode' for the menu 'Menus/Start'
tracker.getAlternative().unlocked("Menus/Start", "Combat Mode", AlternativeTracker.Alternative.Menu);

Tracked Game Object

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

// GameObject

// Interacted 
// The player interacted with an NPC
tracker.getGameObject().interacted("NPC/Villager", GameObjectTracker.TrackedGameObject.Npc);

// Used
// The player used an item
tracker.getGameObject().used("Item/HealthPotion", GameObjectTracker.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, GameObject) for the given case. For instance, in order to track conversations alternatives are the best choice.

Tracker Tester App

An app to test the tracker by sending traces is available in the swing-example folder.

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.

Useful Maven goals

  • mvn clean install: run tests, check correct headers and generate tracker-jar-with-dependencies.jar file inside tracker/target folder
  • mvn clean test: run tests checking tracker output
  • mvn license:check: verify if some files miss license header. This goal is attached to the verify phase if declared in your pom.xml like above.
  • mvn license:format: add the license header when missing. If a header is existing, it is updated to the new one.
  • mvn license:remove: remove existing license header