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

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

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

אם עדיין לא עשיתם זאת, כדאי לעיין בקונספטים של משחקי אירועים.

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

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

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

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

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

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

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

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

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

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

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

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

קטע הקוד הבא מראה איך להריץ שאילתות על שירותי המשחקים של Google Play כדי להציג את הרשימה של כל האירועים במשחק שלכם:

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);
          }
        }
      });
}