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

בעקבות ההוצאה משימוש של ה-API של התחברות באמצעות חשבון Google, בשנת 2026 אנחנו מסירים את גרסה 1 של ה-SDK שהייתה זמינה למשחקים. החל מפברואר 2025, לא תהיה לך אפשרות לפרסם ב-Google Play משחקים שה-SDK בגרסה הזו שולב בהם לאחרונה. מומלץ להשתמש בגרסה 2 של ה-SDK למשחקים.
פריטים קיימים עם גרסה 1 ימשיכו לפעול בשנים הקרובות, אבל מומלץ לעבור לגרסה 2 החל מיוני 2025.
המדריך הזה מיועד לגרסה 1 של ה-SDK של Play Games Services. מידע על גרסת ה-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 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);
          }
        }
      });
}