Sessions

This is the sessions module.

When using the challenge APIs (new challenge/reply challenge), the default behaviour of the session module is to implement the streaks mechanism - i.e. the player replying the challenge is expected to send a counter-challenge to the original challenger. The challenge, then, is expected to reply to this new challenge and send his own counter-challenge. This keeps both the players engaged in the same session and the session object keeps track of the wins for each player.

This default behaviour can be overridden by passing extra parameters (details below) to the ‘Reply challenge’ API. These parameters are:

  • auto_rollover - whether to flush the currently completed rounds (current challenge which is just completed) to persistent storage and prepare for new set of challenges to continue the streak.

    With the default auto-rollover set, the states of the players will automatically toggle between play and waiting to indicate whose turn is it to play.

Note

This is set by default for the default streaks behaviour to continue so, if you don’t want this behaviour, you need to pass “0” to disable the auto-rollover.

  • force_open_states - when this parameter is set to 1, the session will forcibly open the states for both the players - i.e. set them to play. This is so that either player can initiate the next challenge instead of the strictly alternating turns.

  • finished - to indicate that after this reply, the round/session should be considered as finished. This sets the player states for both the players to “finished” and flushes the rounds to persistent storage. However, the in-memory information is still available for both the players to see the results.

    This is useful where the application logic requires only one challenge between any two players.

Attention

After this, the session cannot be used for further activity and the only action possible on the session is to delete the session.

For reason given above, the in-memory structure is still available and the application should explicitly delete the session from both ends by calling the “Flush Session” API.

API: Create Session

Create Session API

URL: {BASE_URL}/app/<APP_ID>/session/<MODE>/<USER_ID>/new

Request Method: HTTP POST

Parameter Mandatory Type Description
APP_ID Yes Alpha-numeric The application ID issued by the Playblazer platform when the app was created
secret_key Yes Alpha-numeric The secret key issued by the Playblazer platform when the app was created
MODE Yes String The mode - used to identify how to interpret the user id.
USER_ID Yes Alpha-numeric The user ID used to identify user’s profile creating the new session.
turn_based No Boolean

Whether the newly created session should support turns.

Possible values:

  • 0: not turn based (default)
  • 1: turn based
auto_switch_turn No Boolean

Whether the turn-swiching should happen automatically when a user posts action using the ‘Post User Action’ API.

This is used only with turn_based=1.

Possible values:

  • 0: do not switch turn automatically (default)
  • 1: switch turn automatically
has_rounds No Boolean

Whether the newly created session should support multiple rounds.

Possible values:

  • 0: no support for rounds (default)
  • 1: support for rounds required
fmt No String One of (json | xml) - the format of output

If successful, the output will contain status=ok state along with the session_id/sess_id attribute that identifies the session created in the format that is specified in the API call; otherwise, status=error and error details encoded as explained earlier.

The session id returned in this API call needs to be used in the subsequent calls to all session APIs.

Note

The ‘has_rounds’ and ‘turn_based’ parameters are no longer used - all sessions created will by default be turn based and support rounds.

We may re-introduce these customization semantics in future.

Note

The caller automatically joins the newly created session.

Example

1. Successful call:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    "http://api.playblazer.com/v1/app/1/session/fb/kunalg/new"

Output:

{
    "status": "ok",
    "sess_id": "cd1d98746f45419da9949b0e7e82b2f7"
}

API: Get Session Details (NOT IMPLEMENTED YET)

Get Session Details API

API: Join Existing Session

Join Existing Session API

URL: {BASE_URL}/app/<APP_ID>/session/<SESSION_ID>/<MODE>/<USER_ID>/join

Request Method: HTTP POST

Parameter Mandatory Type Description
APP_ID Yes Alpha-numeric The application ID issued by the Playblazer platform when the app was created
secret_key Yes Alpha-numeric The secret key issued by the Playblazer platform when the app was created
SESSION_ID Yes Alpha-numeric The session id the caller wants to join.
MODE Yes String The mode - used to identify how to interpret the user id.
USER_ID Yes Alpha-numeric The user ID used to identify user’s profile joining the session.
fmt No String One of (json | xml) - the format of output

