Achievements¶
This module allows the developer to define achievements possible in the game as well as keeps track of the progress for each user.
The APIs provided are only to list down the achievements:
- in the app
- user’s achievements (including the completion status)
Each achievement defines rules that are triggered whenever some metric is updated.
The rule definition specifies:
- what metric to compare
- the operator for comparison (<, ==, >)
- the constant value against which it must be compared.
- the rewards to be given upon successful completion of the achievement.
Upon successful completion of an achievement, the system generates notification messages - both in-app as well as push notifications.
The formats of the notification messages are outlined below.
1. In-app notification
{ "status": "ok", "notifications": { "count": 1, "msgs": [ { "msg": "achievements_completed", "event": { "type": "achievements_completed", "event": { "timestamp": 1401212334, "timestamp_str": "2014-05-27 17:38:54 +0000", "goals": [ { "achievement_id": "a1e19d39b3314f9ab4a9f4905ba6ac06", "reward": { "gems": 3 }, "requirements": { "operator": ">", "field": "profile_scores.xp", "value": "20" }, "description": "Unlock 3 gems" } ] } }, "custom": { } } ] } }2. Push Notification
The structures supported by different push notification systems are quite different - so, it’s very difficult to outline the message structure that is finally delivered on the device.
We can only say that the final message will contain message text as “achievement_completed” and a key called “count” that specifies the count of achievement goals completed.
API: List all achievements¶
List all achievements defined for the application
URL: {BASE_URL}/app/<APP_ID>/achievements
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 |
| fmt | No | String | One of (json | xml) - the format of output |
On success, the API returns status=ok along with the actual list of achievements.
Example¶
1. Successful request (output uncompressed for readability):
URL Call:
curl "http://api.playblazer.com/v1/app/1/achievements?secret_key=cb8d878989b9478e96d1b1574a1bf4ec"
Output:
{
"status": "ok",
"achievements": [
{
"name": "Second achievement",
"descr": "One more achievement",
"incremental": false,
"repeatable": false,
"goals": [
{
"reward": {
"xp": 3
},
"requirements": {
"operator": ">=",
"field": "profile_scores.rp",
"value": "10"
},
"description": "Unlock 3xp on crossing 10 rp"
},
{
"reward": {
"gems": 3
},
"requirements": {
"operator": ">=",
"field": "user_profile.attrib.huts_destroyed",
"value": "2"
},
"description": "Get 2 gems for destroying 2 builders' huts"
}
],
"total_goals": 2,
"id": "088571e4b5864c789b9751323a74fb49"
},
{
"name": "test",
"descr": "Test Achievement",
"incremental": true,
"repeatable": false,
"goals": [
{
"reward": {
"gold": 50,
"elixir": 50
},
"requirements": {
"operator": ">",
"field": "profile_scores.xp",
"value": "3"
},
"description": "Unlock 50 gold and 50 elixir"
},
{
"reward": {
"gold": 100,
"elixir": 70
},
"requirements": {
"operator": ">",
"field": "profile_scores.xp",
"value": "5"
},
"description": "Unlock 10 gold and 70 elixir"
},
{
"reward": {
"gems": 3
},
"requirements": {
"operator": ">",
"field": "profile_scores.xp",
"value": "20"
},
"description": "Unlock 3 gems"
}
],
"total_goals": 3,
"id": "a1e19d39b3314f9ab4a9f4905ba6ac06"
},
{
"name": "2nd Achievement",
"descr": "Testing Repeatable Achievement",
"incremental": false,
"repeatable": true,
"goals": [
{
"reward": {
"title": "Scholar"
},
"requirements": {
"operator": ">=",
"field": "profile_scores.xp",
"value": "30"
},
"description": "Update Title to scholar"
}
],
"total_goals": 1,
"id": "b71d488b4f674c40a4ae162ac2a30032"
}
]
}
API: List user’s achievements¶
List achievement status for the given user - including the next goal for each achievement defined.
URL: {BASE_URL}/app/<APP_ID>/achievements/user/<MODE>/<USER_ID>
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 retrieving the achievement status. |
| fmt | No | String | One of (json | xml) - the format of output |
On success, the API returns status=ok along with the actual list of achievement details for each achievement defined for the application.
Instead, if the requesting user’s profile is not found, it returns an error with status=error and code_str=E_NO_PROFILE
Example¶
1. Successful request (output uncompressed for readability):
URL Call:
curl "http://api.playblazer.com/v1/app/1/achievements/user/fb/kunalg?secret_key=cb8d878989b9478e96d1b1574a1bf4ec"
Output:
{
"status": "ok",
"achievements": [
{
"completion": 66.66666666666666,
"name": "test",
"descr": "Test Achievement",
"incremental": true,
"completed_goals": [
{
"reward": {
"gold": 50,
"elixir": 50
},
"requirements": {
"operator": ">",
"field": "profile_scores.xp",
"value": "3"
},
"description": "Unlock 50 gold and 50 elixir"
},
{
"reward": {
"gold": 100,
"elixir": 70
},
"requirements": {
"operator": ">",
"field": "profile_scores.xp",
"value": "5"
},
"description": "Unlock 10 gold and 70 elixir"
}
],
"repeatable": false,
"total_goals": 3,
"id": "a1e19d39b3314f9ab4a9f4905ba6ac06",
"next_goal": {
"reward": {
"gems": 3
},
"requirements": {
"operator": ">",
"field": "profile_scores.xp",
"value": "20"
},
"description": "Unlock 3 gems"
}
},
{
"completion": 100,
"name": "2nd Achievement",
"descr": "Testing Repeatable Achievement",
"incremental": false,
"completed_goals": [
{
"reward": {
"title": "Scholar"
},
"requirements": {
"operator": ">=",
"field": "profile_scores.xp",
"value": "30"
},
"description": "Update Title to scholar"
}
],
"repeatable": true,
"total_goals": 1,
"id": "b71d488b4f674c40a4ae162ac2a30032",
"next_goal": null
},
{
"completion": 100,
"name": "Second achievement",
"descr": "One more achievement",
"incremental": false,
"completed_goals": [
{
"reward": {
"xp": 3
},
"requirements": {
"operator": ">=",
"field": "profile_scores.rp",
"value": "10"
},
"description": "Unlock 3xp on crossing 10 rp"
},
{
"reward": {
"gems": 3
},
"requirements": {
"operator": ">=",
"field": "user_profile.attrib.huts_destroyed",
"value": "2"
},
"description": "Get 2 gems for destroying 2 builders' huts"
}
],
"repeatable": false,
"total_goals": 2,
"id": "088571e4b5864c789b9751323a74fb49",
"next_goal": null
}
]
}
2. User profile not found:
URL Call:
curl "http://api.playblazer.com/v1/app/1/achievements/user/fb/nonexistent?secret_key=cb8d878989b9478e96d1b1574a1bf4ec"
Output:
{
"status": "error",
"error": {
"message": "User profile with 'fbid' = 'nonexistent' not found",
"code": -10003,
"code_str": "E_NO_PROFILE"
}
}