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