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

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

זהירות: המדריך הזה מיועד לשימוש ב-SDK של Play Games Services v1. מידע על גרסת ה-SDK האחרונה זמין במסמכי העזרה של גרסה 2.

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

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

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

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

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

אחזור הלקוח של האירועים

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

הערה: הכיתה EventsClient משתמשת בכיתה Task של שירותי Google Play כדי להחזיר תוצאות באופן אסינכרוני. מידע נוסף על השימוש במשימות לניהול עבודה בשרשור זמין במדריך למפתחים של Tasks API.

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

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

כדי לאחזר נתונים של אירועים ספציפיים שהגדרתם ב-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);
          }
        }
      });
}