לוחות לידרבורד במשחקי 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 ב-GiHub.

• כדאי לעיין בהמלצות שמפורטות ברשימת המשימות לבדיקת איכות.

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

כדי להתחיל להשתמש ב-Leaderboards API, המשחק צריך לקבל קודם אובייקט LeaderboardsClient. כדי לעשות זאת, קוראים ל-method‏ PlayGames.getLeadeboardsClient() ומעבירים את הפעילות.

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

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

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

PlayGames.getLeaderboardsClient(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() {
  PlayGames.getLeaderboardsClient(this)
      .getLeaderboardIntent(getString(R.string.leaderboard_id))
      .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent intent) {
          startActivityForResult(intent, RC_LEADERBOARD_UI);
        }
      });
}

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