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

قبل البدء

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

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

• اتّبِع التعليمات الخاصة بتثبيت تطبيقك وإعداده لاستخدام "خدمات ألعاب Google Play" في دليل إعداد حزمة تطوير البرامج (SDK) الخاصة بـ "خدمات Google Play".
• حدِّد قوائم الصدارة التي تريد أن تعرضها لعبتك أو تعدّلها، وذلك باتّباع التعليمات الواردة في دليل Google Play Console.
• يمكنك تنزيل عيّنات التعليمات البرمجية الخاصة بلوحات الصدارة ومراجعتها في صفحة عيّنات Android.
• تعرَّف على الاقتراحات الموضّحة في قائمة التحقّق من الجودة.

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

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

ملاحظة: تستخدم الفئة LeaderboardsClient فئة Task من "خدمات Google Play" لعرض النتائج بشكل غير متزامن. لمزيد من المعلومات حول استخدام المهام لإدارة العمل المتسلسل، يُرجى الاطّلاع على دليل المطوّر لواجهة Tasks API.

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

عندما تتغيّر نتيجة اللاعب (على سبيل المثال، عندما ينهي اللاعب اللعبة)، يمكن للعبتك تعديل النتيجة في قائمة الصدارة من خلال استدعاء 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 حتى تتمكّن واجهة برمجة التطبيقات من الحصول على هوية الحزمة التي يتم استدعاؤها. في ما يلي مثال على واجهة المستخدم التلقائية للوحة الصدارة.