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

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

قبل البدء

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

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

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

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

• نزِّل مراجع رموز قوائم الصدارة وراجِعها في صفحة عيّنات Android على GiHub.

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

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

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