הישגים במשחקי 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() ולהעביר את הפעילות.

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

כדי לפתוח הישג, צריך לבצע קריאה ל-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);
        }
      });
}

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