GLEANER is now RAGE Analytics

(Feb 2015) The experience creating GLEANER has been used to create RAGE Analytics. The development of GLEANER has ceased and continues in the RAGE Analytics GitHub repo

Technical documentation

Installing GLEANER on Ubuntu

Software requirements

GLEANER has been mainly tested in Ubuntu machines (both Server and Deskto distributions). To properly run GLEANER, the following software must be installed in the machine

Downloading the code

You can download a .zip or .tar.gz distribution from the right sidebar, or you can download the code directly from the Github repository:

            mkdir repositories
            git clone https://github.com/anserran/gleaner-frontend
            cd gleaner-frontend
            npm install

Configuring GLENAER

For GLEANER to properly run, you need to set the proper configuration settings in app/configuration.js. It has the following properties:

          module.exports =
            {
              "passwordsSalt": "somestalforpasswords", // Salt for password hashing
              "sessionSecret": "somesalt" // Salt for sessions
              "mongoHost": "localhost", // MongoDB host
              "mongoPort": 27017, // MongoDB port
              "mongoDatabase": "gleaner", // MongoDB database name,
              "port": 80 // Port where the application listens
            };

Update these properties to match your settings.

Creating admin user

Once the configuration file is ready, you need to create an admin user to access GLEANER dashboard. You can do that executing, in the gleaner source root:

            node bin/install adminUserName adminUserPassword

substituting adminUserName and adminUserPassword for whichever values you want.

Starting GLEANER server

To start GLENAER, run in the gleaner source root:

            sudo npm start

Once is up, you can access to your server root, log in and start adding games to be tracked.

The API

GLEANER has two main components: the collector, to receive traces from educational videogames and resources, and the analyzer, to deal with analysis and reporting of the collected data.

Collector API

Collector API receives games traces and stores them in the gleaner database, and it listens in http://gleanerhost/api/c/

Start tracking

To send traces to the collector, the client must first ask permission to the server sending the following request, with 'Authorization' header set to 'anonymous':

GET collect/start/gamekey

where gamekey is a unique identifier, known by GLEANER, representing the game to track. You can find this gamekey (labeled with 'Tracking code') under the information tab in the data page of any version of any game you have created. The collector checks request credentials and if they are valid returns an http code 20X with an authorization object:

{
            "authToken":"some_token",
            "playerName":"some_player_identifer"
          }

Sending traces

Clients sends traces to:

POST collect/track

The request must set its authorization header with the value returned in authToken.

The message body must contain a list of json objects. Each of this object represents a trace, and must follow the following structure:

{
  "type": "logic",
  "event": "event_type",
  "target": "event_target",
  "value": "event_value"
}

20X is returned if the list of traces is added, 400 if the format is incorrect or 401 if user hasn't got permission.

Traces can contain as many fields as desired. However, many of the built-in tools in gleaner use two types of traces, input, representing direct interactions of players with input devices (as mouses, keyboards, controllers...) and logic, representing logic events in the game. They follow the next structure:

Examples:

A new game play is started:

{
    "type": 'logic',
    "event": 'start'
}

A player entered a zone, exiting the previous one:

{
    "type": "logic",
    "event": "zone",
    "value": "zone_identifier"
}

A meaningful variable was updated in the game:

{
    "type": "logic",
    "event": "var",
    "target": "variable_name"
    "value": variable_value_object // Object, number or string
}

The user makes a concious choice between several options (e.g. in a conversation node)

{
    "type": "logic",
    "event": "choice",
    "target": "choice_id"
    "value": selected_option_object
}

Using the Gleaner client

You can find some pre-made Java libraries to connect with gleaner from the client in https://github.com/anserran/gleaner-tracker. The main class you want to look is Tracker (and its platform dependent implementations JerseyTracker and GwtTracker). These classes:

Can start the communication with the server only from the URL and the game token
Contain a queue with the traces, that is automatically managed
Handle possible connection errors with the server
Contains many convenient methods to generate common traces