Back end collector

The collector endpoint is designed so that different tracking-clients can send tracking-data to the back-end.

The Collector endpoint exposes two main REST API calls that must be done in the correct order to be able to correctly send data:

1.- POST /api/collector/start/:trackingCode: this method must be invoked once every time a new tracking session starts (for instance, a player connects to the game and we must send log data).

Requirements:

The trackingCode is an unique tracking code identifying the game. This code is created in the frontend.

This API call expects an 'Authorization' header with the following format if the sesssion should be logged in and identified:

• <Authorization, 'Bearer JSON Web Token'>
• No Headers and no body (creates a new anonymous session)
• No Headers but with a body specifying the playerId of an anonymous session from a previosu anonymous session (see below for fmore details):

{
    "anonymous": "<anonymousPlayerIdFromPreviousSession>"
}

This format is used when the user is already authenticated. The JSON Web Token is the token received when logging in as an identified user in the Authorization & Authentication (A2) service. Note that if the value of the Authorization header is the JSON Web Token received when logging into the Authorization & Authentication system (A2) the actor field of the response will have the player name field value set to the authenticated user.

Response (check below for further detail):

{
    "authToken": "..authToken..",        - Used as 'Authorization' header for '/api/collector/track' requests.
    "objectId": "..id..",                - Used as Object.id in the following xAPI statements.
    "actor": {Object}                    - https://github.com/adlnet/xAPI-Spec/blob/master/xAPI.md#actor
}

2.- POST /api/collector/track: This API call should be invoked after the first one has returned successfully with an authToken. This API call can be invoked every time new data must be sent to the server and analyzed. The tracking data must be sent inside the body of this API call.

Note that the RAGE analytics back-end expects an array of xAPI Statements as body of this API call, following some xAPI tracking model.

Collector workflow as a logged in user or an anonymous user

As a Tracking client that wants send data to the Collector endpoint it must follow the following process:

1. Send one POST to <base_path>/collector/start/:trackingCode
2. Send many POST to <base_path>/collector/track

Depending on the information sent to the start method (1. POST to <base_path>/collector/start/:trackingCode) the responses might vary. The following use cases are possible:

Case 1 - Sending data as a Logged In user. This means that we have logged in against the A2 module and received a correct JSON Web Token

1.1 - We start a new session as an identified user because we have a correct JSON Web Token for the first time (session count is 1)

1.2 - We start a new session as the same identified user as before because we have a correct JSON Web Token for the second time (session count is 2)

1.3 - We provide a non JSON Web Token compliant format for the Authorization header, an error is received (400)

Case 2 - Collecting data as an anonymous user (without logging in against the A2 module)

2.1 - Just start a session without providing any Authorization header or any body in the request (session count is 1)

2.2 - Start a new session as an anonymous user but this time don't provide an Authorization header but provide a request body { "anonymous" : "<previously_obtained_playerId" } the session count increases (session count is 2)

2.3 - We provide a not found anonymous field in the body of the request receiving an error (404)

The full API documentation can be found here.