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

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

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

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

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

• פועלים לפי ההוראות להתקנה ולהגדרה של האפליקציה לשימוש ב-Google Play Games Services במדריך הגדרת Google Play Services SDK.
• מגדירים את לוחות הלידרים שרוצים להציג או לעדכן במשחק, לפי ההוראות שמפורטות במדריך של Google Play Console.
• מורידים את דוגמאות הקוד של לוחות הדירוג ומעיינים בהן בדף הדוגמאות ל-Android.
• כדאי לעיין בהמלצות שמפורטות ברשימת המשימות לבדיקת איכות.

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

כדי להתחיל להשתמש ב-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 יוכל לקבל את הזהות של החבילה הקוראת. בהמשך מוצגת דוגמה לממשק המשתמש של לוח הבקרה שמוגדר כברירת מחדל.