אירועים במשחקים ל-Android

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

במדריך הזה מוסבר איך לאסוף נתוני משחק של שחקנים כדי לנתח את נתוני המשחקים באמצעות ממשקי ה-API של האירועים ב-Google Play Games Services. ממשקי ה-API נמצאים בחבילות com.google.android.gms.games.event ו-com.google.android.gms.games.

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

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

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

קריאה לשיטה של האירועים

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

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

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

כדי לשלוח עדכון של אירוע, מפעילים את הפונקציה 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(). בהפעלת method, מעבירים ערך בוליאני כדי לציין אם שירותי Google Play Games צריכים לנקות את הנתונים ששמורים במטמון באופן מקומי במכשיר של המשתמש.

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

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