قوائم الصدارة في ألعاب 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.getLeaderboardsClient() وتمرير النشاط.

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

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