Quests And Events

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

The Google Play Games events service allows you to collect cumulative data generated by your players during the gameplay and store them in Google's servers for the 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.

Important: The Google Play Games quests service will be deprecated as of March 31st 2018. Do not use the Google Play Games quests API in new apps. See the deprecation announcement blog post for more details.

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.

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 Adds new event button and configure the event properties.
    3. Publish your event definitions by the following 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 GooglePlayEvents.instance.SumbitEvent method whenever your game detects that an event that it cares about has been triggered.

Note: On mobile clients, Play Games services update events in batches, so you will see cumulative, rather than fine-grained, changes to your events.

  1. 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's 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.
  2. 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 Games 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 Games 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.
  3. Update the player's quest progress.
    • Update Play Games 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 Games services.

A Play Games 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.


  • "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.


Quest basics

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

A Play Games 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.


  • "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.


  • "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 Games 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 Games 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. Inquests 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.

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.

As Play Games services do 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.
  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.


The following section shows how your game might implement key operations using the events API

Submitting an event

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 SumbitEvent . In the method call, pass  a string with the eventId  value, and an integer incrementAmount that  equals to or greater than 1.

  • The eventId is generated by Play Games services when you first define the event in the Google Play Developer Console and is used to identify this event in your game uniquely.
  • 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 which your game wants to track is 'Defeat 500 bug-eyed monsters', the incrementAmount can be a 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:



Retrieving events

You can retrieve all events data stored in Google's servers for your game by calling LoadEvents in GooglePlayEvents class. 

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

GooglePlayEvents.Instance.OnEventsLoaded += OnEventsLoaded;

private void OnEventsLoaded (GooglePlayResult result) {
	Debug.Log ("Total Events: " + GooglePlayEvents.Instance.Events.Count);
	foreach(GP_Event ev in GooglePlayEvents.Instance.Events) {


Events are represented in GP_Event class.

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 guest 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 the quests they completed.

To bring up the default quest list UI:



Retrieving quests

Your app can retrieve quest data for the currently signed-in player by calling LoadQuests in GooglePlayQuests class. 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).

GooglePlayQuests.Instance.OnQuestsLoaded += OnQuestsLoaded;

//load all quests
//load only opened quests
GooglePlayQuests.Instance.LoadQuests(GP_QuestSortOrder.SORT_ORDER_ENDING_SOON_FIRST, GP_QuestsSelect.SELECT_OPEN);

private void OnQuestsLoaded (GooglePlayResult result) {
	Debug.Log ("Total Quests: " + GooglePlayQuests.Instance.GetQuests().Count);
	foreach(GP_Quest quest in GooglePlayQuests.Instance.GetQuests()) {


Quests are represented in GP_Quest class.

Available Selection options

Handling quest completion

Once players have accepted a quest, make sure to capture their progress in your game. When Play Games services detects that the player has achieved all criteria required to complete a quest, the system triggers the OnQuestsCompleted callback in your app. Result object is represented by GP_QuestResult class.

To detect quest completion:

GooglePlayQuests.Instance.OnQuestsCompleted += OnQuestsCompleted;

private void OnQuestsCompleted (GP_QuestResult result) {
	Debug.Log ("Quests Completed, Reward: " + result.reward);


Note: When working with result.reward string, make sure that encoding of your json file is the same as in your scripts.

You also can get a notification when the player is accepted a query.

To detect quest accepted action:

GooglePlayQuests.Instance.OnQuestsAccepted += OnQuestsAccepted;

private void OnQuestsAccepted (GP_QuestResult result) {
	AndroidNative.showMessage ("On Quests Accepted", "Quests Accepted, ID: " + result.questId);


The full API use example can be found under the QuestsAndEventsExample example scene.