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

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

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

قبل البدء

إذا لم يسبق لك إجراء ذلك، قد يكون من المفيد مراجعة مفاهيم اللعبة المتعلقة بالإنجازات.

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

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

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

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

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