לוחות לידרבורד במשחקי Android

בעקבות ההוצאה משימוש של ה-API של התחברות באמצעות חשבון Google, בשנת 2026 אנחנו מסירים את גרסה 1 של ה-SDK שהייתה זמינה למשחקים. החל מפברואר 2025, לא תהיה לך אפשרות לפרסם ב-Google Play משחקים שה-SDK בגרסה הזו שולב בהם לאחרונה. מומלץ להשתמש בגרסה 2 של ה-SDK למשחקים.
פריטים קיימים עם גרסה 1 ימשיכו לפעול בשנים הקרובות, אבל מומלץ לעבור לגרסה 2 החל מיוני 2025.
המדריך הזה מיועד לגרסה 1 של ה-SDK של Play Games Services. מידע על גרסת ה-SDK העדכנית זמין במאמרי העזרה בנושא גרסה 2.

במדריך הזה נסביר איך להשתמש בממשקי ה-API של לוחות הלידרבורד באפליקציות ל-Android כדי ליצור לוחות לידרבורד חזותיים, לתעד את הניקוד של השחקן ולהשוות את הניקוד לניקוד של השחקן מסשנים קודמים של המשחק. ממשקי ה-API נכללים בחבילות com.google.android.gms.games ו-com.google.android.gms.games.leaderboards.

לפני שמתחילים

אם עדיין לא עשיתם זאת, אנחנו ממליצים לכם להכיר את המושגים שקשורים לטבלאות המובילים במשחקים.

לפני שמתחילים לכתוב קוד באמצעות ממשקי ה-API של טבלאות המובילים:

קבלת לקוח הלידרבורד

כדי להתחיל להשתמש ב-Leaderboards API, המשחק שלכם צריך קודם לקבל אובייקט LeaderboardsClient. כדי לעשות את זה, מפעילים את השיטה Games.getLeadeboardsClient() ומעבירים את הפעילות ואת GoogleSignInAccount של השחקן הנוכחי. במאמר כניסה למשחקי Android מוסבר איך לאחזר את פרטי חשבון השחקן.

עדכון התוצאה של השחקן

כשהניקוד של השחקן משתנה (לדוגמה, כשהשחקן מסיים את המשחק), המשחק יכול לעדכן את הניקוד בטבלת המובילים על ידי קריאה אל LeaderboardsClient.submitScore() והעברת מזהה טבלת המובילים וערך הניקוד הגולמי.

בקטע הקוד הבא מוצג איך האפליקציה יכולה לעדכן את הניקוד של השחקן:

Games.getLeaderboardsClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .submitScore(getString(R.string.leaderboard_id), 1337);

מומלץ להגדיר את מזהה הלידרבורד בקובץ strings.xml, כדי שהמשחק יוכל להתייחס ללידרבורד לפי מזהה המשאב. כשמבצעים קריאות כדי לעדכן ולטעון את הניקוד של השחקן, חשוב לפעול לפי השיטות המומלצות האלה כדי להימנע מחריגה ממכסת ה-API.

הצגת לידרבורד

כדי להציג את הלידרבורד, קוראים ל-LeaderboardsClient.getLeaderboardIntent() כדי לקבל Intent וליצור את ממשק המשתמש של הלידרבורד שמוגדר כברירת מחדל. כדי להציג את ממשק המשתמש במשחק, אפשר לקרוא ל-startActivityForResult.

בקטע הקוד הבא מוצג איך האפליקציה יכולה לעדכן את הניקוד של השחקן. בקטע הקוד, RC_LEADERBOARD_UI הוא מספר שלם שרירותי לקוד הבקשה.

private static final int RC_LEADERBOARD_UI = 9004;

private void showLeaderboard() {
  Games.getLeaderboardsClient(this, GoogleSignIn.getLastSignedInAccount(this))
      .getLeaderboardIntent(getString(R.string.leaderboard_id))
      .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent intent) {
          startActivityForResult(intent, RC_LEADERBOARD_UI);
        }
      });
}

שימו לב: גם אם לא מוחזרת תוצאה, צריך להשתמש ב-startActivityForResult כדי שה-API יוכל לקבל את הזהות של חבילת הקריאה. למטה מוצגת דוגמה לממשק המשתמש של טבלת ברירת המחדל.