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

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

قبل البدء

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

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

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

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

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

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

الحصول على برنامج لوحات الصدارة

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