مرکز بازی - قابلیت های مدیریت

هدف از این مستند آن است که شما بتوانید با استفاده از سرویس رایانش به سرویس مرکز بازی وصل شوید. امکان اتصال به مرکز بازی از طریق SDK نیز وجود دارد، اما گاهی نیاز دارید تا علاوه بر اتصال به مرکز بازی منطق‌های دلخواهی را نیز پیاده‌سازی کنید که خاص بازی شماست. برای مثال اینکه هر کاربر در هر روز فقط یکبار امکان گزارش یک Event خاص را داشته باشد و یا مواردی از این دست که نیازمند آن است که منطق آن در سرور پیاده‌سازی شود تا از تقلب و دستکاری امتیازات جلوگیری شود.

پیش‌نیازها

1. در صورتی که با سرویس مرکز بازی آشنایی ندارید، به معرفی سرویس مرکز بازی مراجعه کنید.
2. در صورتی که هنوز در پنل توسعه‌دهنده خود تنظیمات لازم برای مرکز بازی را انجام نداده‌اید، به تنظیمات پنل مراجعه کنید.
3. در صورتی که ایده‌ای راجع به سرویس Cloud Code ندارید، به معرفی سرویس رایانش مراجعه کنید.
4. در صورتی که هنوز با SDK سرویس رایانش برای اتصال به سایر سرویس ها آشنایی ندارید یا آن را راه اندازی نکرده اید، به راه اندازی SDK سرویس رایانش مراجعه کنید.

سرویس‌های رویداد

ارسال یک رویداد از جانب یک کاربر خاص

همان طور که گفتیم، با ارسال رویداد تغییرات لازم در لیدربورد اعمال می‌شوند و امتیاز بازیکن‌ها و رتبه‌ی آنها به روز می‌شود. برای ارسال یک رویداد از جانب یک کاربر خاص از سرویس زیر استفاده می کنیم.

var event = new Backtory.Event("<event-Name>");
event.add("gold", 100);
event.add("time", 1234);

event.sendFromUser("<user-Id>", {
    success: function() {
        // The request succeeded
    },

    error: function(error) {
        // The request failed
    }
});

انواع پاسخ‌هایی که از این سرویس ممکن است دریافت کنید به صورت جدول زیر است که در حالت اجرای موفقیت آمیز کالبک مربوط به success صدا زده می شود و در غیر این صورت محتویات خطا در شیء error قابل دسترسی می باشد.

ارسال رویداد به صورت دسته‌ای (بالک)

در سرویس رایانش این امکان وجود دارد که مدیر چندین رویداد را به صورت بالک (Bulk) با هم و تنها با یک درخواست ارسال کند. برای این منظور به صورت زیر عمل می‌کنیم:

var event1 = new Backtory.Event("<Event-Name>");
event1.add("gold", 100);
event1.add("time", 1234);

var event2 = new Backtory.Event("<Event-Name>");
event2.add("mmr", 24);
event2.add("time", 1234);

var event3 = new Backtory.Event("<Event-Name>");
event3.add("gold", 150);
event3.add("time", 1334);

var eventBulk = new Backtory.EventBulk();
eventBulk.add(event1, "<USER-ID-1>");
eventBulk.add(event2, "<USER-ID-2>");
eventBulk.add(event3, "<USER-ID-3>");

eventBulk.send({
    success: function() {
        // The request succeeded
    },
    error: function(error) {
        // The request failed
    }
});

در حالت اجرای موفقیت آمیز کالبک مربوط به success صدا زده می شود و در غیر این صورت محتویات خطا در شیء error قابل دسترسی می باشد. انواع پاسخ‌هایی که ممکن است از این سرویس ردیافت کنید، مشابه حالت قبلی است.

سرویس‌های لیدربورد

رتبه یک بازیکن خاص در لیدربورد

برای گرفتن رتبه‌ی یک بازیکن باید از سرویس زیر استفاده شود:

در صورتی که لیدربورد شما فقط براساس یک فیلد از یک رویداد تعریف شده ‌باشد، در داخل آرایه‌ی scores فقط عدد اول مهم است و دو عدد دیگر صفر خواهند بود. اما اگر لیدربورد شما براساس ۲ یا ۳ فیلد از رویدادهای مختلف (یا یکسان) تعریف شده باشد آنگاه اعداد بعدی آرایه‌ی scores نیز اهمیت خواهند داشت. ترتیب این فیلد‌ها هنگام ساختن لیدربورد اولویت آنها را در رتبه‌بندی کاربران تعیین می‌کند.

var leaderBoard = new Backtory.LeaderBoard("<leaderboard-Id>");

leaderBoard.getUserRank("<user-Id>", {
    success: function(rank, scores) {
        // The request succeeded. Show the rank and score
        context.log("User rank and score in leaderboard = " + rank + ", " + scores);
    },

    error: function(error) {
        // The request failed
    }
});

