requisites ก่อน
หากต้องการใช้ลีดเดอร์บอร์ด APIโดยจะต้องเตรียมรายการดังต่อไปนี้:
- โทเค็นการรับรองความถูกต้อง (Hive Certification Key) เป็นเวลา API โทร: Hive Console > App Center > Manage Project > Game Details > Basic Info > Hive Certification Key
- ลีดเดอร์ ID ใช้: Hive Console > Leaderboard > Manage Ranking
Request URL
Server | URL |
---|---|
LIVE | api-leaderboard.withhive.com |
SANDBOX | sandbox-api-leaderboard.withhive.com |
Response Codes
รหัสตอบกลับทั่วไปสำหรับ API.
Code | Value | Description |
---|---|---|
200 | Success | – |
400 | Bad Request | Invalid leaderboardId or Param input |
401 | Unauthorized | The Authorization header of the request message is missing or its value is invalid |
403 | Forbidden | Authentication Token (Hive Certification Key) for API calls is invalid |
500 | Internal Server Error | An internal problem in the server |
ส่งคะแนน
เก็บคะแนนบนลีดเดอร์บอร์ด
Request URL
LIVE URL | https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/score |
---|---|
SANDBOX URL | https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/score |
HTTP METHOD | POST |
CONTENT-TYPE | application/json |
Path Parameters
Field Name | Description | Type | Required |
---|---|---|---|
leaderboardId | Leaderboard ID | string | Y |
Header Parameters
Field Name | Description | Type | Required |
---|---|---|---|
Authorization | Authentication token for calling API (Bearer) | string | Y |
Request Body
Field Name | Description | Type | Required |
---|---|---|---|
playerId | the Account identifier | long | Y |
score | This is the score to register in the ranking. Up to 15 digits (999,999,999,999,999) can be entered. | integer | Y |
achievementTimeUtc | The time the score recorded (based on UTC+0). The format is yyyy-MM-dd'T'HH:mm:ss.SSS . |
string | Y |
extraData | This is the additional information of the playerid account (nickname, level, country, etc.). Up to 256 characters can be entered. | string | N |
Response
If 200 OK
เนื้อหาการตอบกลับว่างเปล่า
Request Sample
1 2 3 4 5 6 7 8 9 10 11 |
curl --location 'https://sandbox-api-leaderboard.withhive.com/leaderboards/1/score'\ --header 'Content-Type: application/json'\ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'\ --data '{ "playerId": 1000, "score": 87, "achievementTimeUtc": "2023-12-19T15:01:01.004", "extraData": "Lv.14|User1|KR" }' |
ลบคะแนน (ลบข้อมูลผู้ใช้)
ลบข้อมูลผู้ใช้ที่ลงทะเบียนบนกระดานผู้นำ
Request URL
LIVE URL | https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId} |
---|---|
SANDBOX URL | https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId} |
HTTP METHOD | DELETE |
CONTENT-TYPE | application/json |
Path Parameters
Field Name | Description | Type | Required |
---|---|---|---|
leaderboardId | Leaderboard ID | string | Y |
playerId | Account identifier | string | Y |
Header Parameters
Field Name | Description | Type | Required |
---|---|---|---|
Authorization | Authentication token for calling API (Bearer) | string | Y |
Response
If 200 OK
เนื้อหาการตอบกลับว่างเปล่า
Request Sample
1 2 3 4 5 6 |
curl --location\ --request DELETE 'https://sandbox-api-leaderboard.withhive.com/leaderboards/1/players/1004'\ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'\ --data '' |
สอบถามการจัดอันดับ: สอบถามหน้า
ค้นหาอันดับจากด้านบนทีละหน้า
Request URL
LIVE URL | https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/ranks |
---|---|
SANDBOX URL | https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/ranks |
HTTP METHOD | GET |
CONTENT-TYPE | application/json |
Path Parameters
Field Name | Description | Type | Required |
---|---|---|---|
leaderboardId | Leaderboard ID | string | Y |
Header Parameters
Field Name | Description | Type | Required |
---|---|---|---|
Authorization | Authentication token required for API call (Bearer) | string | Y |
Query Parameters
Field Name | Description | Type | Required |
---|---|---|---|
page | Requested page number. Starts from 1, default is 1. If value is 5, only the content of page 5 is queried. | integer | N |
rowcount | Number of ranking information to display per page. Maximum 100, default is 100. | integer | N |
requesttimeutc | Base time for inquiry (based on UTC+0). Default is the current time. Format is yyyy-MM-dd'T'HH:mm:ss.SSS . |
string | N |
playerid | If ranking information for the playerid account exists, it queries that player’s ranking information as well. | long | N |
Response
Field Name | Description | Type |
---|---|---|
rankingList | List of ranking data | json array |
rankingList[].rank | Rank | integer |
rankingList[].playerId | Account identifier | long |
rankingList[].score | Score | long |
rankingList[].achievementTimeUtc | Time when the score was registered (based on UTC+0). Format: yyyy-MM-dd'T'HH:mm:ss.SSS |
string |
rankingList[].extraData | additional information of the playerid account (nickname, level, country, etc.) | string |
playerRank | Ranking information of the user with the playerid provided in the Query Parameter (Returned only if playerid information is present in the Query Parameter) |
json |
playerRank.rank | Rank | integer |
playerRank.playerId | Account identifier | long |
playerRank.score | Score | long |
playerRank.achievementTimeUtc | Time when the score was registered (based on UTC+0), format: yyyy-MM-dd'T'HH:mm:ss.SSS |
string |
playerRank.extraData | additional information of the playerid account (nickname, level, country, etc.) | string |
Request Sample
1 2 3 4 |
curl --location 'https://sandbox-api-leaderboard.withhive.com/leaderboards/1/ranks?page=1&rowcount=100&playerid=1000&requesttimeutc=2023-12-19T15%3A01%3A01.004'\ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' |
Response Sample
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
{ "rankingList": [ { "rank": 1, "playerId": 1001, "score": 89, "achievementTimeUtc": "2023-12-19T15:02:02.004", "extraData": "Lv.50|User1|KR" }, { "rank": 2, "playerId": 1000, "score": 87, "achievementTimeUtc": "2023-12-19T15:01:01.004", "extraData": "Lv.50|User14|KR" } ], "playerRank": { "rank": 2, "playerId": 1000, "score": 87, "achievementTimeUtc": "2023-12-19T15:01:01.004", "extraData": "Lv.50|User14|KR" } } |
ถ้า playerid
ไม่ได้ระบุไว้ใน Query Parameterผลลัพธ์จะไม่รวม playerRank
. หากระบุไว้ แต่ไม่มีข้อมูลการจัดอันดับสำหรับบัญชี playerRank
จะกลับมาในรูปแบบต่อไปนี้:
1 2 3 |
"playerRank": null |
สอบถามการจัดอันดับ: สอบถามข้อมูลการจัดอันดับผู้ใช้ที่เฉพาะเจาะจง
ค้นหาข้อมูลการจัดอันดับสำหรับผู้ใช้เฉพาะราย
Request URL
LIVE URL | https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}/ranks |
---|---|
SANDBOX URL | https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}/ranks |
HTTP METHOD | GET |
CONTENT-TYPE | application/json |
Path Parameters
Field Name | Description | Type | Required |
---|---|---|---|
leaderboardId | Leaderboard ID | string | Y |
playerId | Account identifier | string | Y |
Header Parameters
Field Name | Description | Type | Required |
---|---|---|---|
Authorization | Authentication token required for API call (Bearer) | string | Y |
Query Parameters
Field Name | Description | Type | Required |
---|---|---|---|
requesttimeutc | Base time for inquiry (based on UTC+0), format: yyyy-MM-dd'T'HH:mm:ss.SSS |
string | N |
Response
Field Name | Description | Type |
---|---|---|
playerRank.rank | Rank | integer |
playerRank.playerId | Account identifier | long |
playerRank.score | Score | long |
playerRank.achievementTimeUtc | Time when the score was registered (based on UTC+0), format: yyyy-MM-dd'T'HH:mm:ss.SSS |
string |
playerRank.extraData | additional information of the playerid account (nickname, level, country, etc.) | string |
Request Sample
1 2 3 4 |
curl --location 'https://sandbox-api-leaderboard.withhive.com/leaderboards/1/players/1000/ranks?requesttimeutc=2023-12-19T15%3A01%3A01.004'\ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' |
Response Sample
1 2 3 4 5 6 7 8 9 10 11 |
{ "playerRank": { "rank": 2, "playerId": 1000, "score": 87, "achievementTimeUtc": "2023-12-19T15:01:01.004", "extraData": "Lv.50|User14|KR" } } |
สอบถามการจัดอันดับ: ข้อมูลการจัดอันดับผู้ใช้เฉพาะราย
ค้นหาข้อมูลการจัดอันดับของผู้ใช้รายใดรายหนึ่ง คุณสามารถรับข้อมูลการจัดอันดับสำหรับผู้ใช้ 50 อันดับแรกหรือ 50 อันดับแรกจากผู้ใช้รายหนึ่งๆ ได้
Request URL
Live URL | https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}/ranks |
---|---|
Sandbox URL | https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}/ranks |
HTTP Method | GET |
Content-Type | application/json |
Path Parameters
Field Name | Description | Type | Required |
---|---|---|---|
leaderboardId | Leaderboard ID | string | Y |
playerId | Account identifier | string | Y |
Header Parameters
Field Name | Description | Type | Required |
---|---|---|---|
Authorization | Authentication token required for API call (Bearer) | string | Y |
Query Parameters
Field Name | Description | Type | Required |
---|---|---|---|
nearby | The number of rankings around the playerId . Maximum of 100. |
integer | Y |
requesttimeutc | Base time for inquiry (UTC+0), format: yyyy-MM-dd'T'HH:mm:ss.SSS |
string | N |
Response
Field Name | Description | Type |
---|---|---|
rankingList | List of ranking data | json array |
rankingList[].rank | Rank | integer |
rankingList[].playerId | Account identifier | long |
rankingList[].score | Score | long |
rankingList[].achievementTimeUtc | Time when the score was registered (UTC+0), format: yyyy-MM-dd'T'HH:mm:ss.SSS |
string |
rankingList[].extraData | additional information of the playerid account (nickname, level, country, etc.) | string |
playerRank | User ranking information for the playerid entered in the Path Parameter |
json |
playerRank.rank | Rank | integer |
playerRank.playerId | The account identifier | long |
playerRank.score | Score | long |
playerRank.achievementTimeUtc | The time when the score was recorded (in UTC+0), in the yyyy-MM-dd'T'HH:mm:ss.SSS format |
string |
playerRank.extraData | additional information of the playerid account (nickname, level, country, etc.) | string |
Request Sample
1 2 3 4 |
curl --location 'https://sandbox-api-leaderboard.withhive.com/leaderboards/1/players/1000/ranks?nearby=100&requesttimeutc=2023-12-19T15%3A01%3A01.004'\ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' |
Response Sample
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
{ "rankingList": [ { "rank": 1, "playerId": 1001, "score": 89, "achievementTimeUtc": "2023-12-19T15:02:02.004", "extraData": "Lv.50|User1|KR" }, { "rank": 2, "playerId": 1000, "score": 87, "achievementTimeUtc": "2023-12-19T15:01:01.004", "extraData": "Lv.50|User2|KR" }, { "rank": 3, "playerId": 1002, "score": 70, "achievementTimeUtc": "2023-12-19T15:02:02.004", "extraData": "Lv.50|User3|KR" } ], "playerRank": { "rank": 2, "playerId": 1000, "score": 87, "achievementTimeUtc": "2023-12-19T15:01:01.004", "extraData": "Lv.50|User2|KR" } } |
สอบถามจำนวนผู้ใช้ลีดเดอร์บอร์ด
ค้นหาจำนวนผู้ใช้ทั้งหมดที่ลงทะเบียนบนกระดานผู้นำ
Request URL
Live URL | https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/count |
---|---|
Sandbox URL | https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/count |
HTTP Method | GET |
Content-Type | application/json |
Path Parameters
Field Name | Description | Type | Required |
---|---|---|---|
leaderboardId | Leaderboard ID | string | Y |
Header Parameters
Field Name | Description | Type | Required |
---|---|---|---|
Authorization | Authentication token required for API call (Bearer) | string | Y |
Query Parameters
Field Name | Description | Type | Required |
---|---|---|---|
requesttimeutc | Base time for inquiry (UTC+0), if not entered, the current time is the basis, format: yyyy-MM-dd'T'HH:mm:ss.SSS |
string | N |
Response
Field Name | Description | Type |
---|---|---|
count | Number of registered users | integer |
Request Sample
1 2 3 4 |
curl --location 'https://sandbox-api-leaderboard.withhive.com/leaderboards/1/players/count?requesttimeutc=2023-12-19T15%3A01%3A01.004'\ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' |
Response Sample
1 2 3 4 5 |
{ "count": 3; } |