דף זה תורגם על ידי Cloud Translation API.

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

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

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

כדי להשיג הישג, מפעילים את השיטה 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);
        }
      });
}

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