لوحات الصدارة في لعبة Android

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

قبل البدء

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

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

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

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