If successful, the output will contain status=ok state in the format that is specified in the API call; otherwise, status=error and error details encoded as explained earlier.

This is mainly useful in multi-user applications/games where multiple users are supposed to participate in the activity defined by the session.

Example

1. Successful call:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    "http://api.playblazer.com/v1/app/1/session/cd1d98746f45419da9949b0e7e82b2f7/fb/kunalg/join"

Output:

{
    "status": "ok"
}

2. Error - when the session id is not found:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    "http://api.playblazer.com/v1/app/1/session/invalid_sess_id/fb/kunalg/join"

Output:

{
    "status": "error",
    "error": {
        "message": "Session with given ID not found",
        "code": -40001,
        "code_str": "E_SESS_NOT_FOUND"
    }
}

API: Leave Session

Leave Session API

This API can be used when the a player needs to leave the session when it’s no longer possible for him to continue playing - say, when he’s exhausted all his resources.

URL: {BASE_URL}/app/<APP_ID>/session/<SESSION_ID>/<MODE>/<USER_ID>/leave

Request Method: HTTP POST

Parameter Mandatory Type Description
APP_ID Yes Alpha-numeric The application ID issued by the Playblazer platform when the app was created
secret_key Yes Alpha-numeric The secret key issued by the Playblazer platform when the app was created
SESSION_ID Yes Alpha-numeric The session id the caller wants to join.
MODE Yes String The mode - used to identify how to interpret the user id.
USER_ID Yes Alpha-numeric The user ID used to identify user’s profile joining the session.
fmt No String One of (json | xml) - the format of output

If successful, the output will contain status=ok state in the format that is specified in the API call; otherwise, status=error and error details encoded as explained earlier.

Example

1. Successful call:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    "http://api.playblazer.com/v1/app/1/session/cd1d98746f45419da9949b0e7e82b2f7/fb/kunalg/leave"

Output:

{
    "status": "ok"
}

2. Error - when the session id is not found:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    "http://api.playblazer.com/v1/app/1/session/invalid_sess_id/fb/kunalg/leave"

Output:

{
    "status": "error",
    "error": {
        "message": "Session with given ID not found",
        "code": -40001,
        "code_str": "E_SESS_NOT_FOUND"
    }
}

3. Error - when the calling user is not part of the session:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    "http://api.playblazer.com/v1/app/1/session/cd1d98746f45419da9949b0e7e82b2f7/fb/sam/leave"

Output:

{
    "status": "error",
    "error": {
        "message": "You are not part of the session",
        "code": -40002,
        "code_str": "E_INVALID_ACTION"
    }
}

API: Switch Turn (when the session supports turns)

Switch Turn API

URL: {BASE_URL}/app/<APP_ID>/session/<SESSION_ID>/<MODE>/<USER_ID>/switch_turn

Request Method: HTTP POST

Parameter Mandatory Type Description
APP_ID Yes Alpha-numeric The application ID issued by the Playblazer platform when the app was created
secret_key Yes Alpha-numeric The secret key issued by the Playblazer platform when the app was created
SESSION_ID Yes Alpha-numeric The session id that should be updated.
MODE Yes String The mode - used to identify how to interpret the user id.
USER_ID Yes Alpha-numeric The user ID used to identify user’s profile passing on the turn.
fmt No String One of (json | xml) - the format of output

If successful, the output will contain status=ok state in the format that is specified in the API call; otherwise, status=error and error details encoded as explained earlier.

Along with the status, the user whose turn comes next is also reported in the output with all the identity attributes (fbid, googleid, twitterid etc.) returned.

Note

When the session does not support turns (which all of them do as of now), there is possibility of an error returned with code=-40003 and code_str=’E_NOT_TURN_BASED’.

