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

בעקבות הוצאה משימוש של Google Sign-In API, אנחנו מסירים את ה-SDK בגרסה Games v1 בשנת 2026. אחרי פברואר 2025, לא תהיה לך אפשרות לפרסם ב-Google Play משחקים ששולבו לאחרונה עם ה-SDK בגרסה Games v1. מומלץ להשתמש ב-SDK בגרסה Games v2.
פריטים קיימים עם שילובים קודמים של משחקים בגרסה 1 ימשיכו לפעול למשך כמה שנים, אבל מומלץ לעבור לגרסה 2 החל מיוני 2025.
המדריך הזה מיועד לשימוש ב-SDK של Play Games Services בגרסה 1. מידע על גרסת ה-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 יוכל לקבל את הזהות של חבילת הקריאה. למטה מוצגת דוגמה לממשק המשתמש של טבלת ברירת המחדל.