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