دستاوردهای بازی های اندروید

پس از منسوخ شدن رابط برنامه‌نویسی کاربردی ورود گوگل (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.achievements پیدا کنید.

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

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

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

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

یک کلاینت دستاورد دریافت کنید

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

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

برای باز کردن قفل یک دستاورد، متد AchievementsClient.unlock() را فراخوانی کرده و شناسه دستاورد را به آن ارسال کنید.

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

Games.getAchievementsClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .unlock(getString(R.string.my_achievement_id));

اگر دستاورد از نوع افزایشی است (یعنی برای باز کردن قفل آن چندین مرحله لازم است)، به جای آن AchievementsClient.increment() را فراخوانی کنید.

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

Games.getAchievementsClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .increment(getString(R.string.my_achievement_id), 1);

برای باز کردن قفل دستاورد نیازی به نوشتن کد اضافی ندارید؛ سرویس‌های بازی‌های گوگل پلی به طور خودکار پس از رسیدن به تعداد مراحل مورد نیاز، آن را باز می‌کنند.

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

نمایش دستاوردها

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

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

private static final int RC_ACHIEVEMENT_UI = 9003;

private void showAchievements() {
  Games.getAchievementsClient(this, GoogleSignIn.getLastSignedInAccount(this))
      .getAchievementsIntent()
      .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent intent) {
          startActivityForResult(intent, RC_ACHIEVEMENT_UI);
        }
      });
}

نمونه‌ای از رابط کاربری پیش‌فرض دستاوردها در زیر نشان داده شده است.