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

بعد إيقاف واجهة برمجة التطبيقات Google Sign-In نهائيًا، سنزيل الإصدار v1 من حزمة تطوير البرامج (SDK) للألعاب في عام 2026. بعد فبراير (شباط) 2025، لن يكون بإمكانك نشر الألعاب التي تم دمجها حديثًا مع الإصدار v1 من حزمة SDK للألعاب على Google Play. ننصحك باستخدام الإصدار 2 من حزمة SDK للألعاب بدلاً من ذلك.
على الرغم من أنّ العناوين الحالية التي تم دمجها مع الإصدار السابق من حزمة SDK للألعاب ستظل تعمل لعدة سنوات، ننصحك بنقل بياناتها إلى الإصدار 2 اعتبارًا من حزيران (يونيو) 2025.
يتناول هذا الدليل استخدام حزمة تطوير البرامج (SDK) للإصدار 1 من "خدمات ألعاب Play". للحصول على معلومات عن أحدث إصدار من حزمة SDK، يُرجى الاطّلاع على مستندات الإصدار 2.

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

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