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

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

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

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

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

• מגדירים את האירועים למשחק ב-Google Play Console.

• פועלים לפי ההמלצות שבצ'קליסט לכניסה.

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

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

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

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

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

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

• אפשר להשתמש בקלט incrementAmount כדי לציין את ההתקדמות הכמותית של השחקן לקראת השלמת יעד ספציפי במשחק. לדוגמה, אם האירוע שרוצים לעקוב אחריו במשחק הוא 'הבסת 500 מפלצות עם עיניים גדולות', הערך של incrementAmount יכול להיות מספר המפלצות שהשחקן הרג בקרב אחד.

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

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

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

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

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

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

public void loadEvents() {
  PlayGames.getEventsClient(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);
          }
        }
      });
}