הישגים במשחקי 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

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

קבלת הישגים חדשים

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

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

Games.getAchievementsClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .unlock(getString(R.string.my_achievement_id));

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

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

Games.getAchievementsClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .increment(getString(R.string.my_achievement_id), 1);

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

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

הצגת ההישגים

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

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

private static final int RC_ACHIEVEMENT_UI = 9003;

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

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