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

בעקבות הוצאה משימוש של Google Sign-In API, אנחנו מסירים את ה-SDK בגרסה Games v1 בשנת 2026. אחרי פברואר 2025, לא תהיה לך אפשרות לפרסם ב-Google Play משחקים ששולבו לאחרונה עם ה-SDK בגרסה Games v1. מומלץ להשתמש ב-SDK בגרסה Games v2.
משחקים קיימים עם שילובים קודמים של Games v1 ימשיכו לפעול למשך כמה שנים, אבל מומלץ לעבור לגרסה 2 החל מיוני 2025.
המדריך הזה מיועד לשימוש ב-Play Games Services SDK בגרסה 1. מידע על גרסת ה-SDK העדכנית זמין במאמרי העזרה בנושא גרסה 2.

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

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

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

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

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

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

איך להגיע להישגים חדשים

כדי להשיג מטרה במשחק, צריך לבצע קריאה ל-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 Services מבטלת את נעילת ההישג באופן אוטומטי כשהיא מגיעה למספר השלבים הנדרש.

מומלץ להגדיר את מזהי ההישגים בקובץ 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);
        }
      });
}

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