کار با لیدربورد - REST
نکته: در صورتی که با مفهوم REST و سرویسهای سمت سرور و یا با دستور curl آشنایی ندارید، به آشنایی با REST مراجعه کنید.
در ادامه سرویسهای مختلفی که سرویس مرکز بازی بکتوری برای کار با لیدربورد به صورت REST در اختیار شما قرار میدهد، را آوردهایم.
پیشنیازها
- در صورتی که با سرویس مرکز بازی آشنایی ندارید، به معرفی سرویس مرکز بازی مراجعه کنید.
- در صورتی که هنوز در پنل توسعهدهنده خود تنظیمات لازم برای مرکز بازی را انجام ندادهاید، به تنظیمات پنل مراجعه کنید.
- در صورتی که با راهاندازی REST در پلتفرمهای مختلف آشنایی ندارید، به راهاندازی REST در پلتفرمهای مختلف مراجعه کنید.
سرویسهای رویداد
ارسال یک رویداد
همان طور که گفتیم، با ارسال رویداد تغییرات لازم در لیدربورد اعمال میشوند و امتیاز بازیکنها و رتبهی آنها به روز میشود. برای ارسال یک رویداد از سرویس زیر استفاده میکنیم.
curl -X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Backtory-Game-Id: <game-Id>' \
--header 'Authorization: Bearer <user-access-token>' \
-d '{
"eventName": "GameOver",
"fieldsAndValues": [
{
"fieldName": "gold",
"value": 100
},
{
"fieldName": "time",
"value": 1234
}
]
}' \
https://api.backtory.com/game/events
پاسخهایی که ممکن است از سرویس بکتوری دریافت کنید به صورت جدول زیر است
Tables | Description |
---|---|
200-OK | Successful |
417-Expectation Failed | Service is not enables / event data is incorrect |
400-Bad Request | eventName or fieldName is null |
سرویسهای لیدربورد
رتبه یک بازیکن
هر بازیکن این امکان را دارد که بتواند رتبهی خود را در یک لیدربورد مشاهده کند. برای گرفتن رتبهی یک بازیکن باید از سرویس زیر استفاده شود:
curl -X GET \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Backtory-Game-Id: <game-Id>' \
--header 'Authorization: Bearer <user-access-token>' \
'https://api.backtory.com/game/leaderboards/{leaderboardId}'
پاسخهایی که ممکن است از سرویس بکتوری دریافت کنید به صورت جدول زیر است
Tables | Description |
---|---|
200-OK | Successful |
417-Expectation Failed | Service is not enables / event data is incorrect |
400-Bad Request | eventName or fieldName is null |
نمونه پاسخی که توسط سرور ارسال میشود به صورت زیر است:
{
"rank": 2 ,
"scores" : [4, 8 , 13]
}
در صورتی که لیدربورد شما فقط براساس یک فیلد از یک رویداد تعریف شده باشد، در داخل آرایهی scores فقط عدد اول مهم است و دو عدد دیگر صفر خواهند بود. اما اگر لیدربورد شما براساس ۲ یا ۳ فیلد از رویدادهای مختلف (یا یکسان) تعریف شده باشد، آنگاه اعداد بعدی آرایهی scores نیز اهمیت خواهند داشت. ترتیب این فیلدها هنگام ساختن لیدربورد اولویت آنها را در رتبهبندی کاربران تعیین میکند.
افراد برتر لیدربورد
در هر لیدربورد این امکان وجود دارد که بهترین افراد آن لیدربورد را بتوان مشاهده کرد. جهت مشاهدهی بهترین افراد یک لیدربورد میتوان از سرویس زیر کمک گرفت:
curl -X GET \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Backtory-Game-Id: <game-Id>' \
--header 'Authorization: Bearer <user-access-token>' \
'https://api.backtory.com/game/leaderboards/top/{leaderboardId}?count=<COUNT>'
پاسخهایی که ممکن است از سرویس بکتوری دریافت کنید، به صورت جدول زیر است:
Tables | Description |
---|---|
200-OK | Successful |
417-Expectation Failed | Service is not enables / event data is incorrect |
نمونه پاسخ سرور در زیر آمده است:
{
"usersProfile": [
{
"userBriefProfile":
{
"firstName": "محمدجواد",
"lastName": "کریمی",
"userName": "mohj",
"userId": "571655f….."
},
"scores": [418, 0, 0]
},
{
"userBriefProfile":
{
"firstName": "محمد",
"lastName": "احمدی",
"userName": "محمد",
"userId": "5716555c….."
},
"scores": [231, 0, 0]
},
{
"userBriefProfile":
{
"firstName": "حمید",
"lastName": "کریمی",
"userName": "حمیدخفن",
"userId": "571655d0e…."
},
"scores": [118, 0, 0]
}
],
"message": "OK"
}
پارامتر leaderboardId مشخص میکند که بهترین افراد از کدام لیدربورد مد نظر است. leaderboardId را میتوانید از پنل مدیریتی خود برای هر کدام از لیدربوردهایتان مشاهده کنید. متغیر count هم مشخص میکند که چه تعداد از بهترین افراد لیدربورد را میخواهید مشاهده کنید، برای مثال اگر این عدد ۱۰ باشد، ۱۰ نفر اول لیدربورد برگردانده میشوند.
افراد اطراف یک بازیکن
هربازیکن این امکان را دارد که بتواند افرادی که در لیدربورد امتیازی نزدیک به خودش را دارند مشاهده کند. برای مثلا بازیکنی که دررتبهی ۱۰۰ قرار دارد تمایل دارد افراد با رتبه ۹۰ تا ۱۱۰ را مشاهده کند. نحوهی استفاده از این سرویس به این شکل است:
curl -X GET \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Backtory-Game-Id: <game-Id>' \
--header 'Authorization: Bearer <user-access-token>' \
'https://api.backtory.com/game/leaderboards/around-me/{leaderboardId}?count=<COUNT>'
پارامتر leaderboardId مشخص میکند که کدام لیدربورد مد نظر است. leaderboardId را میتوانید از پنل مدیریتی خود برای هر کدام از لیدربوردهایتان مشاهده کنید. متغیر count هم مشخص میکند که چه تعداد از بازیکنهای نزدیک به این بازیکن دیده شود، برای مثال اگر این متغیر ۱۰ باشد، ۵ نفر بالاتر و ۵ نفر پایین تر از بازیکن در جواب برگردانده خواهد شد.
پاسخهایی که ممکن است از سرویس بکتوری دریافت کنید به صورت جدول زیر است
Tables | Description |
---|---|
200-OK | Successful |
417-Expectation Failed | Service is not enables / data is incorrect |
نمونهای از پاسخی که سرور ارسال میکند به صورت زیر است:
{
"usersProfile": [
{
"userBriefProfile": {
"firstName": "محمدجواد",
"lastName": "کریمی",
"userName": "mohj",
"userId": "571655f….."
},
"scores": [418, 0, 0]
},
{
"userBriefProfile": {
"firstName": "محمد",
"lastName": "احمدی",
"userName": "ahmadi.moh",
"userId": "5716555c….."
},
"scores": [231, 0, 0]
},
{
"userBriefProfile": {
"firstName": "حمید",
"lastName": "کریمی",
"userName": "hamid.khafan",
"userId": "571655d0e…."
},
"scores": [118, 0, 0]
}
],
"message": "OK"
}