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