يوضِّح لك هذا الدليل كيفية استخدام واجهات برمجة التطبيقات "لوحات الصدارة" في أحد تطبيقات Android لإنشاء لوحات صدارة مرئية وتسجيل نتيجة لاعب ومقارنة النتيجة
مقابل نتيجة اللاعب في جلسات الألعاب السابقة. يمكن العثور على واجهات برمجة التطبيقات
في حِزمتَي com.google.android.gms.games
وcom.google.android.gms.games.leaderboards
.
قبل البدء
قد يكون من المفيد مراجعة مفاهيم ألعاب لوحات الصدارة إذا لم تكن قد راجعتها من قبل.
قبل البدء في الترميز باستخدام واجهات برمجة التطبيقات الخاصة بلوحات الصدارة:
اتّبِع التعليمات الخاصة بتثبيت تطبيقك وإعداده لاستخدام "خدمات ألعاب Google Play" الواردة في دليل إعداد حزمة تطوير البرامج (SDK) لخدمات Google Play.
حدِّد لوحات الصدارة التي تريد عرضها أو تحديثها في لعبتك، من خلال اتّباع التعليمات الواردة في دليل Google Play Console.
يمكنك تنزيل نماذج رموز قوائم الصدارة ومراجعتها في صفحة نماذج Android على GiHub.
ننصحك بالتعرّف على الاقتراحات الموضّحة في قائمة التحقّق من الجودة.
الحصول على عميل "لوحات الصدارة"
لبدء استخدام واجهة برمجة التطبيقات "لوحات الصدارة"، يجب أن تحصل لعبتك أولاً على عنصر 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
لكي تتمكن واجهة برمجة التطبيقات من الحصول على هوية حزمة الطلب. يظهر أدناه مثال على واجهة المستخدم
الافتراضية للوحة الصدارة.