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

يوضّح لك هذا الدليل كيفية استخدام واجهات برمجة التطبيقات الخاصة بالإنجازات في تطبيق 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);
        }
      });
}

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