انواع پاسخ‌هایی که از این سرویس ممکن است دریافت کنید به صورت جدول زیر است که در حالت اجرای موفقیت آمیز کالبک مربوط به success صدا زده می شود و در غیر این صورت محتویات خطا در شیء error قابل دسترسی می باشد.

نمونه‌ای از پاسخ دریافت شده برای rank و scores از این سرویس در حالتی که درخواست موفقیت آمیز اجرا شده و کالبک success صدا زده شده است، به صورت زیر می باشد.

{
    "rank": 2 ,
    "scores" : [4, 8, 13]
}

افراد برتر لیدربورد

در هر لیدربورد این امکان وجود دارد که بهترین افراد آن لیدربورد را بتوان مشاهده کرد. جهت مشاهده‌ی بهترین افراد یک لیدربورد می‌توان از سرویس زیر کمک گرفت:

var leaderBoard = new Backtory.LeaderBoard("<leaderboard-Id>");

leaderBoard.getTopUsers(<count>, {
    success: function(response) {
        var topList = response.usersProfile;
        for (var i = 0; i < topList.length; i++) {
            context.log("rank = " + (i + 1)
                        + ", user = " + topList[i].userBriefProfile
                        + ", scores = " + topList[i].scores);
        }
    },
    error: function(error) {
        // The request failed
    }
});

پارامتر leaderboardId مشخص می‌کند که بهترین افراد از کدام لیدربورد مد نظر است. leaderboardId را می‌توانید از پنل مدیریتی خود برای هر کدام از لیدربوردهایتان مشاهده کنید. متغیر count هم مشخص می‌کند که چه تعداد از بهترین افراد لیدربورد را می‌خواهید مشاهده کنید، برای مثال اگر این عدد ۱۰ باشد، ۱۰ نفر اول لیدربورد برگردانده می‌شوند.

انواع پاسخ‌هایی که از این سرویس ممکن است دریافت کنید به صورت جدول زیر است که در حالت اجرای موفقیت آمیز کالبک مربوط به success صدا زده می شود و در غیر این صورت محتویات خطا در شیerror قابل دسترسی می باشد.

نمونه‌ای از پاسخ دریافت شده برای response از این سرویس در حالتی که درخواست موفقیت آمیز اجرا شده و کالبک success صدا زده شده است به صورت زیر می باشد.

{
    "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"
}

افراد برتر لیدربورد همراه با صفحه بندی

مدیر این امکان را دارد که بفهمد چه کسانی در جایگاه ۱۰۰ ام تا ۱۸۰ ام یک لیدربورد قرار دارند. نحوه استفاده از این سرویس به صورت زیر می باشد.

var leaderBoard = new Backtory.LeaderBoard("<leaderboard-Id>");

leaderBoard.getTopUsersWithPagination(<page>, <count>, {
    success: function(response) {
        var topList = response.usersProfile;
        for (var i = 0; i < topList.length; i++) {
            context.log("rank = " + (i + 1)
                        + ", user = " + topList[i].userBriefProfile
                        + ", scores = " + topList[i].scores);
        }
    },
    error: function(error) {
        // The request failed
    }
});

در کد بالا اگر page را برار 1 قرار دهیم و count را برابر ۱۸، کاربرانی با رتبه ۱۹ تا ۳۶ در لیدربورد مشخص شده بر گردانده می شود.

انواع پاسخ‌هایی که از این سرویس ممکن است دریافت کنید به صورت جدول زیر است که در حالت اجرای موفقیت آمیز کالبک مربوط به success صدا زده می شود و در غیر این صورت محتویات خطا در شیerror قابل دسترسی می باشد.

نمونه‌ای از پاسخ دریافت شده برای response از این سرویس در حالتی که درخواست موفقیت آمیز اجرا شده و کالبک success صدا زده شده است به صورت زیر می باشد.

{
    "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"
}

افراد اطراف یک بازیکن خاص در لیدربورد

مدیر این امکان را دارد که بتواند افرادی که در لیدربورد امتیازی نزدیک به یک کاربر خاص را دارند، مشاهده کند. برای مثال ممکن است بخواهد برای یک کاربر خاص که در رتبه ۱۰۰ قرار دارد، بفهمد چه کسانی اطراف او در لیدربورد در جایگاه ۹۰ تا ۱۱۰ قرار دارند. نحوه استفاده از این سرویس به شکل زیر می باشد:

var leaderBoard = new Backtory.LeaderBoard("<leaderboard-Id>");

leaderBoard.getAroundUser("<user-Id>", <count>, {
    success: function(response) {
        var aroundList = response.usersProfile;
        for (var i = 0; i < aroundList.length; i++) {
            context.log("user = " + aroundList[i].userBriefProfile
                        + ", scores = " + aroundList[i].scores);
        }
    },

    error: function(error) {
        // The request failed
    }
});

