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

پس از منسوخ شدن رابط برنامه‌نویسی کاربردی ورود گوگل (Google Sign-In API)، ما در سال ۲۰۲۶ کیت توسعه نرم‌افزاری بازی‌ها نسخه ۱ (games v1 SDK) را حذف خواهیم کرد. پس از فوریه ۲۰۲۵، شما قادر به انتشار عناوینی که به تازگی با کیت توسعه نرم‌افزاری بازی‌ها نسخه ۱ (games v1 SDK) ادغام شده‌اند، در گوگل پلی نخواهید بود. توصیه می‌کنیم به جای آن از کیت توسعه نرم‌افزاری بازی‌ها نسخه ۲ (games v2 SDK) استفاده کنید.
در حالی که عناوین موجود با بازی‌های قبلی نسخه ۱ ادغام‌شده تا چند سال دیگر به کار خود ادامه می‌دهند، توصیه می‌شود از ژوئن ۲۰۲۵ به نسخه ۲ مهاجرت کنید .
این راهنما برای استفاده از SDK نسخه ۱ سرویس بازی‌های Play Games Services است. برای اطلاعات بیشتر در مورد آخرین نسخه SDK، به مستندات نسخه ۲ مراجعه کنید.

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

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

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

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

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

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

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

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

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

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

Games.getLeaderboardsClient(this, GoogleSignIn.getLastSignedInAccount(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() {
  Games.getLeaderboardsClient(this, GoogleSignIn.getLastSignedInAccount(this))
      .getLeaderboardIntent(getString(R.string.leaderboard_id))
      .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent intent) {
          startActivityForResult(intent, RC_LEADERBOARD_UI);
        }
      });
}

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