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