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

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

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

قبل البدء

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

قبل البدء في كتابة الرموز البرمجية باستخدام Achievements API، يجب:

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

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

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