کار با لیدربورد - REST

نکته: در صورتی که با مفهوم REST و سرویس‌های سمت سرور و یا با دستور curl آشنایی ندارید، به آشنایی با REST مراجعه کنید.

در ادامه سرویس‌های مختلفی که سرویس مرکز بازی بکتوری برای کار با لیدربورد به صورت REST در اختیار شما قرار می‌دهد، را آورده‌ایم.

پیش‌نیازها

  1. در صورتی که با سرویس مرکز بازی آشنایی ندارید، به معرفی سرویس مرکز بازی مراجعه کنید.
  2. در صورتی که هنوز در پنل توسعه‌دهنده خود تنظیمات لازم برای مرکز بازی را انجام نداده‌اید، به تنظیمات پنل مراجعه کنید.
  3. در صورتی که با راه‌اندازی ‌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"
}