Example

1. Successful call:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    "http://api.playblazer.com/v1/app/1/session/cd1d98746f45419da9949b0e7e82b2f7/fb/kunalg/switch_turn"

Output:

{
    "status": "ok",
    "next": {
        "attribs": {
            "fbid": "test_profile",
            "googleid": null,
            "twitterid": null
        }
    }
}

2. Error - when it’s not the caller’s turn:

Continuing with the previous example..

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    "http://api.playblazer.com/v1/app/1/session/cd1d98746f45419da9949b0e7e82b2f7/fb/kunalg/switch_turn"

Output:

{
    "status": "error",
    "error": {
        "message": "It's not your turn",
        "code": -40002,
        "code_str": "E_INVALID_ACTION"
    }
}

API: Post User Action

Post custom action to the session.

The app can use this API in a turn-based game to post custom user actions in the game session. These are recorded and stored on the server side and become available in the session history.

URL: {BASE_URL}/app/<APP_ID>/session/<SESSION_ID>/<MODE>/<USER_ID>/action

Request Method: HTTP POST

Parameter Mandatory Type Description
APP_ID Yes Alpha-numeric The application ID issued by the Playblazer platform when the app was created
secret_key Yes Alpha-numeric The secret key issued by the Playblazer platform when the app was created
SESSION_ID Yes Alpha-numeric The session id the caller wants to join.
MODE Yes String The mode - used to identify how to interpret the user id.
USER_ID Yes Alpha-numeric The user ID used to identify user’s profile joining the session.
action Yes String The action string to post.
score No Numeric The score associated with the action - if any.
result No String

The result associated with the action - if any.

This is where the app can post win/loss etc. results.
custom:attr1 No Alpha-numeric Set of custom data to
custom:attr2     include in the action
custom:attr3      
...      
switch_turn No Boolean

Whether to switch the turn or not.

Possible values: - null (default - i.e. not passed) - 0 - 1

This works along with the ‘auto_switch_turn’ attribute that is passed at the time of creating the session.

This parameter can be used to override the ‘auto_switch_turn’ value.

For example, with auto_switch_turn=1, if you pass switch_turn=0 in this API the result will be to hold off the turn of the user. That is, the turn will remain with the current owner of the turn.

If this variable is not passed, the ‘auto_switch_turn’ comes into effect.
send_notification No Boolean

Whether the playblazer system should generate and send a notification to the opponent.

Possible values:

  • 0 (don’t generate)
  • 1 (default - generate and send notification)
fmt No String One of (json | xml) - the format of output

If successful, the output will contain status=ok state in the format that is specified in the API call; otherwise, status=error and error details encoded as explained earlier.

The “score”, “result” and any “custom:..” attributes are included in the “rounds_scores” data structure - just like in the case of ‘Reply Challenge’ API to keep the data structures consistent.

Attention

The “custom:..” attributes are not appended automatically to existing values. Instead, they are replaced with the values passed.

So, the application needs to make sure to append the data to existing variables and pass the updated values in the API call.

The output will also contain ‘next_turn’ - the next logical user who is supposed to play if the turn-switch happens; else, the ‘next_turn’ field in the output will be null.

Note

As of now, we have made a provision to include some custom (processed data) in the output in the field ‘custom’ as a dictionary. However, it is currently not populated since there are no processing steps defined as yet.

Example

1. Successful call:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "action=RAISE" \
    -F "custom:card_used=9S" \
    "http://api.playblazer.com/v1/app/1/session/cd1d98746f45419da9949b0e7e82b2f7/fb/kunalg/action"

Output:

{
    "status": "ok",
    "custom": {
    },
    "next_turn": {
        "attribs": {
            "fbid": "nikhil",
            "googleid": null,
            "first_name": "Nikhil",
            "last_name": "S.",
            "picture_url": null,
        }
    }
}

