אירועים במשחקים ל-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 של האירועים שמוצעים על ידי Google Play Games Services. ממשקי ה-API נמצאים ב-com.google.android.gms.games.event וב-com.google.android.gms.games.

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

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

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

• מגדירים את האירועים במשחק ב-Google Play Console.
• פועלים לפי ההמלצות שבצ'קליסט לכניסה.

קבלת הלקוח של האירועים

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

שליחת אירועים

אתם יכולים להוסיף קוד למשחק כדי לשלוח הודעה לשירותי המשחקים של Google Play בכל פעם שמתרחש אירוע שמעניין את המשחק.

כדי לשלוח עדכון של אירוע, קוראים ל-EventsClient.increment() עם הערך eventId ומספר שלם incrementAmount שגדול מ-0 או שווה לו.

• המזהה eventId נוצר על ידי Google Play Games Services כשמגדירים את האירוע בפעם הראשונה ב-Google Play Console, והוא משמש לזיהוי ייחודי של האירוע במשחק.
• אפשר להשתמש בקלט incrementAmount כדי לציין את ההתקדמות הכמותית של השחקן לקראת השלמת יעד ספציפי במשחק. לדוגמה, אם האירוע שרוצים לעקוב אחריו במשחק הוא 'הבסת 500 מפלצות עם עיניים גדולות', הערך של incrementAmount יכול להיות מספר המפלצות שהשחקן הרג בקרב אחד.

דוגמה לשליחת אירוע עם סכום הגדלה של 1:

public void submitEvent(String eventId) {
  Games.getEventsClient(this, GoogleSignIn.getLastSignedInAccount(this))
      .increment(eventId, 1);
}

אחזור אירועים

אפשר לאחזר את כל נתוני האירועים שמאוחסנים בשרתי Google עבור המשחק שלכם באמצעות קריאה ל-EventsClient.load(). בשיחה לשיטה, מעבירים ערך בוליאני כדי לציין אם שירותי Google Play Games צריכים לנקות את הנתונים ששמורים במטמון באופן מקומי במכשיר של המשתמש.

כדי לאחזר נתונים של אירועים ספציפיים שהגדרתם ב-Google Play Console, צריך לקרוא ל-EventsClient.loadByIds() ולהעביר מערך של מזהי אירועים בפרמטרים של הקלט.

בקטע הקוד הבא אפשר לראות איך שולחים שאילתה אל Play Games Services כדי לקבל את רשימת כל האירועים במשחק:

public void loadEvents() {
  Games.getEventsClient(this, GoogleSignIn.getLastSignedInAccount(this))
      .load(true)
      .addOnCompleteListener(new OnCompleteListener<AnnotatedData<EventBuffer>>() {
        @Override
        public void onComplete(@NonNull Task<AnnotatedData<EventBuffer>> task) {
          if (task.isSuccessful()) {
            // Process all the events.
            for (Event event : task.getResult().get()) {
              Log.d(TAG, "loaded event " + event.getName());
            }
          } else {
            // Handle Error
            Exception exception = task.getException();
            int statusCode = CommonStatusCodes.DEVELOPER_ERROR;
            if (exception instanceof ApiException) {
              ApiException apiException = (ApiException) exception;
              statusCode = apiException.getStatusCode();
            }
            showError(statusCode);
          }
        }
      });
}