跳到主要内容

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 Socialhttp://sp.mobage-platform.cn/social/api/restful/v2
Sandbox Socialhttp://sp.sb.mobage-platform.cn/social/api/restful/v2
EnvironmentURL
------

Mobage Traditional Chinese Platform

EnvironmentURL
Production Socialhttp://sp.mobage-platform.tw/social/api/restful/v2
Sandbox Socialhttp://sp.sb.mobage-platform.tw/social/api/restful/v2
API NameHTTP MethodREST URI FragmentDescription
Get LeaderboardGET/leaderboards/{appId}Retrieves the app's leaderboards.
GET/leaderboards/{appId}/{leaderboardId}/{userId}/{groupId}Retrieves the user's scores on the leaderboards.
Update LeaderboardPUT/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

NameTypeRequired/OptionalDescription
idStringOptionalUnique identifier for this leaderboard. Read-only.
appIdStringOptionalThe application identifier for this leaderboard. Read-only.
titleStringOptionalThe name for this leaderboard. Read-only.
scoreFormatStringOptionalThe format used to display scores for this leaderboard. Read-only. See below for a list of possible values.
scorePrecisionNumberOptionalThe decimal precision value for this leaderboard. Read-only.
iconUrlStringOptionalThe URL to the leaderboard icon. Read-only.
allowLowerScoreBooleanOptionalIf 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.
reverseBooleanOptionalIf true, lower scores are ranked higher. Read-only.
defaultScoreNumberOptionalDefault score value used when no score attribute is specified during an update or insert operation.
archivedBooleanOptionalIf 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.
publishedDateOptionalThe date and time when this leaderboard was created. Uses the format YYYY-MM-DDThh:mm:ss. Read-only.
updatedDateOptionalThe 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

NameUnits in Score.valueDescription
integerinteger or realSigned 32-bit integer expression
decimalinteger or realSigned double expression

 Time Expression Fields

NameUnits in Score.valueDescription
hourssecondsHH.zzz
minutessecondsMM.zzz
secondssecondsSS.zzz
day_secondsecondsDD HH:MM:SS.zzz
day_minutesecondsDD HH:MM.zzz
day_hoursecondsDD HH.zzz
hour_secondsecondsHH:MM:SS.zzz
hour_minutesecondsHH:MM.zzz
minute_secondsecondsMM:SS.zzz

Score

NameTypeDescription
userIdUserIdUser identifier.
valueNumberOriginal value.
displayValueStringValue formatted to match unit and format rules.
rankNumberThe 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

NameTypeRequired/OptionalParameter TypeDescription
appIdAppIdRequiredURI Template Variable@app or direct value
leaderboardIdLeaderboardId or ArrayOptionalURI Template Variable
fieldsArrayOptionalQuery ParameterAll fields of Leaderboard are specifiable. If no fields are specified, all fields are returned.
formatStringOptionalQuery ParameterThe only legal value is json.
countNumberOptionalQuery ParameterAn integer between 1 and 1000. The default value is 50.
sortByStringOptionalQuery ParameterThe only legal value is id.
sortOrderStringOptionalQuery ParameterAscending or descending order.
startIndexNumberOptionalQuery ParameterA positive integer.

Get Score Request Parameters

NameTypeRequired/OptionalParameter TypeDescription
appIdAppIdRequiredURI Template Variable@app or direct value
leaderboardIdLeaderboardIdRequiredURI Template Variabledirect value
userIdUserIdRequiredURI Template Variable@me or direct value
groupIdGroupIdRequiredURI Template VariableThe only legal values are @all, @self, or @friends.
fieldsArray<String>OptionalQuery ParameterSpecify any Score fields. When no fields are specified, returns all fields.
formatStringOptionalQuery ParameterThe only legal value is json. The default value isjson.
countNumberOptionalQuery ParameterAn integer between 1 and 1000. The default value is 50.
sortByStringOptionalQuery ParameterThe only legal values are rank and value. The default value is rank.
sortOrderStringOptionalQuery ParameterAscending or descending order. The default value is ascending.
startIndexNumberOptionalQuery ParameterA 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 CodeHTTP Status MessageMeaning
200OKData successfully acquired
400Bad RequestCorrupt request data on the client side
401UnauthorizedAuthorization error
403ForbiddenThe resource exists, but access is not possible due to a reason other than an authorization error.
404Not FoundThe resource doesn't exist
429Too Many RequestsThe number of leaderboard requests exceeds the throttling limit.
500Internal Server ErrorAn error on the API server side
503Service UnavailableThe 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​

NameTypeRequired/OptionalTypeDescription
appIdAppIdRequiredURI Template Variable@app or direct value
leaderboardIdLeaderboardIdRequiredURI Template VariableLeaderboard identifier
userIdUserIdRequiredURI Template Variable@me or direct value
groupIdGroupIdRequiredURI Template Variable@self is the only legal value
fieldsArrayRequiredQuery Parametervalue is the only legal value.
scoreScoreRequiredBody ContentThe 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 CodeHTTP Status MessageMeaning
202AcceptedScore update or creation is successful.
400Bad RequestCorrupt request data on the client side
401UnauthorizedAuthorization error
403ForbiddenThe resource exists, but access is not possible due to a reason other than an authorization error.
404Not FoundThe resource doesn't exist
409ConflictThis 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.
429Too Many RequestsThe number of leaderboard requests exceeds the throttling limit.
500Internal Server ErrorAn error on the API server side
503Service UnavailableThe API cannot be used temporarily

Response Body​

Score

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​

NameTypeRequired/OptionalParameter TypeDescription
appIdAppIdRequiredURI Template Variable@app or direct value
leaderboardIdLeaderboardIdRequiredURI Template VariableLeaderboard identifier
userIdUserIdRequiredURI Template Variable@me or direct value
groupIdGroupIdRequiredURI 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 CodeHTTP Status MessageMeaning
202AcceptedScore update or creation is successful.
400Bad RequestCorrupt request data on the client side
401UnauthorizedAuthorization error
403ForbiddenThe resource exists, but access is not possible due to a reason other than an authorization error.
404Not FoundThe resource doesn't exist
429Too Many RequestsThe number of leaderboard requests exceeds the throttling limit.
500Internal Server ErrorAn error on the API server side
503Service UnavailableThe 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**​
  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 "&" 
ParameterDescriptionValue
oauth_consumer_keyThe Consumer Key for the applicationIssued when resist the application
oauth_nonceUnique value for each requestGenerated on the game server
oauth_signature_methodHash methodOnly HMAC-SHA1 is specifiable
oauth_timestampUNIX timestampGenerated on the game server
oauth_tokenThe token code

oauth_token is obtained from the token credential.

oauth_versionOAuth versionOnly 1.0
  1. URL encode the following three parameters.
ParameterDescription
Request MethodHTTP Method to the API Server
API URLURL to the API Server (exclude query parameters)
OAuth ParametersA string Built in previous step
  1. 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.

ParameterValue
oauth_consumer_keyIssued when resist the application
oauth_nonceGenerated on the game server
oauth_signatureGenerated on the game server, Refer to Step 2. Generate the oauth_signature
oauth_signature_methodonly "HMAC-SHA1" is specifiable
oauth_timestampGenerated on the game server
oauth_token

oauth_token is obtained from the token credential.

oauth_versionOnly 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"