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

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

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

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

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

• פועלים לפי ההוראות להתקנה ולהגדרה של האפליקציה לשימוש ב-Google Play Games Services במדריך הגדרת ה-SDK של Google Play Services.
• מגדירים את ההישגים שרוצים שהמשחק יפתח או יציג, לפי ההוראות שמפורטות במדריך של 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);
        }
      });
}

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