پارامتر leaderboardId مشخص می‌کند که کدام لیدربورد مد نظر است. leaderboardId را می‌توانید از پنل مدیریتی خود برای هر کدام از لیدربوردهایتان مشاهده کنید. متغیر count (پارامتر دوم متود getAroundUser) هم مشخص می‌کند که چه تعداد از بازیکن‌های نزدیک به این بازیکن دیده شود، برای مثال اگر این متغیر ۱۰ باشد، ۵ نفر بالاتر و ۵ نفر پایین تر از بازیکن در جواب برگردانده خواهد شد.

انواع پاسخ‌هایی که از این سرویس ممکن است دریافت کنید به صورت جدول زیر است که در حالت اجرای موفقیت آمیز کالبک مربوط به success صدا زده می شود و در غیر این صورت محتویات خطا در شیء error قابل دسترسی می باشد.

نمونه‌ای از پاسخ دریافت شده برای response از این سرویس در حالتی که درخواست موفقیت آمیز اجرا شده و کالبک success صدا زده شده است به صورت زیر می باشد.

{
    "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"
}

لیدربورد های یک کاربر خاص

مدیر این امکان را دارد که بفهمد یک کاربر خاص در چه لیدربورد هایی وجود دارد. (یک کاربر وقتی به یک لیدربورد اضافه می شود که رخدادی از سمت او به آن لیدربورد ارسال شده باشد.) نحوه استفاده از این سرویس به شکل زیر می باشد:

Backtory.Game.getUserLeaderBoards("<user-Id>", {
    success: function(leaderBoards) {
        context.log(leaderBoards);
    },
    error: function(error) {
        // The request failed
    }
});

انواع پاسخ‌هایی که از این سرویس ممکن است دریافت کنید به صورت جدول زیر است که در حالت اجرای موفقیت آمیز کالبک مربوط به success صدا زده می شود و در غیر این صورت محتویات خطا در شیء error قابل دسترسی می باشد.

نمونه‌ای از پاسخ دریافت شده برای leadeBoards از این سرویس در حالتی که درخواست موفقیت آمیز اجرا شده و کالبک success صدا زده شده است، به صورت زیر می باشد.

["<leaderboard-Id-1>", "<leadeboard-Id-2>", "<leaderboard-Id-3>"]

امتیاز های تعدادی کاربر خاص در لیدربورد

مدیر این دسترسی را دارد که بپرسد لیستی از کاربران (که userId آن ها را می داند) در یک لیدربورد چه امتیاز هایی دارند. نحوه استفاده از این سرویس به شکل زیر می باشد:

var leaderBoard = new Backtory.LeaderBoard("<leaderboard-Id>");
var users = ["<user-Id-1>", "<user-Id-2>", "<user-Id-3>"];

leaderBoard.getUsersScore(users, {
    success: function(list) {
        for (var i = 0; i < list.length; i++) {
            context.log("userId = " + list[i].userId + ", scores = " + list[i].scores);
        }
    },

    error: function(error) {
        // The request failed
    }
});

انواع پاسخ‌هایی که از این سرویس ممکن است دریافت کنید به صورت جدول زیر است که در حالت اجرای موفقیت آمیز کالبک مربوط به success صدا زده می شود و در غیر این صورت محتویات خطا در شیء error قابل دسترسی می باشد.

نمونه‌ای از پاسخ دریافت شده برای list از این سرویس، در حالتی که درخواست موفقیت آمیز اجرا شده و کالبک success صدا زده شده است، به صورت زیر می باشد.

[
    { userId: '<user-Id-1>', scores: [175, 10, 0] },
    { userId: '<user-Id-2>', scores: [105, 50, 0] },
    { userId: '<user-Id-3>', scores: [195, 43, 0] }
]

حذف تمام کاربران یک لیدربورد

برای این‌که همه‌ی کاربران یک لیدربورد را پاک کنیم، به صورت زیر عمل می‌کنیم.

var leaderBoard = new Backtory.LeaderBoard("<leaderboard-Id>");

leaderBoard.remove({
    success: function() {
        // The request succeeded.
    },
    error: function(error) {
        // The request failed.
    }
});

به‌روزرسانی امتیاز یک کاربر خاص

مدیر می‌تواند در یک لیدربورد، امتیاز یک کاربر خاص را مستقیما به روزرسانی کند. برای این منظور به صورت زیر عمل می‌کنیم.

var leaderBoard = new Backtory.LeaderBoard("<leaderboard-Id>");
var newScores = [100, 0, 0];

leaderBoard.updateScore("<User-Id>", newScores, {
    success: function() {
        // The request succeeded.
    },

    error: function(error) {
        // The request failed.
    }
});