تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
بعد إيقاف واجهة برمجة التطبيقات
Google Sign-In API
نهائيًا، سنزيل حزمة تطوير البرامج (SDK) لألعاب الإصدار 1 في عام 2026. بعد شباط (فبراير) 2025، لن تتمكّن من نشر
العناوين التي تم دمجها حديثًا مع حزمة تطوير البرامج (SDK) لإصدار 1 من "ألعاب Google Play" على Google Play. ننصحك باستخدام
حزمة تطوير البرامج (SDK) لإصدار 2 من "ألعاب Google Play" بدلاً من ذلك.
على الرغم من أنّ العناوين الحالية التي تم دمجها مع الإصدار 1 من الألعاب السابقة ستظل تعمل لعدة
سنوات، ننصحك بنقل بياناتها إلى الإصدار 2
اعتبارًا من حزيران (يونيو) 2025.
يتناول هذا الدليل استخدام حزمة تطوير البرامج (SDK) لإصدار 1 من "خدمات ألعاب Play". للحصول على معلومات
عن أحدث إصدار من حزمة SDK، يُرجى الاطّلاع على
مستندات الإصدار 2.
يوضّح لك هذا الدليل كيفية استخدام واجهات برمجة التطبيقات الخاصة بلوحات الصدارة في تطبيق Android
لإنشاء لوحات صدارة مرئية وتسجيل نتيجة اللاعب ومقارنة النتيجة
بنتيجة اللاعب من جلسات اللعب السابقة. يمكن العثور على واجهات برمجة التطبيقات
في حِزم com.google.android.gms.games
وcom.google.android.gms.games.leaderboards.
عندما تتغيّر نتيجة اللاعب (على سبيل المثال، عندما ينتهي اللاعب من اللعبة)، يمكن لتطبيقك تعديل النتيجة في قائمة الصدارة من خلال استدعاء LeaderboardsClient.submitScore()،
وإرسال معرّف قائمة الصدارة وقيمة النتيجة الأولية.
يوضّح المقتطف التالي من الرمز البرمجي كيفية تعديل تطبيقك لنتيجة اللاعب:
من أفضل الممارسات تحديد معرّف لوحة الصدارة في ملف strings.xml، حتى تتمكّن
لعبتك من الإشارة إلى لوحات الصدارة حسب معرّف المورد. عند إجراء طلبات لتعديل نتائج اللاعبين وتحميلها، احرص أيضًا على اتّباع أفضل الممارسات التالية لتجنُّب تجاوز حصة واجهة برمجة التطبيقات.
يُرجى العِلم أنّه على الرغم من عدم عرض أي نتيجة، علينا استخدام
startActivityForResult
كي تتمكّن واجهة برمجة التطبيقات من الحصول على هوية حزمة الاستدعاء. في ما يلي مثال على واجهة مستخدم الترتيب التلقائي
للقوائم.
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Leaderboards in Android games\n\nFollowing the deprecation of the\n[Google Sign-In](https://android-developers.googleblog.com/2024/09/streamlining-android-authentication-credential-manager-replaces-legacy-apis.html)\nAPI, we are removing the games v1 SDK in 2026. After February 2025, you will be unable to publish\ntitles that are newly integrated with games v1 SDK, on Google Play. We recommend that you use the\ngames v2 SDK instead. \n\nWhile existing titles with the previous games v1 integrations continue to function for a\ncouple of years, you are encouraged to\n[migrate to v2](/games/pgs/android/migrate-to-v2)\nstarting June 2025. \n\nThis guide is for using the Play Games Services v1 SDK. For information\non the latest SDK version, see the\n[v2 documentation](/games/pgs/android/leaderboards).\n\nThis guide shows you how to use leaderboards APIs in an Android application\nto create visual leaderboards, record a player's score, and compare the score\nagainst the player's score from previous game sessions. The APIs can be found\nin the [`com.google.android.gms.games`](https://developers.google.com/android/reference/com/google/android/gms/games/package-summary)\nand [`com.google.android.gms.games.leaderboards`](https://developers.google.com/android/reference/com/google/android/gms/games/leaderboard/package-summary) packages.\n\nBefore you begin\n----------------\n\nIf you haven't already done so, you might find it helpful to review the\n[leaderboards game concepts](/games/pgs/leaderboards).\n\nBefore you start to code using the leaderboards APIs:\n\n- Follow the instructions for installing and setting up your app to use Google Play Games Services in the [Set Up Google Play Services SDK](https://developers.google.com/android/guides/setup) guide.\n- Define the leaderboards that you want your game to display or update, by following the instructions in the [Google Play Console guide](/games/pgs/leaderboards#create_a_leaderboard).\n- Download and review the leaderboards code samples in the [Android samples page](https://github.com/playgameservices/android-basic-samples).\n- Familiarize yourself with the recommendations described in [Quality Checklist](/games/pgs/v1/quality).\n\nGet the leaderboards client\n---------------------------\n\nTo start using the leaderboards API, your game must first obtain a [`LeaderboardsClient`](https://developers.google.com/android/reference/com/google/android/gms/games/LeaderboardsClient) object.\nYou can do this by calling the [`Games.getLeadeboardsClient()`](https://developers.google.com/android/reference/com/google/android/gms/games/Games.html#getLeaderboardsClient(android.app.Activity,%20com.google.android.gms.auth.api.signin.GoogleSignInAccount)) method and passing in the\nactivity and the [`GoogleSignInAccount`](https://developers.google.com/android/reference/com/google/android/gms/auth/api/signin/GoogleSignInAccount) for the current player. To learn how to retrieve the\nplayer account information, see [Sign-in in Android Games](/games/pgs/v1/android/signin).\n| **Note:** The [`LeaderboardsClient`](https://developers.google.com/android/reference/com/google/android/gms/games/LeaderboardsClient) class makes use of the Google Play services Task class to return results asynchronously. To learn more about using tasks to manage threaded work, see the [Tasks API developer guide](https://developers.google.com/android/guides/tasks).\n\nUpdate the player's score\n-------------------------\n\nWhen the player's score changes (for example, when the player finishes the game), your\ngame can update their score on the leaderboard by calling [`LeaderboardsClient.submitScore()`](https://developers.google.com/android/reference/com/google/android/gms/games/LeaderboardsClient.html#submitScore(java.lang.String,%20long,%20java.lang.String)),\nand passing in the leaderboard ID and the raw score value.\n\nThe following code snippet shows how your app can update the player's score: \n\n```scdoc\nGames.getLeaderboardsClient(this, GoogleSignIn.getLastSignedInAccount(this))\n .submitScore(getString(R.string.leaderboard_id), 1337);\n```\n\nA good practice is to define the leaderboard ID in your `strings.xml` file, so\nyour game can reference the leaderboards by resource ID. When making calls to\nupdate and load player scores, make sure to also follow these\n[best practices](/games/pgs/v1/quality) to avoid exceeding your API quota.\n\nDisplay a leaderboard\n---------------------\n\nTo display leaderboard, call [`LeaderboardsClient.getLeaderboardIntent()`](https://developers.google.com/android/reference/com/google/android/gms/games/LeaderboardsClient.html#getLeaderboardIntent(java.lang.String)) to get an\n[`Intent`](/reference/android/content/Intent) to\ncreate the default leaderboard user interface. Your game can then bring up the UI by calling\n[`startActivityForResult`](/reference/android/app/Activity#startActivityForResult(android.content.Intent,%20int)).\n\nThe following code snippet shows how your app can update the player's score. In the\ncode snippet, `RC_LEADERBOARD_UI` is an arbitrary integer for the request code. \n\n```transact-sql\nprivate static final int RC_LEADERBOARD_UI = 9004;\n\nprivate void showLeaderboard() {\n Games.getLeaderboardsClient(this, GoogleSignIn.getLastSignedInAccount(this))\n .getLeaderboardIntent(getString(R.string.leaderboard_id))\n .addOnSuccessListener(new OnSuccessListener\u003cIntent\u003e() {\n @Override\n public void onSuccess(Intent intent) {\n startActivityForResult(intent, RC_LEADERBOARD_UI);\n }\n });\n}\n```\n\nNotice that even though no result is returned, we have to use\n[`startActivityForResult`](/reference/android/app/Activity#startActivityForResult(android.content.Intent,%20int))\nso that the API can obtain the identity of the calling package. An example of the default\nleaderboard UI is shown below."]]
