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

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

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

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

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

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

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

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

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

כשהניקוד של השחקן משתנה (לדוגמה, כשהשחקן מסיים את המשחק), המשחק יכול לעדכן את הנקודה שלו בלוח הדירוג באמצעות קריאה ל-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 יוכל להשיג את הזהות של חבילת הקריאה. בהמשך מוצגת דוגמה לממשק המשתמש של לוח הבקרה שמוגדר כברירת מחדל.