يوضح لك هذا الدليل كيفية استخدام واجهات برمجة تطبيقات الإنجازات في أحد تطبيقات Android
لإتاحة الإنجازات في لعبتك وعرضها. يمكن العثور على واجهات برمجة التطبيقات
في حِزم com.google.android.gms.games
وcom.google.android.gms.games.achievements
.
قبل البدء
ننصحك بمراجعة مفاهيم ألعاب الإنجازات إذا لم يسبق لك ذلك.
قبل بدء الترميز باستخدام واجهة برمجة تطبيقات الإنجازات:
- اتّبِع تعليمات تثبيت تطبيقك وإعداده لاستخدام "خدمات ألعاب Google Play" في دليل إعداد حزمة تطوير البرامج (SDK) لـ "خدمات Google Play".
- حدِّد الإنجازات التي تريد أن تمنح لعبتك مكافآت لها أو تعرضها، وذلك من خلال اتّباع التعليمات الواردة في دليل Google Play Console.
- نزِّل واطّلِع على نماذج رموز الإنجازات في صفحة نماذج Android.
- اطّلِع على الاقتراحات الموضّحة في قائمة التحقّق من الجودة.
الحصول على عميل إنجاز
لبدء استخدام واجهة برمجة التطبيقات "إنجازات Google Play"، يجب أن تحصل لعبتك أولاً على عنصر
AchievementsClient
. يمكنك إجراء ذلك من خلال تنفيذ الإجراء Games.getAchievementClient()
وتمرير النشاط وGoogleSignInAccount
للّاعب الحالي. للتعرّف على كيفية استرداد
معلومات حساب اللاعب، يُرجى الاطّلاع على مقالة تسجيل الدخول في ألعاب Android.
فتح الإنجازات
لفتح قفل إنجاز، استخدِم الطريقة 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);
لست بحاجة إلى كتابة رمز إضافي لفتح الإنجاز، لأنّ "خدمات ألعاب Play" تفتح الإنجاز تلقائيًا عند بلوغ العدد المطلوب من الخطوات.
من الممارسات الجيدة تحديد أرقام تعريف الإنجازات في ملف strings.xml
، لكي تتمكّن
لعبتك من الإشارة إلى الإنجازات حسب رقم تعريف المورد. عند إجراء طلبات لتعديل الإنجاز وتحميله، احرص أيضًا على اتّباع أفضل الممارسات التالية لتجنّب تجاوز حصة واجهة برمجة التطبيقات.
عرض الإنجازات
لعرض إنجازات اللاعب، اتصل بـ 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); } }); }
في ما يلي مثال على واجهة مستخدم الإنجازات التلقائية.