2. Successful call (with switch_turn=0 - to hold-off the turn):

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "action=RAISE" \
    -F "custom:card_used=9S" \
    -F "switch_turn=0" \
    "http://api.playblazer.com/v1/app/1/session/cd1d98746f45419da9949b0e7e82b2f7/fb/kunalg/action"

Output:

{
    "status": "ok",
    "custom": {
    },
    "next_turn": null
}

3. Error - when the session id is not found:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "action=MOVE_PIECE" \
    -F "custom:moves=['C2-C3']" \
    "http://api.playblazer.com/v1/app/1/session/invalid_sess_id/fb/kunalg/action"

Output:

{
    "status": "error",
    "error": {
        "message": "Session with given ID not found",
        "code": -40001,
        "code_str": "E_SESS_NOT_FOUND"
    }
}

4. Error - when the turn does not belong to the caller:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "action=FOLD" \
    -F "result=loss" \
    -F "score=232" \
    "http://api.playblazer.com/v1/app/1/session/invalid_sess_id/fb/kunalg/action"

Output:

{
    "status": "error",
    "error": {
        "message": "Not your turn",
        "code": -40002,
        "code_str": "E_INVALID_ACTION"
    }
}

API: New Round (when the session supports rounds)

New Round API

URL: {BASE_URL}/app/<APP_ID>/session/<SESSION_ID>/<MODE>/<USER_ID>/round/new

Request Method: HTTP POST

Parameter Mandatory Type Description
APP_ID Yes Alpha-numeric The application ID issued by the Playblazer platform when the app was created
secret_key Yes Alpha-numeric The secret key issued by the Playblazer platform when the app was created
SESSION_ID Yes Alpha-numeric The session id that should be updated.
MODE Yes String The mode - used to identify how to interpret the user id.
USER_ID Yes Alpha-numeric The user ID used to identify user’s profile creating new round.
fmt No String One of (json | xml) - the format of output

If successful, the output will contain status=ok state in the format that is specified in the API call; otherwise, status=error and error details encoded as explained earlier.

This API call internally triggers a closure of the currently active round whereby it is stored in the database and evicted from the in-memory data structure and cannot be used for further actions.

Instead, a new round data structure is created and stored in memory as the currently active round.

Note

When the session does not support rounds (which all of them do as of now), there is possibility of an error returned with code=-40004 and code_str=’E_NO_ROUDS’.

Example

1. Successful call:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    "http://api.playblazer.com/v1/app/1/session/cd1d98746f45419da9949b0e7e82b2f7/fb/kunalg/round/new"

Output:

{
    "status": "ok"
}

2. Error - when the caller is not part of the session (i.e. has not joined the session), it is treated as an invalid action:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    "http://api.playblazer.com/v1/app/1/session/cd1d98746f45419da9949b0e7e82b2f7/fb/new_user/round/new"

Output:

{
    "status": "error",
    "error": {
        "message": "You are not part of the session",
        "code": -40002,
        "code_str": "E_INVALID_ACTION"
    }
}

API: Flush/Delete Session

Flush/Delete Session API

URL: {BASE_URL}/app/<APP_ID>/session/<SESSION_ID>/<MODE>/<USER_ID>/delete

Request Method: HTTP POST

Parameter Mandatory Type Description
APP_ID Yes Alpha-numeric The application ID issued by the Playblazer platform when the app was created
secret_key Yes Alpha-numeric The secret key issued by the Playblazer platform when the app was created
SESSION_ID Yes Alpha-numeric The session id that should be deleted.
MODE Yes String The mode - used to identify how to interpret the user id.
USER_ID Yes Alpha-numeric The user ID used to identify user’s profile deleting the session.
fmt No String One of (json | xml) - the format of output

If successful, the output will contain status=ok state in the format that is specified in the API call; otherwise, status=error and error details encoded as explained earlier.

Deleting a session is a two-step process - first, one of the players calls “Delete Session” API passing the session id that needs to be deleted - this marks the session for deletion, flushes the scores to the DB and generates a notification to the opponent that the session has been terminated.

