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

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

قبل البدء

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

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

• اتّبِع التعليمات لتثبيت تطبيقك وإعداده لاستخدامه. "خدمات ألعاب Google Play" في دليل إعداد حزمة تطوير البرامج (SDK) لخدمات Google Play

• حدِّد لوحات الصدارة التي تريد أن تعرضها لعبتك أو تعديلها من خلال باتباع التعليمات الواردة في دليل Google Play Console

• يمكنك تنزيل نماذج رموز لوحات الصدارة ومراجعتها في صفحة نماذج Android على GiHub.

• تعرف على التوصيات الموضحة في قائمة التحقّق من الجودة:

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

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

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

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

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

PlayGames.getLeaderboardsClient(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() {
  PlayGames.getLeaderboardsClient(this)
      .getLeaderboardIntent(getString(R.string.leaderboard_id))
      .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent intent) {
          startActivityForResult(intent, RC_LEADERBOARD_UI);
        }
      });
}

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