Activity Stream¶
The activity stream in any game is useful for users to discover what other users in the game are doing - especially their own friends.
Facebook is a very good example of how the activity stream helps users stay up-to-date about what their friends are doing.
When a user does any activity in the game/app, the Playblazer platform posts it in the inboxes of all the friends and also posts the activity in the app-level activity stream. At the same time, it’s also available in the user’s own outbox.
Think about the two constructs as incoming and outgoing messages respectively.
Activity Structure¶
The two “Fetch Activity Stream” APIs return a list of activities.
Each entry in the “activities” array has the following fields:
- activity id
which uniquely identifies the activity in the system
- creator
the primary attribs of user who created the activity (in the “attribs” dictionary)
- creation time
when the activity was created
- activity type
the type of activity - e.g. “NEW_CHALLENGE”, “CHALLENGE_REPLIED”, “ACHIEVEMENT_GOAL_COMPLETED” etc.
extra data - any activity specific additional data e.g. the opponent primary attribs and the score for “NEW_CHALLENGE”, the goal information for “ACHIEVEMENT_GOAL_COMPLETED” etc.
Note
It is a convention to use capital letters for the activity type.
Example:
{
"status": "ok",
"activities": [
{
"extra_data": {
"sess_scores": {
"user": 3,
"oppn": 3
},
"oppn_score": 87.3,
"score": 89.7,
"result": "win",
"oppn_result": "loss",
"oppn": {
"attribs": {
"first_name": "Kunal",
"last_name": "Gangakhedkar",
"twitterid": null,
"fbid": "u1",
"deviceid": null,
"picture_url": "https://lh3.googleusercontent.com/-XdUIqdMkCWA/AAAAAAAAAAI/AAAAAAAAAAA/4252rscbv5M/photo.jpg?sz=50",
"googleid": "u1"
}
}
},
"activity_id": "a125a25d-3f28-4fc0-a75c-3d4d2f659e01",
"creator": {
"attribs": {
"first_name": "Test",
"last_name": "User 2",
"deviceid": null,
"twitterid": null,
"fbid": "u2",
"googleid": null
}
},
"creation_time": "2014-09-10 10:41:40 +0000",
"activity_type": "CHALLENGE_REPLIED"
},
{
"extra_data": {
"score": 87.3,
"sess_scores": {
"user": 3,
"oppn": 2
},
"oppn": {
"attribs": {
"first_name": "Test",
"last_name": "User 2",
"twitterid": null,
"fbid": "u2",
"deviceid": null,
"googleid": null
}
}
},
"activity_id": "3dd0226c-2603-4c28-ab9c-ff837d3b1c0e",
"creator": {
"attribs": {
"first_name": "Kunal",
"last_name": "Gangakhedkar",
"deviceid": null,
"twitterid": null,
"fbid": "u1",
"picture_url": "https://lh3.googleusercontent.com/-XdUIqdMkCWA/AAAAAAAAAAI/AAAAAAAAAAA/4252rscbv5M/photo.jpg?sz=50",
"googleid": "u1"
}
},
"creation_time": "2014-09-10 10:39:15 +0000",
"activity_type": "NEW_CHALLENGE"
},
{
"extra_data": {
"goal": {
"requirements": {
"operator": ">",
"field": "profile_scores.xp",
"value": "3"
},
"reward": {
"gold": 50,
"elixir": 50
},
"goal_id": 1,
"description": "Unlock 50 gold and 50 elixir",
"achievement_id": "a1e19d39b3314f9ab4a9f4905ba6ac06"
}
},
"activity_id": "2159adab-0d4a-46bd-a260-91169d4d8644",
"creator": {
"attribs": {
"first_name": "Kunal",
"last_name": "Gangakhedkar",
"deviceid": null,
"twitterid": null,
"fbid": "u1",
"picture_url": "https://lh3.googleusercontent.com/-XdUIqdMkCWA/AAAAAAAAAAI/AAAAAAAAAAA/4252rscbv5M/photo.jpg?sz=50",
"googleid": "u1"
}
},
"creation_time": "2014-09-10 07:25:04 +0000",
"activity_type": "ACHIEVEMENT_GOAL_COMPLETED"
},
{
"extra_data": {
"goal": {
"requirements": {
"operator": ">=",
"field": "profile_scores.rp",
"value": "10"
},
"reward": {
"xp": 3
},
"goal_id": 3,
"description": "Unlock 3xp on crossing 10 rp",
"achievement_id": "088571e4b5864c789b9751323a74fb49"
}
},
"activity_id": "0b8bf50e-be29-4a0d-91ae-9bd28d6b93b9",
"creator": {
"attribs": {
"first_name": "Test",
"last_name": "User 2",
"deviceid": null,
"twitterid": null,
"fbid": "u2",
"googleid": null
}
},
"creation_time": "2014-09-10 07:37:36 +0000",
"activity_type": "ACHIEVEMENT_GOAL_COMPLETED"
},
{
"extra_data": {
"goal": {
"requirements": {
"operator": "<",
"field": "leaderboards.xp.rank",
"value": "2"
},
"reward": {
"title": "Scholar"
},
"goal_id": 6,
"description": "Update Title to scholar",
"achievement_id": "b71d488b4f674c40a4ae162ac2a30032"
}
},
"activity_id": "d2d83348-0bc7-4dfc-b620-07377e6434a7",
"creator": {
"attribs": {
"first_name": "Kunal",
"last_name": "Gangakhedkar",
"deviceid": null,
"twitterid": null,
"fbid": "u1",
"picture_url": "https://lh3.googleusercontent.com/-XdUIqdMkCWA/AAAAAAAAAAI/AAAAAAAAAAA/4252rscbv5M/photo.jpg?sz=50",
"googleid": "u1"
}
},
"creation_time": "2014-09-10 07:25:04 +0000",
"activity_type": "ACHIEVEMENT_GOAL_COMPLETED"
}
]
}
API: Fetch app-level activity stream¶
This API retrieves the activity stream posted at the application level - i.e. the activities of all the users in the application.
URL: {BASE_URL}/app/<APP_ID>/activity
Request Method: HTTP GET
| 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 |
| limit | No | Integer | The no. of messages to return in the stream. Defaults to 100. |
| fmt | No | String | One of (json | xml) - the format of output |
On successful execution, the output will carry list of activities along with status=ok. The format of each entry is explained in activity structure above.
Example¶
URL Call:
curl "http://api.playblazer.com/v1/app/1/activity?secret_key=cb8d878989b9478e96d1b1574a1bf4ec"
Output:
{
"status": "ok",
"activities": [
{
"extra_data": {
"sess_scores": {
"user": 3,
"oppn": 3
},
"oppn_score": 87.3,
"score": 89.7,
"result": "win",
"oppn_result": "loss",
"oppn": {
"attribs": {
"first_name": "Kunal",
"last_name": "Gangakhedkar",
"twitterid": null,
"fbid": "u1",
"deviceid": null,
"picture_url": "https://lh3.googleusercontent.com/-XdUIqdMkCWA/AAAAAAAAAAI/AAAAAAAAAAA/4252rscbv5M/photo.jpg?sz=50",
"googleid": "u1"
}
}
},
"activity_id": "a125a25d-3f28-4fc0-a75c-3d4d2f659e01",
"creator": {
"attribs": {
"first_name": "Test",
"last_name": "User 2",
"deviceid": null,
"twitterid": null,
"fbid": "u2",
"googleid": null
}
},
"creation_time": "2014-09-10 10:41:40 +0000",
"activity_type": "CHALLENGE_REPLIED"
},
{
"extra_data": {
"score": 87.3,
"sess_scores": {
"user": 3,
"oppn": 2
},
"oppn": {
"attribs": {
"first_name": "Test",
"last_name": "User 2",
"twitterid": null,
"fbid": "u2",
"deviceid": null,
"googleid": null
}
}
},
"activity_id": "3dd0226c-2603-4c28-ab9c-ff837d3b1c0e",
"creator": {
"attribs": {
"first_name": "Kunal",
"last_name": "Gangakhedkar",
"deviceid": null,
"twitterid": null,
"fbid": "u1",
"picture_url": "https://lh3.googleusercontent.com/-XdUIqdMkCWA/AAAAAAAAAAI/AAAAAAAAAAA/4252rscbv5M/photo.jpg?sz=50",
"googleid": "u1"
}
},
"creation_time": "2014-09-10 10:39:15 +0000",
"activity_type": "NEW_CHALLENGE"
},
{
"extra_data": {
"goal": {
"requirements": {
"operator": ">",
"field": "profile_scores.xp",
"value": "3"
},
"reward": {
"gold": 50,
"elixir": 50
},
"goal_id": 1,
"description": "Unlock 50 gold and 50 elixir",
"achievement_id": "a1e19d39b3314f9ab4a9f4905ba6ac06"
}
},
"activity_id": "2159adab-0d4a-46bd-a260-91169d4d8644",
"creator": {
"attribs": {
"first_name": "Kunal",
"last_name": "Gangakhedkar",
"deviceid": null,
"twitterid": null,
"fbid": "u1",
"picture_url": "https://lh3.googleusercontent.com/-XdUIqdMkCWA/AAAAAAAAAAI/AAAAAAAAAAA/4252rscbv5M/photo.jpg?sz=50",
"googleid": "u1"
}
},
"creation_time": "2014-09-10 07:25:04 +0000",
"activity_type": "ACHIEVEMENT_GOAL_COMPLETED"
},
{
"extra_data": {
"goal": {
"requirements": {
"operator": ">=",
"field": "profile_scores.rp",
"value": "10"
},
"reward": {
"xp": 3
},
"goal_id": 3,
"description": "Unlock 3xp on crossing 10 rp",
"achievement_id": "088571e4b5864c789b9751323a74fb49"
}
},
"activity_id": "0b8bf50e-be29-4a0d-91ae-9bd28d6b93b9",
"creator": {
"attribs": {
"first_name": "Test",
"last_name": "User 2",
"deviceid": null,
"twitterid": null,
"fbid": "u2",
"googleid": null
}
},
"creation_time": "2014-09-10 07:37:36 +0000",
"activity_type": "ACHIEVEMENT_GOAL_COMPLETED"
},
{
"extra_data": {
"goal": {
"requirements": {
"operator": "<",
"field": "leaderboards.xp.rank",
"value": "2"
},
"reward": {
"title": "Scholar"
},
"goal_id": 6,
"description": "Update Title to scholar",
"achievement_id": "b71d488b4f674c40a4ae162ac2a30032"
}
},
"activity_id": "d2d83348-0bc7-4dfc-b620-07377e6434a7",
"creator": {
"attribs": {
"first_name": "Kunal",
"last_name": "Gangakhedkar",
"deviceid": null,
"twitterid": null,
"fbid": "u1",
"picture_url": "https://lh3.googleusercontent.com/-XdUIqdMkCWA/AAAAAAAAAAI/AAAAAAAAAAA/4252rscbv5M/photo.jpg?sz=50",
"googleid": "u1"
}
},
"creation_time": "2014-09-10 07:25:04 +0000",
"activity_type": "ACHIEVEMENT_GOAL_COMPLETED"
}
]
}
API: Fetch inbound activity stream (inbox) for user¶
This API retrieves the incoming activity messages for the given user - i.e. messages about activities done by their friends in the application.
URL: {BASE_URL}/app/<APP_ID>/activity/<MODE>/<USER_ID>/inbox
Request Method: HTTP GET
| 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 for user ID interpretation |
| USER_ID | Yes | String | The user ID whose inbox is requested (usually, self - the logged in user). |
| limit | No | Integer | The no. of messages to return in the stream. Defaults to 100. |
| fmt | No | String | One of (json | xml) - the format of output |
On successful execution, the output will carry list of activities along with status=ok. The format of each entry is explained in activity structure above.
Example¶
URL Call:
curl "http://api.playblazer.com/v1/app/1/activity/fb/u1/inbox?secret_key=cb8d878989b9478e96d1b1574a1bf4ec"
Output: (pay attention to the “creator” field)
{
"status": "ok",
"activities": [
{
"extra_data": {
"sess_scores": {
"user": 3,
"oppn": 3
},
"oppn_score": 87.3,
"score": 89.7,
"result": "win",
"oppn_result": "loss",
"oppn": {
"attribs": {
"first_name": "Kunal",
"last_name": "Gangakhedkar",
"twitterid": null,
"fbid": "u1",
"deviceid": null,
"picture_url": "https://lh3.googleusercontent.com/-XdUIqdMkCWA/AAAAAAAAAAI/AAAAAAAAAAA/4252rscbv5M/photo.jpg?sz=50",
"googleid": "u1"
}
}
},
"activity_id": "a125a25d-3f28-4fc0-a75c-3d4d2f659e01",
"creator": {
"attribs": {
"first_name": "Test",
"last_name": "User 2",
"deviceid": null,
"twitterid": null,
"fbid": "u2",
"googleid": null
}
},
"creation_time": "2014-09-10 10:41:40 +0000",
"activity_type": "CHALLENGE_REPLIED"
},
{
"extra_data": {
"goal": {
"requirements": {
"operator": ">=",
"field": "profile_scores.rp",
"value": "10"
},
"reward": {
"xp": 3
},
"goal_id": 3,
"description": "Unlock 3xp on crossing 10 rp",
"achievement_id": "088571e4b5864c789b9751323a74fb49"
}
},
"activity_id": "0b8bf50e-be29-4a0d-91ae-9bd28d6b93b9",
"creator": {
"attribs": {
"first_name": "Test",
"last_name": "User 2",
"deviceid": null,
"twitterid": null,
"fbid": "u2",
"googleid": null
}
},
"creation_time": "2014-09-10 07:37:36 +0000",
"activity_type": "ACHIEVEMENT_GOAL_COMPLETED"
}
]
}
API: Fetch outbound activity stream (outbox) of user¶
This API retrieves the outbound activity messages of the given user - i.e. messages about activities done by the user himself.
URL: {BASE_URL}/app/<APP_ID>/activity/<MODE>/<USER_ID>/outbox
Request Method: HTTP GET
| 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 for user ID interpretation |
| USER_ID | Yes | String | The user ID whose outbox is requested (usually, some other user). |
| limit | No | Integer | The no. of messages to return in the stream. Defaults to 100. |
| fmt | No | String | One of (json | xml) - the format of output |
On successful execution, the output will carry list of activities along with status=ok. The format of each entry is explained in activity structure above.
Example¶
URL Call:
curl "http://api.playblazer.com/v1/app/1/activity/fb/u1/outbox?secret_key=cb8d878989b9478e96d1b1574a1bf4ec"
Output: (pay attention to the “creator” field)
{
"status": "ok",
"activities": [
{
"extra_data": {
"score": 87.3,
"sess_scores": {
"user": 3,
"oppn": 2
},
"oppn": {
"attribs": {
"first_name": "Test",
"last_name": "User 2",
"twitterid": null,
"fbid": "u2",
"deviceid": null,
"googleid": null
}
}
},
"activity_id": "3dd0226c-2603-4c28-ab9c-ff837d3b1c0e",
"creator": {
"attribs": {
"first_name": "Kunal",
"last_name": "Gangakhedkar",
"deviceid": null,
"twitterid": null,
"fbid": "u1",
"picture_url": "https://lh3.googleusercontent.com/-XdUIqdMkCWA/AAAAAAAAAAI/AAAAAAAAAAA/4252rscbv5M/photo.jpg?sz=50",
"googleid": "u1"
}
},
"creation_time": "2014-09-10 10:39:15 +0000",
"activity_type": "NEW_CHALLENGE"
},
{
"extra_data": {
"goal": {
"requirements": {
"operator": ">",
"field": "profile_scores.xp",
"value": "3"
},
"reward": {
"gold": 50,
"elixir": 50
},
"goal_id": 1,
"description": "Unlock 50 gold and 50 elixir",
"achievement_id": "a1e19d39b3314f9ab4a9f4905ba6ac06"
}
},
"activity_id": "2159adab-0d4a-46bd-a260-91169d4d8644",
"creator": {
"attribs": {
"first_name": "Kunal",
"last_name": "Gangakhedkar",
"deviceid": null,
"twitterid": null,
"fbid": "u1",
"picture_url": "https://lh3.googleusercontent.com/-XdUIqdMkCWA/AAAAAAAAAAI/AAAAAAAAAAA/4252rscbv5M/photo.jpg?sz=50",
"googleid": "u1"
}
},
"creation_time": "2014-09-10 07:25:04 +0000",
"activity_type": "ACHIEVEMENT_GOAL_COMPLETED"
},
{
"extra_data": {
"goal": {
"requirements": {
"operator": "<",
"field": "leaderboards.xp.rank",
"value": "2"
},
"reward": {
"title": "Scholar"
},
"goal_id": 6,
"description": "Update Title to scholar",
"achievement_id": "b71d488b4f674c40a4ae162ac2a30032"
}
},
"activity_id": "d2d83348-0bc7-4dfc-b620-07377e6434a7",
"creator": {
"attribs": {
"first_name": "Kunal",
"last_name": "Gangakhedkar",
"deviceid": null,
"twitterid": null,
"fbid": "u1",
"picture_url": "https://lh3.googleusercontent.com/-XdUIqdMkCWA/AAAAAAAAAAI/AAAAAAAAAAA/4252rscbv5M/photo.jpg?sz=50",
"googleid": "u1"
}
},
"creation_time": "2014-09-10 07:25:04 +0000",
"activity_type": "ACHIEVEMENT_GOAL_COMPLETED"
}
]
}
API: Post custom activity to the stream on behalf of the user¶
This API allows the application to post an activity on behalf of the user.
The activity will be added to all the current friends’ inboxes (i.e. the friends who are registered with the application as of the posting from all the social graphs of the user) along with the app activity stream and the user’s own outbox.
URL: {BASE_URL}/app/<APP_ID>/activity/<MODE>/<USER_ID>/post
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 for user ID interpretation |
| USER_ID | Yes | String | The user ID on whose behalf the activity is being posted. |
| type | Yes | String | The type of activity. (stored in “activity_type”) |
| extra_data | No | String | Any activity-specific data to be stored |
| fmt | No | String | One of (json | xml) - the format of output |
On successful execution, the output will be status=ok.
Attention
The Playblazer platform does not do any processing on ‘extra_data’. So, please make sure it is binary-safe.
Example¶
URL Call:
curl -X POST \
-F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
-F "type=CUSTOM_ACTIVITY" \
-F "extra_data={ \"activity\": \"title_change\", \"new_title\": \"Globetrotter\" }" \
"http://api.playblazer.com/v1/app/1/activity/fb/kunalg/post"
Output:
{
"status": "ok"
}