The opponent still sees this session in his “active session list”, but with his own state now changed to “game_over”.

The opponent then has to call “Delete Session” with the same session ID to indicate its acknowledgment - at which point, the entire in-memory data structure is cleared.

This is where a session is declared as “closed”, its clean-up actions triggered (for example, calculating winner/loser for the session) and it is evicted from the memory and stored in the persistent storage/db.

After this call, the session ID becomes invalid.

Note

If the caller is not part of the session, this API call will return an error with code_str = “E_INVALID_ACTION”.

Similarly, if the session with given ID is not found, the error returned will have code_str = “E_SESS_NOT_FOUND”.

Example

1. Successful call:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    "http://api.playblazer.com/v1/app/1/session/cd1d98746f45419da9949b0e7e82b2f7/fb/kunalg/delete"

Output:

{
    "status": "ok"
}

The notification event that is sent to the opponent has following format:

{
    "msg": null,
    "event": {
        "type": "session_closed",
        "event": {
            "time": <long timestamp>,
            "time_str": "<string representation of time - format YYYY-MM-DD HH:MM:SS>",
            "sessid"; "<session id>",
            "by_user": {
                "fbid": "<fb id of user>",
                "googleid": "<google+ id of user>",
                "email": "<email of user>",
                ....
            }
        }
    },
    "custom": { }
}

API: New Challenge

New Challenge API

URL: {BASE_URL}/app/<APP_ID>/session/challenge/<MODE>/<USER_ID>/new

Request Method: HTTP POST

Parameter Mandatory Type Description
APP_ID Yes Alpha-numeric The application ID issued by the Playblazer platform when the app was created
secret_key Yes Alpha-numeric The secret key issued by the Playblazer platform when the app was created
MODE Yes String The mode - used to identify how to interpret the user id.
USER_ID Yes Alpha-numeric The user ID used to identify user’s profile who wants to initiate challenge.
score Yes Numeric The score for this challenge - the opponent is expected to beat this score.
oppn:mode Yes String The mode of user id interpretation of the opponent.
oppn:id Yes Alpha-numeric The user id of the opponent.
custom:attr1 No Alpha-numeric Set of custom attributes to
custom:attr2     include in the push notification.
custom:attr3      
...      
send_notification No Boolean

Whether the playblazer system should generate and send a notification to the opponent.

Possible values:

  • 0 (default - don’t generate)
  • 1 (generate and send notification)
fmt No String One of (json | xml) - the format of output

If successful, the output will contain status=ok state in the format that is specified in the API call; otherwise, status=error and error details encoded as explained earlier.

Along with the status=ok state, the output will also contain state of the session associated with the challenge.

Example

1. Successful call:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "score=53" \
    -F "oppn:mode=fb" \
    -F "oppn:id=test_profile" \
    -F "send_notification=1" \
    -F "custom:robot=kasporov" \
    "http://api.playblazer.com/v1/app/1/session/challenge/fb/kunalg/new"

Output:

{
    "status": "ok",
    "sess_id": "1b036eef685f4e239ccc37cc3c24b74f",
    "states": {
        "you": "<waiting | play>",
        "oppn": "<play | waiting>",
    },
    "to": {
        "mode": "<USER_MODE_OF_OPPN>",
        "id": "<USER_ID_OF_OPPN_AS_PER_MODE>",
        "first_name": "<first_name_of_oppn | null>",
        "last_name": "<last_name_of_oppn | null>",
        "picture_url": "<pic_url_from_social_graph_module | null>",
        "profile_scores": {
            "played": <no_of_challenges_played_by_oppn>,
            "wins": <no_of_challenges_won_by_oppn>,
            "losses": <no_of_challenges_lost_by_oppn>,
            "level": <level_of_oppn_user>,
            "xp": <xp_of_oppn_user>,
            "hp": <hp_of_oppn_user>,
            "rp": <rp_of_oppn_user>,
            "level_completion": <%age_level_completed>,
        }
    },
    "sess_scores": {
        "you": <session_score_for_you>,
        "oppn": <session_score_for_oppn>,
    },
    "custom": {
        "attrib1": "val1",
        "attrib2": "val2",
        "attrib3": "val3",
        ...
    },
    "your_profile_scores": {
        "played": <no_of_challenges_played>,
        "wins": <no_of_challenges_won>,
        "losses": <no_of_challenges_lost>,
        "level": <level_of_your_user>,
        "xp": <xp_of_your_user>,
        "hp": <hp_of_your_user>,
        "rp": <rp_of_your_user>,
        "level_completion": <%age_level_completed>,
    }
}

