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

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

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

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

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

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

הורדת אפליקציית הלקוח של טבלת הבאז

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

עדכון הניקוד של השחקן

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

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

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

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