הישגים במשחקי Android

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

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

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

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

• מתקינים ומגדירים את האפליקציה לפי ההוראות לשימוש ב-Google Play Games Services שמופיעות במדריך להגדרת Google Play Services SDK.

• מגדירים את ההישגים שרוצים שהמשחק יציג או יאפשר להשיג, לפי ההוראות במדריך ל-Google Play Console.

• מורידים ומעיינים בדוגמאות הקוד של ההישגים שמופיעות בדף הדוגמאות ל-Android.

• מעיינים בהמלצות שמופיעות ברשימת המשימות לאיכות.

קריאה לשיטה של ההישגים

כדי להתחיל להשתמש בממשק ה-API של ההישגים, המשחק שלכם צריך קודם לקבל אובייקט AchievementsClient. כדי לעשות את זה, קוראים לשיטה Games.getAchievementClient() ומעבירים את הפעילות.

איך להעניק הישגים

כדי להעניק הישגים, צריך לבצע קריאה ל-method‏ AchievementsClient.unlock() ולהעביר את מזהה ההישג.

קטע הקוד הבא מראה איך האפליקציה יכולה להעניק הישגים:

PlayGames.getAchievementsClient(this).unlock(getString(R.string.my_achievement_id));

אם ההישג הוא מסוג מצטבר (כלומר, נדרשים כמה שלבים כדי לזכות בו), צריך לקרוא ל-AchievementsClient.increment() במקום זאת.

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

PlayGames.getAchievementsClient(this).increment(getString(R.string.my_achievement_id), 1);

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

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

הצגת ההישגים

כדי להציג את ההישגים של שחקן או שחקנית, קוראים ל-AchievementsClient.getAchievementsIntent() כדי לקבל Intent וליצור את ממשק המשתמש של ההישגים שמוגדר כברירת מחדל. כדי להציג את ממשק המשתמש במשחק, אפשר לקרוא ל-startActivityForResult.

בקטע הקוד הבא אפשר לראות איך האפליקציה יכולה להציג של ממשק המשתמש של ההישגים שמוגדר כברירת מחדל. בקטע הקוד, RC_ACHIEVEMENT_UI הוא מספר שלם שרירותי שהמשחק משתמש בו כקוד הבקשה.

private static final int RC_ACHIEVEMENT_UI = 9003;

private void showAchievements() {
  PlayGames.getAchievementsClient(this)
      .getAchievementsIntent()
      .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent intent) {
          startActivityForResult(intent, RC_ACHIEVEMENT_UI);
        }
      });
}

בהמשך מוצגת דוגמה לממשק המשתמש של ההישגים שמוגדר כברירת מחדל.