With the “send_notification=1” parameter, the opponent (“test_profile”, in the above case) will get the following message in the notification (the same rules as outlined in the documentation of Notifications module apply):

{
    "status": "ok",
    "notifications": {
        "count": 1,
        "msgs": [
            {
                "msg": "new_challenge",
                "custom": {
                    "score": 53,
                    "from": {
                        "mode": "fb",
                        "id": "kunalg"
                    },
                    "robot": "kasparov",
                    "sessid": "1b036eef685f4e239ccc37cc3c24b74f"
                }
            }
        ]
    }
}

API: Reply to Challenge

Reply to Challenge API

URL: {BASE_URL}/app/<APP_ID>/session/challenge/<SESSION_ID>/<MODE>/<USER_ID>/reply

Request Method: HTTP POST

Parameter Mandatory Type Description
APP_ID Yes Alpha-numeric The application ID issued by the Playblazer platform when the app was created
secret_key Yes Alpha-numeric The secret key issued by the Playblazer platform when the app was created
SESSION_ID Yes Alpha-numeric The session ID against which this is a reply
MODE Yes String The mode - used to identify how to interpret the user id.
USER_ID Yes Alpha-numeric The user ID used to identify user’s profile who wants to initiate challenge.
score Yes Numeric The score for this reply
custom:attr1 No Alpha-numeric Set of custom attributes to
custom:attr2     include in the push notification.
custom:attr3      
...      
send_notification No Boolean

Whether the playblazer system should generate and send a notification to the opponent.

Possible values:

  • 0 (default - don’t generate)
  • 1 (generate and send notification)
auto_rollover No Boolean

Whether to rollover the rounds and prepare for the next streak.

Possible values:

  • 1 (default - do automatic rollover)
  • 0 (do NOT perform the rollover automatically - the application logic will take care of that)
force_open_states No Boolean

Whether to forcibly open the states (to “play”) of the players so that any one player can initiate the next challenge instead of the default strictly alternating turns.

Possible values:

  • 0 (default - use the alternating turns for the streaks)
  • 1 (forcibly open the states)
finished No Boolean

Whether to close the session at the end of the current reply.

Possible values:

  • 0 (default - keep the session active for subsequent rounds/streaks)
  • 1 (close the session - but keep the results in memory for both the players to display)
fmt No String One of (json | xml) - the format of output

If successful, the output will contain status=ok state in the format that is specified in the API call; otherwise, status=error and error details encoded as explained earlier.

Along with the status=ok state, the output will also contain the result of the challenge reply - it just compares the scores from the original challenge (to which this is a reply) and the score submitted in the “reply challenge” API call.

Example

1. Successful call:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "score=55" \
    -F "send_notification=1" \
    -F "custom:robot=karpov" \
    "http://api.playblazer.com/v1/app/1/session/challenge/1b036eef685f4e239ccc37cc3c24b74f/fb/test_profile/reply"

Output:

