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

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

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

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

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

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

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

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

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

הורדת אפליקציית לקוח של הישגים

כדי להתחיל להשתמש ב-Achievements 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);
        }
      });
}

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