قوائم الصدارة في ألعاب 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.leaderboards.

قبل البدء

ننصحك بمراجعة مفاهيم ألعاب قوائم الصدارة إذا لم يسبق لك ذلك.

قبل بدء الترميز باستخدام واجهات برمجة تطبيقات قوائم الصدارة:

الحصول على عميل لوحات الصدارة

لبدء استخدام واجهة برمجة تطبيقات لوحات الصدارة، يجب أن تحصل لعبتك أولاً على عنصر LeaderboardsClient. يمكنك إجراء ذلك من خلال استدعاء طريقة Games.getLeadeboardsClient() وضبط القيمة activity وGoogleSignInAccount للمشغّل الحالي. للتعرّف على كيفية استرداد معلومات حساب اللاعب، يُرجى الاطّلاع على مقالة تسجيل الدخول في ألعاب Android.

تعديل نتيجة اللاعب

عندما تتغيّر نتيجة اللاعب (على سبيل المثال، عندما ينتهي اللاعب من اللعبة)، يمكن لتطبيقك تعديل النتيجة في قائمة الصدارة من خلال استدعاء LeaderboardsClient.submitScore()، وإرسال معرّف قائمة الصدارة وقيمة النتيجة الأولية.

يوضّح المقتطف التالي من الرمز البرمجي كيفية تعديل تطبيقك لنتيجة اللاعب:

Games.getLeaderboardsClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .submitScore(getString(R.string.leaderboard_id), 1337);

من أفضل الممارسات تحديد معرّف لوحة الصدارة في ملف strings.xml، حتى تتمكّن لعبتك من الإشارة إلى لوحات الصدارة حسب معرّف المورد. عند إجراء طلبات لتعديل نتائج اللاعبين وتحميلها، احرص أيضًا على اتّباع أفضل الممارسات التالية لتجنُّب تجاوز حصة واجهة برمجة التطبيقات.

عرض قائمة صدارة

لعرض لوحة الصدارة، اتصل بـ LeaderboardsClient.getLeaderboardIntent() للحصول على Intent لإنشاء واجهة مستخدِم لوحة الصدارة التلقائية. يمكن لتطبيق لعبتك بعد ذلك عرض واجهة المستخدم من خلال استدعاء رمز startActivityForResult.

يوضّح مقتطف الرمز البرمجي التالي كيفية تعديل تطبيقك لنتيجة اللاعب. في مقتطف الرمز، RC_LEADERBOARD_UI هو عدد صحيح عشوائي لرمز الطلب.

private static final int RC_LEADERBOARD_UI = 9004;

private void showLeaderboard() {
  Games.getLeaderboardsClient(this, GoogleSignIn.getLastSignedInAccount(this))
      .getLeaderboardIntent(getString(R.string.leaderboard_id))
      .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent intent) {
          startActivityForResult(intent, RC_LEADERBOARD_UI);
        }
      });
}

يُرجى العِلم أنّه على الرغم من عدم عرض أي نتيجة، علينا استخدام startActivityForResult كي تتمكّن واجهة برمجة التطبيقات من الحصول على هوية حزمة الاستدعاء. في ما يلي مثال على واجهة مستخدم الترتيب التلقائي للقوائم.