جدول امتیازات در بازی های اندروید

این راهنما به شما نشان می‌دهد که چگونه از APIهای جدول امتیازات در یک برنامه اندروید برای ایجاد جدول امتیازات بصری، ثبت امتیاز بازیکن و مقایسه امتیاز با امتیاز بازیکن در جلسات بازی قبلی استفاده کنید. APIها را می‌توانید در بسته‌های com.google.android.gms.games و com.google.android.gms.games.leaderboards پیدا کنید.

قبل از اینکه شروع کنی

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

قبل از اینکه شروع به کدنویسی با استفاده از APIهای جدول امتیازات کنید:

• دستورالعمل‌های نصب و راه‌اندازی برنامه خود را برای استفاده از سرویس‌های بازی‌های گوگل پلی در راهنمای «راه‌اندازی کیت توسعه نرم‌افزار سرویس‌های گوگل پلی» دنبال کنید.

• با دنبال کردن دستورالعمل‌های موجود در راهنمای کنسول گوگل پلی ، جدول امتیازاتی را که می‌خواهید بازی شما نمایش دهد یا به‌روزرسانی کند، تعریف کنید.

• نمونه‌های کد جدول امتیازات را از صفحه نمونه‌های اندروید در GiHub دانلود و بررسی کنید.

• با توصیه‌های شرح داده شده در چک لیست کیفیت آشنا شوید.

کلاینت جدول امتیازات را دریافت کنید

برای شروع استفاده از API مربوط به جدول امتیازات، بازی شما ابتدا باید یک شیء LeaderboardsClient دریافت کند. می‌توانید این کار را با فراخوانی متد PlayGames.getLeadeboardsClient() و ارسال activity مربوطه انجام دهید.

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

وقتی امتیاز بازیکن تغییر می‌کند (مثلاً وقتی بازی را تمام می‌کند)، بازی شما می‌تواند با فراخوانی LeaderboardsClient.submitScore() و ارسال شناسه‌ی جدول امتیازات و مقدار خام امتیاز، امتیاز او را در جدول امتیازات به‌روزرسانی کند.

قطعه کد زیر نشان می‌دهد که چگونه برنامه شما می‌تواند امتیاز بازیکن را به‌روزرسانی کند:

PlayGames.getLeaderboardsClient(this)
    .submitScore(getString(R.string.leaderboard_id), 1337);

یک روش خوب این است که شناسه جدول امتیازات را در فایل strings.xml خود تعریف کنید، تا بازی شما بتواند با استفاده از شناسه منبع به جدول امتیازات مراجعه کند. هنگام فراخوانی برای به‌روزرسانی و بارگذاری امتیازات بازیکنان، حتماً از این بهترین شیوه‌ها نیز پیروی کنید تا از سهمیه API خود فراتر نروید.

نمایش جدول امتیازات

برای نمایش جدول امتیازات، تابع LeaderboardsClient.getLeaderboardIntent() را فراخوانی کنید تا یک Intent برای ایجاد رابط کاربری پیش‌فرض جدول امتیازات دریافت کنید. سپس بازی شما می‌تواند با فراخوانی startActivityForResult رابط کاربری را نمایش دهد.

قطعه کد زیر نشان می‌دهد که چگونه برنامه شما می‌تواند امتیاز بازیکن را به‌روزرسانی کند. در قطعه کد، RC_LEADERBOARD_UI یک عدد صحیح دلخواه برای کد درخواست است.

private static final int RC_LEADERBOARD_UI = 9004;

private void showLeaderboard() {
  PlayGames.getLeaderboardsClient(this)
      .getLeaderboardIntent(getString(R.string.leaderboard_id))
      .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent intent) {
          startActivityForResult(intent, RC_LEADERBOARD_UI);
        }
      });
}

حتی اگر هیچ نتیجه‌ای برگردانده نشود، شما باید از startActivityForResult استفاده کنید تا API بتواند هویت بسته فراخوانی شده را بدست آورد. نمونه‌ای از رابط کاربری پیش‌فرض جدول امتیازات در زیر نشان داده شده است.