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

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

قبل البدء

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

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

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

لبدء استخدام واجهة برمجة تطبيقات الإنجازات، يجب أن تحصل لعبتك أولاً على كائن 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);

لست بحاجة إلى كتابة رمز إضافي لفتح الإنجاز، لأنّ "خدمات ألعاب 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);
        }
      });
}

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