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

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

قبل البدء

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

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

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

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

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