{
    "status": "ok",
    "score": {
        "you":  <score_submitted_by_you>,
        "oppn": <score_submitted_by_oppn>,
    },
    "result": "<win | loss | tie>",
    "states": {
        "you": "<waiting | play>",
        "oppn": "<play | waiting>",
    },
    "sess_scores": {
        "you": <session_score_for_you>,
        "oppn": <session_score_for_oppn>,
    },
    "custom": {
        "attrib1": "val1",
        "attrib2": "val2",
        "attrib3": "val3",
        ...
    },
    "your_profile_scores": {
        "played": <no_of_challenges_played>,
        "wins": <no_of_challenges_won>,
        "losses": <no_of_challenges_lost>,
        "level": <level_of_your_user>,
        "xp": <xp_of_your_user>,
        "hp": <hp_of_your_user>,
        "rp": <rp_of_your_user>,
        "level_completion": <%age_level_completed>,
    }
}

With the “send_notification=1” parameter, the opponent (“kunalg”, in the above case) will get the following message in the notification (the same rules as outlined in the documentation of Notifications module apply):

{
    "status": "ok",
    "notifications": {
        "count": 1,
        "msgs": [
            {
                "msg": "challenge_reply",
                "custom": {
                    "from": {
                        "mode": "fb",
                        "id": "test_profile"
                    },
                    "robot": "karpov",
                    "score": 55,
                    "result": "loss",
                    "sessid": "1b036eef685f4e239ccc37cc3c24b74f"
                }
            }
        ]
    }
}

API: Check possibility of challenge

Check possibility of challenge API

URL: {BASE_URL}/app/<APP_ID>/session/challenge/<MODE>/<USER_ID>/check

Request Method: HTTP POST

Parameter Mandatory Type Description
APP_ID Yes Alpha-numeric The application ID issued by the Playblazer platform when the app was created
secret_key Yes Alpha-numeric The secret key issued by the Playblazer platform when the app was created
MODE Yes String The mode - used to identify how to interpret the user id.
USER_ID Yes Alpha-numeric The user ID used to identify user’s profile who wants to initiate challenge.
oppn:mode Yes String The mode of user id interpretation of the opponent.
oppn:id Yes Alpha-numeric The user id of the opponent.
fmt No String One of (json | xml) - the format of output

This API is to be used to check if a challenge between two players can be successfully started.

It uses the following criteria to decide whether such a challenge is possible:

  • check if there is an on-going session between the two players
  • check if the user identified by (mode, user_id) combination is participating in no. of sessions less than the threshold set.
  • check if the opponent user identified by (oppn:mode, oppn:id) combination is participating in no. of sessions less than the threshold set.

If all the above criteria are successfully met, the API will return with status=ok with can_challenge=true. This indicates that a new challenge can be started between given pair of players.

Also, if there is an on-going session between the two players, the API will also return the session ID for the session.

Example

1. Successful call - existing session found:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "oppn:mode=fb" \
    -F "oppn:id=abcd" \
    "http://api.playblazer.com/v1/app/1/session/challenge/fb/kunalg/check"

Output:

{
    "status": "ok",
    "sess_id": "4a2b990470e8450ea76d05ae659fcfcd",
    "can_challenge": true,
    "round_scores": [
        {
            "start_time": "start_time",
            "end_time": null,
            "score": <score_value | null>,
            "xp": <xp_value_if_set | null>,
            "hp": <hp_value_if_set | null>,
            "user": {
                "fbid": "<FBID>",
                "googleid": "<googleid>",
                "email": "<email>",
                "first_name": "<first_name>",
                "last_name": "<last_name>",
                ...
            },
            "extra": {
                "custom": {
                    <"custom_prop1": "custom_val1">,
                    <"custom_prop2": "custom_val2">,
                    ...
                }
            },
            "result": null
        },
        {
            "start_time": "start_time",
            "end_time": null,
            "score": <score_value | null>,
            "xp": <xp_value_if_set | null>,
            "hp": <hp_value_if_set | null>,
            "user": {
                "fbid": "<FBID>",
                "googleid": "<googleid>",
                "email": "<email>",
                "first_name": "<first_name>",
                "last_name": "<last_name>",
                ...
            },
            "extra": {
                "custom": {
                    <"custom_prop1": "custom_val1">,
                    <"custom_prop2": "custom_val2">,
                    ...
                }
            },
            "result": null
        }
    ]
}

