| **Note:** This guide is for the Play Games Services v2 SDK. For information on the previous version of this SDK, see the [Play Games Services v1
| documentation](https://developer.android.com/games/pgs/v1/android/events).

This guide shows you how to collect player gameplay data for game analytics
using the events APIs provided by Google Play Games Services. The APIs can be found in the
[`com.google.android.gms.games.event`](https://developers.google.com/android/reference/com/google/android/gms/games/event/package-summary)
and [`com.google.android.gms.games`](https://developers.google.com/android/reference/com/google/android/gms/games/package-summary)
packages.

## Before you begin

If you haven't already done so, you might find it helpful to review the [events
game concepts](https://developer.android.com/games/pgs/events).

Before you start to code using the events APIs:

- Define the events for your game in the
  [Google Play Console](https://play.google.com/apps/publish/).

- Follow the [sign-in checklist recommendations](https://developer.android.com/games/pgs/quality#sign-in).

## Get the events client

To start using the events APIs, your game must first obtain an
[`EventsClient`](https://developers.google.com/android/reference/com/google/android/gms/games/EventsClient)
object. You can do this by calling the [`PlayGames.getEventsClient()`](https://developers.google.com/android/reference/com/google/android/gms/games/PlayGames#public-static-eventsclient-geteventsclient-activity-activity)
method and passing in the activity.
| **Note:** The [`EventsClient`](https://developers.google.com/android/reference/com/google/android/gms/games/EventsClient) class makes use of the Google Play services [`Task`](https://developers.google.com/android/reference/com/google/android/gms/tasks/Task) class to return results asynchronously. To learn more about using tasks to manage threaded work, see the [Tasks API developer
| guide](https://developers.google.com/android/guides/tasks).

## Submit events

You can add code in your game to notify Play Games Services whenever an event of
interest to your game occurs.

To send an event update, call
[`EventsClient.increment()`](https://developers.google.com/android/reference/com/google/android/gms/games/EventsClient#increment)
with the `eventId` value and an integer `incrementAmount` that is equal to or
greater than 0.

- The `eventId` is generated by Play Games Services when you first define the
  event in the Google Play Console and is used to uniquely identify this
  event in your game.

- You can use the `incrementAmount` input to specify the player's quantitative
  progress towards completing some game-specific goal. For example, if the
  event your game wants to track is *'Defeat 500 bug-eyed monsters'* , the
  `incrementAmount` value can be the number of monsters that the player killed
  in a single battle.

Here's an example of how to submit an event with an increment amount of 1:  

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

## Retrieve events

You can retrieve all events data stored in Google's servers for your game, by
calling
[`EventsClient.load()`](https://developers.google.com/android/reference/com/google/android/gms/games/EventsClient#load(boolean)).
In the method call, pass in a boolean value to indicate if Play Games Services
should clear the locally cached data on the user's device.

To retrieve data for specific events that you defined in the
Google Play Console, call
[`EventsClient.loadByIds()`](https://developers.google.com/android/reference/com/google/android/gms/games/EventsClient#loadByIds)
and pass in an array of event IDs in the input parameters.

The following snippet shows how you can query Play Games Services for the list of
all events for your game:  

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