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

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

قبل البدء

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

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

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

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

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