إنجازات ألعاب Android

يوضّح لك هذا الدليل كيفية استخدام واجهات برمجة التطبيقات الخاصة بالإنجازات في تطبيق Android لإتاحة الإنجازات وعرضها في لعبتك. يمكن العثور على واجهات برمجة التطبيقات في حزمتَي com.google.android.gms.games وcom.google.android.gms.games.achievements.

قبل البدء

إذا لم يسبق لك إجراء ذلك، قد يكون من المفيد مراجعة مفاهيم اللعبة المتعلقة بالإنجازات.

قبل البدء في كتابة الرموز البرمجية باستخدام واجهة برمجة التطبيقات الخاصة بالإنجازات، عليك اتّباع ما يلي:

• اتّبِع التعليمات الخاصة بتثبيت تطبيقك وإعداده لاستخدام حزمة تطوير البرامج (SDK) الخاصة بـ "خدمات ألعاب 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);
        }
      });
}

في ما يلي مثال على واجهة المستخدم التلقائية للإنجازات.