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

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

قبل البدء

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

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

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

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