این راهنما به شما نشان می دهد که چگونه از API های دستاوردها در یک برنامه اندروید برای باز کردن قفل و نمایش دستاوردها در بازی خود استفاده کنید. APIها را میتوانید در بستههای com.google.android.gms.games
و com.google.android.gms.games.achievements
پیدا کنید.
قبل از شروع
اگر قبلاً این کار را نکردهاید، مرور مفاهیم بازی دستاوردها برای شما مفید خواهد بود.
قبل از شروع به کدنویسی با استفاده از API دستاوردها:
دستورالعملهای نصب و راهاندازی برنامه خود را برای استفاده از خدمات بازیهای Google Play در راهنمای راهاندازی سرویسهای SDK Google Play دنبال کنید.
با دنبال کردن دستورالعملهای راهنمای کنسول Google Play، دستاوردهایی را که میخواهید قفل بازی شما باز یا نمایش داده شود، تعریف کنید.
نمونه کد دستاوردها را در صفحه نمونه اندروید دانلود و بررسی کنید.
با توصیه هایی که در چک لیست کیفیت توضیح داده شده است آشنا شوید.
مشتری دستاوردها دریافت کنید
برای شروع استفاده از API دستاوردها، بازی شما باید ابتدا یک شیء AchievementsClient
را دریافت کند. می توانید این کار را با فراخوانی متد Games.getAchievementClient()
و عبور از اکتیویتی انجام دهید.
قفل دستاوردها را باز کنید
برای باز کردن قفل یک دستاورد، متد AchievementsClient.unlock()
را فراخوانی کرده و شناسه دستاورد را ارسال کنید.
قطعه کد زیر نشان می دهد که چگونه برنامه شما می تواند قفل دستاوردها را باز کند:
PlayGames.getAchievementsClient(this).unlock(getString(R.string.my_achievement_id));
اگر دستاورد از نوع افزایشی است (یعنی چندین مرحله برای باز کردن قفل آن لازم است)، در عوض AchievementsClient.increment()
را فراخوانی کنید.
قطعه کد زیر نشان می دهد که چگونه برنامه شما می تواند دستاورد پخش کننده را افزایش دهد:
PlayGames.getAchievementsClient(this).increment(getString(R.string.my_achievement_id), 1);
برای باز کردن قفل دستاورد نیازی به نوشتن کد اضافی ندارید. خدمات بازیهای Google Play بهصورت خودکار قفل دستاورد را پس از رسیدن به تعداد مراحل لازم باز میکند.
یک تمرین خوب این است که شناسه های دستاورد را در فایل strings.xml
تعریف کنید تا بازی شما بتواند دستاوردها را با شناسه منبع ارجاع دهد. هنگام برقراری تماس برای بهروزرسانی و بارگیری دستاوردها، مطمئن شوید که این بهترین روشها را نیز دنبال میکنید تا از تجاوز از سهمیه API خود جلوگیری کنید.
نمایش دستاوردها
برای نمایش دستاوردهای یک بازیکن، با AchievementsClient.getAchievementsIntent()
تماس بگیرید تا Intent
برای ایجاد رابط کاربری پیش فرض دستاوردها دریافت کنید. سپس بازی شما میتواند با فراخوانی startActivityForResult
UI را نمایش دهد.
قطعه کد زیر نشان می دهد که چگونه برنامه شما می تواند رابط کاربری پیش فرض دستاورد را نمایش دهد. در قطعه، RC_ACHIEVEMENT_UI
یک عدد صحیح دلخواه است که بازی از آن به عنوان کد درخواست استفاده می کند.
private static final int RC_ACHIEVEMENT_UI = 9003; private void showAchievements() { PlayGames.getAchievementsClient(this) .getAchievementsIntent() .addOnSuccessListener(new OnSuccessListener<Intent>() { @Override public void onSuccess(Intent intent) { startActivityForResult(intent, RC_ACHIEVEMENT_UI); } }); }
نمونهای از رابط کاربری پیشفرض دستاوردها در زیر نشان داده شده است.
![](https://developer.android.com/static/images/games/pgs/achievements_android.png?hl=fa)