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

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

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