Hide
Google Play Game Services

Events and Quests

One way to motivate players to return to your game is by introducing new challenges for players to complete and incentivizing them with some in-game reward or benefit if they succeed.

The Google Play Games events service allows you to collect cumulative data generated by your players during gameplay and store them in Google's servers for game analytics. You can flexibly define what player data your game should collect; this might include metrics such as how often:

  • Players use a particular item
  • Players reach a certain level
  • Players perform some specific game action

You can use the events data as feedback on how to improve your game. For example, you can adjust the difficulty level of certain levels in your game that players are finding too hard to complete.

The Google Play Games quests service complements the events service by allowing you to add new time-bound challenges that are based on events data, along with associated in-game rewards that players can claim when they complete a quest, without having to republish your entire game in the Google Play Developer Console.

The Google Play Games events and quests services are supported on these platforms:

To learn how to implement events and quests for these platforms, see Client implementations.

Integrating events and quests in your game

The following workflow describes how you can apply events and quests in your game:

  1. Define events. To define new events to capture in your game:
    1. Go to the Events page for your game in the Google Play Developer Console.
    2. Click on the Add new event button and configure the event properties.
    3. Publish your event definitions by following the steps described in Publishing your game changes.
  2. Implement event capturing in your game using the events APIs. For example, in your Android code, call the events increment method whenever your game detects that an event that it cares about has been triggered.

  3. View events data. Go to the Events page for your game in the Google Play Developer Console to view statistics for the captured events.

  4. Define quests. To define new quests and rewards for your game:
    1. Go to the Quests page for your game in the Google Play Developer Console.
    2. Click on the Add a new quest button and configure the quest properties.
    3. In the quest definition, specify the events that represent player actions or milestones needed to complete the quest.
    4. You can publish individual quests from the Google Play Developer Console. You do not need to republish your game, as long as the events required by the new quest are already published.
  5. Present new quests to players.
    • If your game is installed on a player's device, your new quests are automatically displayed when the player opens the Google Play Game app.
    • You can also present new quests to players from within your game through the default Quest list user interface (UI) provided by the Play Game services SDK or through your own custom UI. If you are implementing your own UI, make sure to provide players with a description of how to complete each quest.
  6. Update the player's quest progress.
    • Update Play Game services with the players progress by using the events and quests APIs.
    • Reward players if they complete the quest. If players fail to complete the quest within the given time period, the Quest list UI shows the quest as Expired.

Event basics

The events APIs provide you with a way to define and collect interesting gameplay metrics and upload these metrics to Play Game services.

A Play Game services event contains these key properties:

Property Description
ID A unique string generated by the Google Play Developer Console for this event. Use this unique ID to refer to the event in your game clients.
Name A short name of the event. The name can be up to 100 characters. This value is used by the Google Play Developer Console and can be displayed in your game.

Examples:

  • "Zombies Killed"
  • "Red Gems Collected"
Description A longer description of the event (for example, "Number of times a player has killed a zombie" or "The total number of red gems the player has eliminated and matched."). The description can be up to 500 characters. This value is used by the Google Play Developer Console and can be displayed in your game.
Icon A square icon that will be associated with your event.

Creating an event

To create a new event for your game, follow these steps:

  1. Add your game in the Google Play Developer Console, if you have not already done so.
  2. In the Google Play Developer Console, click on the Game services icon on the left and select the entry for your game.
  3. Select the Events tab on the left, and click on the Add event button.
  4. Fill in the details for the event you want to create.
  5. Click Save. If there are no errors, your event is placed in the "Ready to publish" state. You can now proceed to publish your game changes.

Editing an event

To edit an event that you've created:

  1. In the Google Play Developer Console, open the Events tab and select the entry for the event you want to edit. You should see the same form you used when creating the event.
  2. Make your edit changes.
  3. When you've finished editing the event, click the Save button.
  4. Test your game to verify the modified event. If it is working correctly, republish your game changes.

Deleting an event

You can delete events that are in draft state or that have been published, as long as the event is not in use by a quest. To delete an event in the Google Play Developer Console, click the button labeled Delete at the bottom of the form for that event.

Resetting event data

You can reset player progress data for testers of your events.

  • To reset draft events in the Google Play Developer Console, click the button labeled Reset event progress at the bottom of the form for that event.
  • To reset event data programmatically, call the Management API Events methods.

Quest basics

The quests APIs lets you create in-game challenges for players to attempt to complete within a predefined time period.

A Play Game services quest contains these key properties:

Property Description
ID A unique string that the Google Play Developer Console generates for you. Use this ID in your game client to implement accepting a specific quest and claiming a quest's rewards. You don't need to hard code this value in your game; you can get this value from the *Quests list* UI.
Name The short name of the quest. This can be up to 100 characters.

To make your quest names meaningful and engaging to players, follow these recommendations:

  • Use present tense.
  • Use a call to action to engage the user. The name should start with an imperative verb.
  • Address your players directly, but only use "you" if needed.

Examples:

  • "Collect 50 coins"
  • "Eat 100 pancakes"

Description A longer description of the quest. Your quest description should let players know what they should do to complete the quest.

The description can be up to 500 characters. The first 150 characters will be visible to players in cards such as those shown in the Google Play Games app.The Play Games *Quest list* UI includes a featured image for the game, so mentioning the game name isn't necessary in the description.

Examples:

  • "Zombies are taking over the town this weekend. Help take it back by killing all the zombies!"
  • "In honor of May Day, we’ve decided to paint the town red! Get as many red gems as you can on May 1st."
Icon A square icon that will be associated with your event.
Banner A rectangular image that will be used to promote your quest.
Completion Criteria How Play Games determines if the quest is completed. This consists of an event (which you can enter by name), and the number of times the event must occur to complete this criteria (for example, “Kill Zombie” 100 times).
Schedule Specifies when players will be able to accept and participate in quests. When you enter the dates and time values, Play Game services uses your local time zone but stores the values as UTC. Players will see these values appear in their local time zone in the Google Play Game app and in the default Quest list UI.
Reward Data Specifies a reward for your players upon completing this quest. When storing data in this property, you can use your own game-specific data format. To learn more, see Specifying reward data.
Notifications Boolean value indicating whether to send a notification to participating players when the quest is about to end. In quests spanning multiple days, this occurs at the start of the last day of the quest. For shorter quests, this occurs when 80% of the alloted time on the quest has passed.

Creating a quest

To create a new quest for your game, follow these steps:

  1. Add your game in the Google Play Developer Console, if you have not already done so.
  2. In the Google Play Developer Console, click on the Game services icon on the left and select the entry for your game.
  3. Select the Quests tab on the left, and click on the Add quest button. (You must create an event first, if you have not already done so.)
  4. Fill in the details for the quest you want to create.
  5. Click Save. If there are no errors, the Google Play Developer Console displays a Publish Quest button. However, before you proceed to publish your quest, make sure to test your game to verify the new quest.

Editing a quest

To edit a quest that you've created, follow these steps

  1. In the Google Play Developer Console, open the Quests tab and select the entry for the quest you want to edit. You should see the same form you used when creating the quest.
  2. Make your changes.
  3. When you've finished editing the event, click the Save button.
  4. Before publishing your changes, test your game to verify the modified quest.

Deleting a quest

You can delete quests that are in draft state. To delete a quest in the Google Play Developer Console, click the button labeled Delete quest at the bottom of the form for that quest.

Resetting quest data

You can reset player progress data for quests. To reset draft and published quests programmatically, call the Management API Quests methods to reset the quest data in your game.

Specifying reward data

Each quest that you define contains a reward data value that is in a customized game-specific format. In your game client, you can use the reward data value to determine what corresponding game items or benefits to grant to players who successfully completed your quest.

Because Play Game services does not include any special security for reward data, you are strongly discouraged from specifying rewards of any monetary value in your quests.

The following example shows how you can specify the reward data value by using a JSON string that lists the in-game items that a player receives upon completing the quest. You are free to use any data format in your game implementation, as long as your game is able to parse and interpret the rewards data value.

{
    "bonusGems": 2134,
    "extraSeconds": 12
}

You can also use the contents in the reward data value to customize gameplay when the player accepts the quest. For example, you can use the rewards data to store a link pointing to a short animation or video that your game should display when the player accepts your quest.

Testing quests

To test quests before you publish them:

  1. In the Google Play Developer Console, create the quest and set its schedule date to overlap with the current day. Don't publish the quest yet.
  2. Have users with testing access to your game try out the quest. To enable users for testing, follow the steps described in Testing and Publishing Game Changes. Quest progress does not update until the quest has been accepted. Also, the quest cannot be accepted and is not activated in the quest picker until it is available as specified in the Google Play Developer Console. To see examples of how to test checking reward data, see the management tools sample app.
  3. When you are satisfied that your quest is working correctly, change its schedule date to when you want players to be able to participate in your quest.
  4. Publish your quest from the Google Play Developer Console.

Client implementations