2. Successful call - existing session NOT found:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "oppn:mode=fb" \
    -F "oppn:id=test_profile" \
    "http://api.playblazer.com/v1/app/1/session/challenge/fb/kunalg/check"

Output:

{
    "status": "ok",
    "sess_id": null,
    "can_challenge": true
}

3. Error - caller has more active sessions than the threshold value:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "oppn:mode=fb" \
    -F "oppn:id=test_profile" \
    "http://api.playblazer.com/v1/app/1/session/challenge/fb/kunalg/check"

Output:

{
    "status": "error",
    "error": {
        "message": "You have reached your limit of 20 challenges",
        "code": -40005,
        "code_str": "E_CHALLENGE_LIMIT_REACHED"
    }
}

4. Error - opponent has more active sessions than the threshold value:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "oppn:mode=fb" \
    -F "oppn:id=abcd" \
    "http://api.playblazer.com/v1/app/1/session/challenge/fb/kunalg/check"

Output:

{
    "status": "error",
    "error": {
        "message": "Your opponent has too many challenges. Please select different opponent.",
        "code": -40006,
        "code_str": "E_OPPN_CHALLENGE_LIMIT_REACHED"
    }
}

API: Bulk-close sessions

Bulk-close sessions API

URL: {BASE_URL}/app/<APP_ID>/session/<MODE>/<USER_ID>/bulk_delete

Request Method: HTTP POST

Parameter Mandatory Type Description
APP_ID Yes Alpha-numeric The application ID issued by the Playblazer platform when the app was created
secret_key Yes Alpha-numeric The secret key issued by the Playblazer platform when the app was created
MODE Yes String The mode - used to identify how to interpret the user id.
USER_ID Yes Alpha-numeric The user ID used to identify user’s profile deleting the sessions.
sessions Yes JSON Array List of session ids to delete.
fmt No String One of (json | xml) - the format of output

This API helps close multiple sessions in one call - useful to clean-up the sessions in “game-over” state. However, that’s not a hard requirement - it can also be used to close active sessions.

The output contains “failed_count” and “failed_requests” to indicate which sessions could not be closed along with the corresponding error.

If all the sessions could be closed successfully, “failed_count” will have value 0.

If any of the sessions corresponding to the passed session IDs is still active, it’ll be marked as closed and a notification will be generated for the opponent as outlined in Delete Session.

Example

1. Successful call:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "sessions=[ \"84192fe1955d4dec825fc1c482589c01\", \"75f727a07a6d42ee81459278e2c938e5\", \"c291520282754c9bbe635dc454746f9e\" ]" \
    "http://api.playblazer.com/v1/app/1/session/fb/kunalg/delete"

Output:

{
    "status": "ok",
    "failed_count": 0,
    "failed_requests": [
    ]
}

2. Successful call - some sessions failed to close:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "sessions=[ \"84192fe1955d4dec825fc1c482589c01\", \"75f727a07a6d42ee81459278e2c938e5\", \"c291520282754c9bbe635dc454746f9e\" ]" \
    "http://api.playblazer.com/v1/app/1/session/fb/kunalg/delete"

Output:

{
    "status": "ok",
    "failed_count": 2,
    "failed_requests": [
        {
            "sess_id": "84192fe1955d4dec825fc1c482589c01",
            "error": {
                "message": "Session '84192fe1955d4dec825fc1c482589c01' already ended",
                "code": -40002,
                "code_str": "E_INVALID_ACTION"
            }
        },
        {
            "sess_id": "c291520282754c9bbe635dc454746f9e",
            "error": {
                "message": "Session 'c291520282754c9bbe635dc454746f9e' already ended",
                "code": -40002,
                "code_str": "E_INVALID_ACTION"
            }
        }
    ]
}