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

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

قبل البدء

ننصحك بمراجعة مفاهيم ألعاب الإنجازات إذا لم يسبق لك ذلك.

قبل بدء الترميز باستخدام واجهة برمجة تطبيقات الإنجازات:

الحصول على عميل إنجاز

لبدء استخدام واجهة برمجة التطبيقات "إنجازات 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);
        }
      });
}

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