Leaderboard
本文档无中文版本,
请查看其他语言。
Endpoint for Social API
Note: Social API includes Appdata API, Blacklist API, People API, Profanity API, Leaderboard API, Remote Notification API.
Mobage Simplified Chinese Platform
| Production Social | http://sp.mobage-platform.cn/social/api/restful/v2 |
| Sandbox Social | http://sp.sb.mobage-platform.cn/social/api/restful/v2 |
| Environment | URL |
| --- | --- |
Mobage Traditional Chinese Platform
| Environment | URL |
|---|---|
| Production Social | http://sp.mobage-platform.tw/social/api/restful/v2 |
| Sandbox Social | http://sp.sb.mobage-platform.tw/social/api/restful/v2 |
| API Name | HTTP Method | REST URI Fragment | Description |
|---|---|---|---|
| Get Leaderboard | GET | /leaderboards/{appId} | Retrieves the app's leaderboards. |
| GET | /leaderboards/{appId}/{leaderboardId}/{userId}/{groupId} | Retrieves the user's scores on the leaderboards. | |
| Update Leaderboard | PUT | /leaderboards/{appId}/{leaderboardId}/{userId}/{groupId} | Adds a user's score to the app's leaderboard. |
| Delete a Score from | DELETE | /leaderboards/{appId}/{leaderboardId}/{userId}/{groupId} | Removes a user's score from the app's leaderboard. |
Data Type Definition
| Name | Type | Required/Optional | Description |
|---|---|---|---|
| id | String | Optional | Unique identifier for this leaderboard. Read-only. |
| appId | String | Optional | The application identifier for this leaderboard. Read-only. |
| title | String | Optional | The name for this leaderboard. Read-only. |
| scoreFormat | String | Optional | The format used to display scores for this leaderboard. Read-only. See below for a list of possible values. |
| scorePrecision | Number | Optional | The decimal precision value for this leaderboard. Read-only. |
| iconUrl | String | Optional | The URL to the leaderboard icon. Read-only. |
| allowLowerScore | Boolean | Optional | If true, the leaderboard allows a user to post a lower score to the leaderboard. Â If false, a user's existing higher score is not replaced by a lower score. Read-only. |
| reverse | Boolean | Optional | If true, lower scores are ranked higher. Read-only. |
| defaultScore | Number | Optional | Default score value used when no score attribute is specified during an update or insert operation. |
| archived | Boolean | Optional | If true, the leaderboard has been archived and can no longer be updated. This property is reserved for future use and is currently always set to false. |
| published | Date | Optional | The date and time when this leaderboard was created. Uses the format YYYY-MM-DDThh:mm:ss. Read-only. |
| updated | Date | Optional | The date and time when this leaderboard was updated. Uses the format YYYY-MM-DDThh:mm:ss. Read-only. |
Leaderboard.scoreFormat Fields
These fields control the user score's displayValue element. Requested formatting can result in a displayValue element that is different from the raw value field.
Numeric Expression Fields
| Name | Units in Score.value | Description |
|---|---|---|
| integer | integer or real | Signed 32-bit integer expression |
| decimal | integer or real | Signed double expression |
| Name | Units in Score.value | Description |
|---|---|---|
| hours | seconds | HH.zzz |
| minutes | seconds | MM.zzz |
| seconds | seconds | SS.zzz |
| day_second | seconds | DD HH:MM:SS.zzz |
| day_minute | seconds | DD HH:MM.zzz |
| day_hour | seconds | DD HH.zzz |
| hour_second | seconds | HH:MM:SS.zzz |
| hour_minute | seconds | HH:MM.zzz |
| minute_second | seconds | MM:SS.zzz |
| Name | Type | Description |
|---|---|---|
| userId | UserId | User identifier. |
| value | Number | Original value. |
| displayValue | String | Value formatted to match unit and format rules. |
| rank | Number | The value's rank. |
Get Leaderboard
Description
Retrieves the app's leaderboards and the user's scores on the leaderboards.
URI Fragment
/leaderboards/{appId}
/leaderboards/{appId}/{leaderboardId}/{userId}/{groupId}
HTTP Method
GET
Supported Formats
JSON
Request Parameter
Get Leaderboard Request Parameters
| Name | Type | Required/Optional | Parameter Type | Description |
|---|---|---|---|---|
| appId | AppId | Required | URI Template Variable | @app or direct value |
| leaderboardId | LeaderboardId or Array | Optional | URI Template Variable | |
| fields | Array | Optional | Query Parameter | All fields of Leaderboard are specifiable. If no fields are specified, all fields are returned. |
| format | String | Optional | Query Parameter | The only legal value is json. |
| count | Number | Optional | Query Parameter | An integer between 1 and 1000. The default value is 50. |
| sortBy | String | Optional | Query Parameter | The only legal value is id. |
| sortOrder | String | Optional | Query Parameter | Ascending or descending order. |
| startIndex | Number | Optional | Query Parameter | A positive integer. |
Get Score Request Parameters
| Name | Type | Required/Optional | Parameter Type | Description |
|---|---|---|---|---|
| appId | AppId | Required | URI Template Variable | @app or direct value |
| leaderboardId | LeaderboardId | Required | URI Template Variable | direct value |
| userId | UserId | Required | URI Template Variable | @me or direct value |
| groupId | GroupId | Required | URI Template Variable | The only legal values are @all, @self, or @friends. |
| fields | Array<String> | Optional | Query Parameter | Specify any Score fields. When no fields are specified, returns all fields. |
| format | String | Optional | Query Parameter | The only legal value is json. The default value isjson. |
| count | Number | Optional | Query Parameter | An integer between 1 and 1000. The default value is 50. |
| sortBy | String | Optional | Query Parameter | The only legal values are rank and value. The default value is rank. |
| sortOrder | String | Optional | Query Parameter | Ascending or descending order. The default value is ascending. |
| startIndex | Number | Optional | Query Parameter | A positive integer. |
Request Headers
Any request to the Mobage REST APIs must include the Authorization header. For more details, see How to add the Authorization Header.
Request Body
None
Response Body
- Collection of Leaderboards (in the case of /leaderboards/{appId})
- LeaderBoard (/leaderboards/{appId}/{leaderboardId})
- Collection of Scores (/leaderboards/{appId}/{leaderboardId}/{userId}/@all,/leaderboards/{appId}/{leaderboardId}/{userId}/@friends)
- Score (/leaderboards/{appId}/{userId}/@self)
Response Status Code
| HTTP Status Code | HTTP Status Message | Meaning |
|---|---|---|
| 200 | OK | Data successfully acquired |
| 400 | Bad Request | Corrupt request data on the client side |
| 401 | Unauthorized | Authorization error |
| 403 | Forbidden | The resource exists, but access is not possible due to a reason other than an authorization error. |
| 404 | Not Found | The resource doesn't exist |
| 429 | Too Many Requests | The number of leaderboard requests exceeds the throttling limit. |
| 500 | Internal Server Error | An error on the API server side |
| 503 | Service Unavailable | The API cannot be used temporarily |
Example 1. Get All Leaderboards
HTTPS Request
GET /leaderboards/@app
HTTPS Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"entry": [
{
"id": "timeattackranking",
"appId": "12000129",
"title": "Best time ranking",
"scoreFormat": "minute_second",
"scorePrecision": 0,
"iconUrl": "http://example.com/time_ranking.png",
"allowLowerScore": false,
"reverse": false,
"archived": false,
"defaultScore": null,
"published": "2012-02-14 21:00:12T",
"updated": "2012-02-14 21:00:12T"
},
{
"id": "totalwinningranking",
"appId": "12000129",
"title": "The number of win ranking",
"scoreFormat": "integer",
"scorePrecision": 0,
"iconUrl": "http://example.com/win_ranking.png",
"allowLowerScore": false,
"reverse": true,
"archived": false,
"defaultScore": 0,
"published": "2012-02-14 21:00:12T",
"updated": "2012-02-14 21:00:12T"
}
],
"totalResults": 2,
"itemsPerPage": 50,
"startIndex": 1,
"sorted": false
}
Example 2. Get a LeaderBoard
HTTPS Request
GET /leaderboards/@app/timeattackranking,totalwinningranking
HTTPS Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"id": "timeattackranking",
"appId": "12000129",
"title": "Best time ranking",
"scoreFormat": "minute_second",
"scorePrecision": 0,
"iconUrl": "http://example.com/time_ranking.png",
"allowLowerScore": false,
"reverse": false,
"archived": false,
"defaultScore": null,
"published": "2012-02-14 21:00:12T",
"updated": "2012-02-14 21:00:12T"
}
Example 3. Get LeaderBoards with Specified IDs
HTTPS Request
GET /leaderboards/@app/timeattackranking,totalwinningranking
HTTPS Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"entry": [
{
"id": "timeattackranking",
"appId": "12000129",
"title": "Best time ranking",
"scoreFormat": "minute_second",
"scorePrecision": 0,
"iconUrl": "http://example.com/time_ranking.png",
"allowLowerScore": false,
"reverse": false,
"archived": false,
"defaultScore": null,
"published": "2012-02-14 21:00:12T",
"updated": "2012-02-14 21:00:12T"
},
{
"id": "totalwinningranking",
"appId": "12000129",
"title": "The number of win ranking",
"scoreFormat": "integer",
"scorePrecision": 0,
"iconUrl": "http://example.com/win_ranking.png",
"allowLowerScore": false,
"reverse": true,
"archived": false,
"defaultScore": 0,
"published": "2012-02-14 21:00:12T",
"updated": "2012-02-14 21:00:12T"
}
],
"totalResults": 2,
"itemsPerPage": 50,
"startIndex": 1,
"sorted": false
}
Example 4. Get the Top 50 Ranked Scores
HTTPS Request
GET /leaderboards/@app/timeattackranking/@me/@all?sortBy=rank&sortOrder=asscending&count=50&startIndex=1
HTTPS Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"entry": [
{
"userId": "10028",
"value": 128,
"displayValue": "2:08",
"rank": 1,
},
{
"userId": "10029",
"value": 130,
"displayValue": "2:10",
"rank": 2,
},
/* ... */
],
"totalResults": 2,
"itemsPerPage": 50,
"startIndex": 1,
"sorted": true
}
Example 5. Get My Friends' Score Ranking
HTTPS Request
GET /leaderboards/@app/timeattackranking/@me/@friends?sortBy=rank&sortOrder=ascending
HTTPS Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"entry": [
{
"userId": "10028",
"value": 128,
"displayValue": "2:08",
"rank": 1,
},
{
"userId": "10029",
"value": 130,
"displayValue": "2:10",
"rank": 2,
},
/* ... */
],
"totalResults": 2,
"itemsPerPage": 50,
"startIndex": 1,
"sorted": true
}
Example 6. Get the Specified User's Score
HTTPS Request
GET /leaderboards/@app/timeattackranking/10128/@self
HTTPS Reponse
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"userId": "10028",
"value": 128,
"displayValue": "2:08",
"rank": 1
}
Update Leaderboard
Description
Adds a user's score to the app's leaderboard.
URI Fragment
/leaderboards/{appId}/{leaderboardId}/{userId}/{groupId}
Supported Formats
JSON
HTTP Method
PUT
Request Parameters
| Name | Type | Required/Optional | Type | Description |
|---|---|---|---|---|
| appId | AppId | Required | URI Template Variable | @app or direct value |
| leaderboardId | LeaderboardId | Required | URI Template Variable | Leaderboard identifier |
| userId | UserId | Required | URI Template Variable | @me or direct value |
| groupId | GroupId | Required | URI Template Variable | @self is the only legal value |
| fields | Array | Required | Query Parameter | value is the only legal value. |
| score | Score | Required | Body Content | The value field is the only legal value. |
Request Headers
Any request to the Mobage REST APIs must include the Authorization header. For more details, see How to add the Authorization Header .
Response Status Code
| HTTP Status Code | HTTP Status Message | Meaning |
|---|---|---|
| 202 | Accepted | Score update or creation is successful. |
| 400 | Bad Request | Corrupt request data on the client side |
| 401 | Unauthorized | Authorization error |
| 403 | Forbidden | The resource exists, but access is not possible due to a reason other than an authorization error. |
| 404 | Not Found | The resource doesn't exist |
| 409 | Conflict | This operation attempted to set a lower score for a given userId for a leaderboard where the value of the allowLowerScore flag is false. Alternatively, this operation attempted to update a score without a specified value on a leaderboard where the value of the defaultScore flag isnull. |
| 429 | Too Many Requests | The number of leaderboard requests exceeds the throttling limit. |
| 500 | Internal Server Error | An error on the API server side |
| 503 | Service Unavailable | The API cannot be used temporarily |
Response Body
Example 1. Update New Score
HTTPS Request
PUT /leaderboards/@app/timestackranking/@me/@self?fields=value
Content-Type: application/json; charset=utf-8
{
"value": 100
}
HTTPS Response
202 Accepted
Content-Type: application/json; charset=utf-8
{
"rank": 57,
"value": 100,
"userId": "mbga.jp:1192",
"displayValue": "1:40",
}
Example 2. Failed Attempt to Update a Leaderboard with a Lower Score
HTTPS Request
PUT /leaderboards/@app/timeattackranking/@me/@self?fields=value
Content-Type: application/json; charset=utf-8
{
"value": 120
}
HTTPS Resonse
409 Conflict
Content-Type: "application/json; charset=utf-8"
{
"rank": 57,
"value": 100,
"userId": "mbga.jp:1192",
"displayValue": "1:40",
}
Example 3. Update a Leaderboard that has a defaultScore Value
HTTPS Request
PUT /leaderboards/@app/totalwinningranking/@me/@self?fields=value
Content-Type: application/json; charset=utf-8
{
"value": null
}
HTTPS Response
202 Accepted
Content-Type: "application/json; charset=utf-8"
{
"rank": 9999,
"value": 0,
"userId": "mbga.jp:1192",
"displayValue": "0",
}
Delete a Score from a Leaderboard
Description
Removes a user's score from the app's leaderboard.
URI Fragment
/leaderboards/{appId}/{leaderboardId}/{userId}/{groupId}
HTTP Method
DELETE
Request Parameters
| Name | Type | Required/Optional | Parameter Type | Description |
|---|---|---|---|---|
| appId | AppId | Required | URI Template Variable | @app or direct value |
| leaderboardId | LeaderboardId | Required | URI Template Variable | Leaderboard identifier |
| userId | UserId | Required | URI Template Variable | @me or direct value |
| groupId | GroupId | Required | URI Template Variable | @self is the only legal value |
Request Headers
Any request to the Mobage REST APIs must include the Authorization header. For more details, see How to add the Authorization Header .
Request Body
None
Response Body
None
Response Status Code
| HTTP Status Code | HTTP Status Message | Meaning |
|---|---|---|
| 202 | Accepted | Score update or creation is successful. |
| 400 | Bad Request | Corrupt request data on the client side |
| 401 | Unauthorized | Authorization error |
| 403 | Forbidden | The resource exists, but access is not possible due to a reason other than an authorization error. |
| 404 | Not Found | The resource doesn't exist |
| 429 | Too Many Requests | The number of leaderboard requests exceeds the throttling limit. |
| 500 | Internal Server Error | An error on the API server side |
| 503 | Service Unavailable | The API cannot be used temporarily |
Example . Delete Score
HTTPS Request
DELETE /leaderboards/@app/timesttackranking/@me/@self
Content-Type: application/json; charset=utf-8
HTTPS Response
202 Accepted
Content-Type: application/json; charset=utf-8
How to Add the Authorization Header
Step 1. Create the base string**
- build a string for OAuth parameters: firstly sort the following parameters alphabetically and URL encode the names and values, then join name and value with "=", finally join name/value pairs with "
&"
| Parameter | Description | Value |
|---|---|---|
oauth_consumer_key | The Consumer Key for the application | Issued when resist the application |
oauth_nonce | Unique value for each request | Generated on the game server |
oauth_signature_method | Hash method | Only HMAC-SHA1 is specifiable |
oauth_timestamp | UNIX timestamp | Generated on the game server |
oauth_token | The token code | oauth_token is obtained from the token credential. |
oauth_version | OAuth version | Only 1.0 |
- URL encode the following three parameters.
| Parameter | Description |
|---|---|
| Request Method | HTTP Method to the API Server |
| API URL | URL to the API Server (exclude query parameters) |
| OAuth Parameters | A string Built in previous step |
- join the encoded parameters with "&".
Step 2. Generate the oauth_signature
-
Build a secret by joining the Consumer Secret and the Token Secret (obtained from the token credential) with "
&". -
Pass the base string and secret to the HMAC-SHA1 hashing algorithm.
-
the output of HMAC-SHA1 hashing algorithm is a binary string. Use base64 encode to produce the signature string.
A tool is provided to verify whether your signature is correct. Refer to Oauth Signature Tool.
Step 3. Build the Authorization Header
Follow the steps to build the “Authorization” header:
-
URL encode the parameter names and values in the table below
-
Double quote the value, join name and value with "=", join name/value pairs with ","
-
Add realm parameter as an option
-
Add "OAuth " (including the space at the end) to the beginning of the header.
| Parameter | Value |
|---|---|
| oauth_consumer_key | Issued when resist the application |
| oauth_nonce | Generated on the game server |
| oauth_signature | Generated on the game server, Refer to Step 2. Generate the oauth_signature |
| oauth_signature_method | only "HMAC-SHA1" is specifiable |
| oauth_timestamp | Generated on the game server |
| oauth_token | oauth_token is obtained from the token credential. |
| oauth_version | Only 1.0 |
Authorization Header Example
OAuth realm="", oauth_consumer_key="195dcf3f2b64da74549f", oauth_nonce="abb5031d1d767d3626e4", oauth_signature="nzWySwCI9oIUU9mSTnIvrti7V7I%3D", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1363057344", oauth_token="sp_client_id%3A6317c85392724d8914904f708f16d01d", oauth_version="1.0"