3. Contexts

Contexts

Contexts are the core of the RData API. Contexts are made to log continuous events that have start and end time. Generally, there is no way to asynchronously track when your application is closed (or crashed) on mobile platforms. That makes a time logging in any event-based data collection system a non-trivial task. This is one of the issues that RData contexts are made to solve.

Context interruption

Since RData is connection-based, when user is disconnected, RData-Server will interrupt all opened contexts of the connection. That means that if the player started the context by calling StartContext, and then application crashed or user closed it, once the player is disconnected/timed-out, the context will change it's state to interrupted. Interrupted state can be restored by calling restoreContext or ended by calling endContext.

Restoring and ending the interrupted context

It's a responsibility of the client to choose which method to call based on if the state of the game was restored or not. Generally, if the game has disconnected without affecting the gameplay, restoreContext should be called after the reconnect on all root contexts (contexts without parent). If this is not called and any action on the context is performed (context is ended or event is logged withing this context), the context will be restored automatically. If the game has crashed or closed without proper ending of the context tree, endContext should be called next time the client has connected and authenticated. If this step is skipped, the context will hang in the interrupted state.

Parent contexts

Context can have parentContextId. If parent context id is provided, this context will be marked as "child context" to another context. When the parentContextId is specified, context id will be added to the list of children on the parent context document in the database. When the parent context is closed, all it's child contexts will be automatically closed.

When working with contexts, built-in events will be logged, such as StartContextEvent, EndContextEvent, RestoreContextEvent, InterruptContextEvent, SetContextDataEvent and UpdateContextDataEvent.

Methods to work with contexts:

startContext

Starts specific context.

{
    "jsonrpc": "2.0",
    "method": "startContext",
    "params": {
        "id": "CONTEXTGUID", 
        "name": "StartMissionContext", 
        "timeStarted": 1474562400326,
        "persistent": false,
        "parentContextId": "PARENTCONTEXTGUID",
        "data": {
            "missionName": "SaveTheZion",
            "missionProgress": { "questsFinished": 0 }
        }
    },
    "id": 1
}

Parameters:

• id - Id of the context. This should be unique id for the context, ideally GUID. You must keep track of it to be able to close the context later. Even if 2 identical contexts are logged (with the same name and data), they must have unique id.
• name - Name of the context. For example, "StartMissionContext".
• timeStarted - optional parameter, unix timestamp in milliseconds (UTC). If not provided, server time from Date.now() will be used.
• persistent - optional parameter, boolean, false by default. If true, context will be marked as "persistent" and will not be automatically closed when user is disconnected
• parentContextId - optional parameter, id of the parent context. If specified, when parent context is closed this context will also be closed.
• data - Custom data of the context.

endContext

Ends context with given id. If context ID has child contexts, they will also be ended.

{
    "jsonrpc": "2.0",
    "method": "endContext",
    "params": {
        "id": "CONTEXTGUID", 
        "timeEnded": 1474562400326
    },
    "id": 1
}

Parameters:

• id - Id of the context to close.
• timeEnded - optional parameter, unix timestamp in milliseconds (UTC). If not provided, server time from Date.now() will be used.

restoreContext

Restores the interrupted context and all it's interrupted children. Call this to restore your contexts when your client reconnects to the RData during the gameplay.

{
    "jsonrpc": "2.0",
    "method": "restoreContext",
    "params": {},
    "id": 1
}

Parameters:

• id - Id of the context to end

setContextData

Set the data on the context. When the context is started, you can set the data on it. This command gives you the opportunity to set (or replace) it later.

{
    "jsonrpc": "2.0",
    "method": "setContextData",
    "params": {
        "id": "CONTEXT_ID", 
        "data": {"missionProgress": {"questsFinished": 5} },
        "timeSet": 1474562400326
    },
    "id": 1
}

Parameters:

• id - Id of the context to set the data on.
• data - Data object to set.
• timeSet - optional parameter, unix timestamp in milliseconds (UTC). If not provided, server time from Date.now() will be used.

updateContextDataVariable

Updates the data on the context. While setContextData will replace the data field on the context, this command makes it possible to partially update the existing data. You need to follow MongoDB "dot" notation to do that.

{
    "jsonrpc": "2.0",
    "method": "updateContextDataVariable",
    "params": {
        "id": "CONTEXT_ID", 
        "key": "missionProgress.questsFinished", 
        "value": 50,
        "timeUpdated": 1474562400326
     },
    "id": 1
}

Parameters:

• id - Id of the context to set the data on.
• key - Key of the data to update. Use MongoDB dot notation to update a part of the data.
• value - New value
• timeUpdated - optional parameter, unix timestamp in milliseconds (UTC). If not provided, server time from Date.now() will be used.