Adding Events and Quests to Your Android Game

This guide shows you how to use the events and quests APIs in an Android application.

Before you begin

If you haven't already done so, you might find it helpful to review the quests and events game concepts.

Before you start to code using the events and quests APIs:

Once the player is signed in and the GoogleApiClient is connected, your game can start using the events and quests APIs.

Using events in your game

The following section shows how your game might implement key operations using the events API from the com.google.android.gms.games.event package.

Submitting an event

You can add code in your game to notify Google Play games services whenever an event of interest to your game occurs. To send an event update, call increment(). In the method call, pass in the GoogleApiClient, a string with the eventId value, and an integer incrementAmount that is equal to or greater than 0.

  • The eventId is generated by Google Play games services when you first define the event in the Google Play Developer Console and is used to uniquely identify this event in your game.
  • For events which are used to determine quest completion, you can use the incrementAmount input to specify the player's quantitative progress towards completing the quest. For example, if the event your game wants to track is 'Defeat 500 bug-eyed monsters', the incrementAmount can be the number of monsters that the player killed in a single battle.

The following snippet shows how to submit an event with an increment amount of 1:

public void submitEvent(String eventId) {
    // eventId is taken from the developer console
    String myEventId = eventId;

    // increment the event counter
    Games.Events.increment(mGoogleApiClient, myEventId, 1);
}

Retrieving events

You can retrieve all events data stored in Google's servers for your game, by calling load(). In the method call, pass in the GoogleApiClient, and a boolean value to indicate if Google 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 Developer Console, call loadByIds() and pass in an array of event IDs in the input parameters.

The following snippet shows how you can query Google Play games services for the list of all events for your game:

// EventCallback is a subclass of ResultCallback; use this to handle the
// query results
EventCallback ec = new EventCallback();

// Load all events tracked for your game
com.google.android.gms.common.api.PendingResult<Events.LoadEventsResult>
        pr = Games.Events.load(mGoogleApiClient, true);
pr.setResultCallback(ec);

If the call is successful, the system triggers the ResultCallback object in your app. You should handle the query results in the onResult() method:

class EventCallback implements ResultCallback {
    // Handle the results from the events load call
    public void onResult(com.google.android.gms.common.api.Result result) {
        Events.LoadEventsResult r = (Events.LoadEventsResult)result;
        com.google.android.gms.games.event.EventBuffer eb = r.getEvents();

        for (int i=0; i < eb.getCount(); i++) {
            // do something with the events retrieved
        }
        eb.close();
    }
}

Using quests in your game

The following section shows how your game might implement key operations using the quests API from the com.google.android.gms.games.quest package.

Displaying quests

To integrate quests into your game, you should provide players with a user interface (UI) to view the list of available quests. To simplify your development, the quests API provides a default quest list UI that you can use out-of-the-box. The quest list UI allows players to view details about quests, accept an open quest, and claim rewards for quests they completed.

To bring up the default quest list UI:

  1. Call getQuestsIntent() to get an Intent for launching the default quest list UI. In the method call, pass in an integer array with selectors to filter the quests that you want the UI to display. For the full list of selectors you can specify, see the getQuestsIntent() API reference. The system logically ORs the specified selectors to determine which quests to display in the list UI.

  2. Call startActivityForResult() and pass in that Intent. If the call is successful, the game displays the list of quests, filtered by the selectors you specified.

    The following snippet shows how to bring up a list UI that displays all quests that you defined in Google Play Developer Console for your game:

    public void showQuests() {
        Intent questsIntent = Games.Quests.getQuestsIntent(mGoogleApiClient,
                Quests.SELECT_ALL_QUESTS);
        startActivityForResult(questsIntent, 0);
    }
    

Retrieving quests

Your app can retrieve quest data for the currently signed-in player, by calling load(). If you want to filter the results based on the quest state, set the questSelector input parameter (for example, set SELECT_OPEN to retrieve all quests that the player can accept).

Handling quest completion

Once players have accepted a quest, make sure to capture their progress in your game by sending event updates as they perform game actions or achieve milestones towards completing the quest. When Google Play games services detects that the player has achieved all criteria required to complete a quest, the system triggers the onQuestCompleted() callback in your app.

To detect quest completion:

  1. Register a QuestUpdateListener by calling registerQuestUpdateListener() as soon as the player is signed-in to your game.

    @Override
    public void onConnected(Bundle connectionHint) {
        // Sign-in worked!
        // Hide the SignIn button and show a SignOut button, etc.
    
        // Start the quest listener.
        Games.Quests.registerQuestUpdateListener(mGoogleApiClient, this);
    }
    
  2. Override the onQuestCompleted() in the listener to handle the quest completion. Your game should call claim() to inform Google Play games services the player is claiming the reward for completing this quest. Your game should also retrieve the RewardData for the completed quest and use this data to provision an appropriate in-game reward to the player.

    The following code snippet shows how you might override the onQuestCompleted() callback:

    @Override
    public void onQuestCompleted(Quest quest) {
    
        // Claim the quest reward.
        Games.Quests.claim(mGoogleApiClient, quest.getQuestId(),
                quest.getCurrentMilestone().getMilestoneId());
    
        // Process the RewardData to provision a specific reward.
        String reward = new
              String(quest.getCurrentMilestone().getCompletionRewardData(),
              Charset.forName("UTF-8"));
    
        // Provision the reward; this is specific to your game. Your game
        // should also let the player know the quest was completed and
        // the reward was claimed; for example, by displaying a toast.
        // ...
    }
    

Enviar comentarios sobre…

Play Games Services for Android
Play Games Services for Android