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

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

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

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

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

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

קבלת לקוח של 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);
        }
      });
}

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