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
LeaderBoard
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 |
Score
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<LeaderboardId> | Optional | URI Template Variable | |
fields | Array<String> | 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
Example 2. Get a LeaderBoard
Example 3. Get LeaderBoards with Specified IDs
Example 4. Get the Top 50 Ranked Scores
Example 5. Get My Friends' Score Ranking
Example 6. Get the Specified User's Score
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<String> | 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
Example 2. Failed Attempt to Update a Leaderboard with a Lower Score
Example 3. Update a Leaderboard that has a defaultScore Value
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
How to Add the Authorization Header
Step 1. Create the base string
1. 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 |
2. 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 |
3. join the encoded parameters with "&".
Step 2. Generate the oauth_signature
1. Build a secret by joining the Consumer Secret and the Token Secret (obtained from the token credential) with "&"
.
2. Pass the base string and secret to the HMAC-SHA1 hashing algorithm.
3. 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:
1. URL encode the parameter names and values in the table below
2. Double quote the value, join name and value with "=", join name/value pairs with ","
3. Add realm parameter as an option
4. 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