قوائم الصدارة في ألعاب Android

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

قبل البدء

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

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

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

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

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