High replay value is one of the defining characteristics of a great game. Even games with very simple plots can become successful on Google Play so long as they have a high replay value. If you are an avid gamer, you probably already know what replay value is. If you don't, you can think of it as the likelihood that a user is going to play a game again even after achieving its primary objective.
By using the events and quests APIs, which are a subset of the Google Play games services APIs, you can dramatically increase the replay values of your games, not to mention make them more challenging and fun. In this tutorial, I'll show you how to make the most of both the APIs.
Before you proceed, I suggest you read my introductory tutorial about Google Play games services, which shows you how to use the services in an Android Studio project.
1. Understanding Events and Quests
Anything that happens in a game can be considered an event. By logging enough events using the events API, you can closely analyze the behaviors of your users. You can infer details such as how far the users are able to go in your game, how many enemies they kill, and how many in-game resources they collect. With such details at hand, you'll be able to easily refine your game to make it more enjoyable.
The events API, however, is rarely used alone. Most developers use it along with the quests API to create quests. A quest, as its name suggests, is a secondary objective the users can achieve to gain some reward. For example, if you are creating a game where the user is trying to save a princess, you can add a quest to it where the user must find at least 100 rings for her.
If you haven't guessed it already, events are used to define the completion criteria of quests. In the above example, finding a ring would be an event that must occur 100 times for the quest to be marked as complete.
Although quests share some similarities with achievements, there are a few important differences between the two:
- You don't have to write any code to add a new quest to your game, provided the events it depends on are already a part of the game.
- Quests are time-bound. For example, you can schedule a new quest to start a week before Christmas and challenge users to complete it before Christmas Eve.
- A user can complete a quest only after choosing to participate in it.
With lots of interesting quests, some of which are scheduled to repeat every week or month, you can effortlessly get users to play your game multiple times.
2. Creating an Event
Log in to the Play developer console and open the Game Services screen by clicking on the gamepad icon.
Next, pick the game you want to add events to and open the Events section.
Press the Add event button to start creating an event. In the form that pops up, give a meaningful name to the event. Continuing with the example of the previous step, I'll call the event Collect Ring.
Once you press the Save button, you'll be able to see the ID of the event. To be able to use the event in your Android Studio project, you must add the ID as a new <string> tag in the games-ids.xml file.
<string name="event_collect_ring">ABCDEFabcdef123</string>
3. Creating a Quest
Creating a quest is slightly more involved. Start by going to the Quests section and pressing the Add quest button. Give the quest an attractive name and an easy-to-understand description. Both are very important because they will be read by the users. A quest that doesn't look interesting is unlikely to see many participants.
Next, scroll down to the Completion criteria section. In the Find an event field, type in the ID of the event you created earlier. In the next input field, you must specify how many times the event must occur for the quest to be completed.
In the Schedule section, specify the Start date and time of the quest. To be able to start working with the quest immediately, you can choose today's date.
You must also specify the duration of the quest by typing in a value in the Number of days field. Optionally, you can choose to notify quest participants when they are almost out of time.
A quest must have a reward—why else would a user choose to participate in it? You can specify what the reward is by uploading a reward file, which can be a file of any format. Most developers choose to use the JSON format. Here's a sample reward file:
{
points: 3000,
max_lives: 15
}It is worth noting that the contents of the reward file are not important to the Play games services APIs. It is your responsibility to parse and use them in your game.
In the Reward data section, press the Browse button and upload the reward file you created.
Finally, press Save to generate an ID for the quest. Optionally, you can copy the ID and add it to your Android Studio project's games-ids.xml file as another <string> tag.
<string name="quest_please_the_princess">BCDEABCD123</string>
4. Displaying the Quests UI
The quests API offers an activity that can display all the quests that are available in your game. The activity also allows users to join quests.
To open the quests activity, you must create an intent for it using the getQuestsIntent() method of the Games.Quests class. As its arguments, it expects a GoogleApiClient object and an int array specifying the types of quests you want to display. Here are some popular values for the types of quests:
Quests.SELECT_OPEN, a quest a user can participate in right away.Quests.SELECT_UPCOMING, a quest that is yet to start.Quests.SELECT_COMPLETED, a quest the user has completed already.Quests.SELECT_ACCEPTED, a quest the user is currently participating in.
After creating the Intent object, you can pass it to the startActivityForResult() method to display the quests activity.
The following code shows you how to open the quests activity and display four types of quests:
Intent intent = Games.Quests.getQuestsIntent(apiClient,
new int[]{
Quests.SELECT_OPEN,
Quests.SELECT_UPCOMING,
Quests.SELECT_ACCEPTED,
Quests.SELECT_COMPLETED
});
startActivityForResult(intent, 0);Here's what the quests activity looks like:
The user becomes a participant of the quest by pressing the Accept button. During a quest, the users can return to the quests UI to see how much of the quest is complete.
5. Using the Events API
The events API allows you to easily manage events in your game. To change the value of an event, you can use the increment() method of the Games.Events class. As its arguments, it expects a GoogleApiClient object, the name of the event, and a number specifying how much the value of the event should be increased.
The following code increments the value of the event_collect_ring event by 1:
Games.Events.increment(apiClient,
getString(R.string.event_collect_ring), 1);To fetch the current values of events, you must use the load() method. Because the value is fetched from Google's servers asynchronously, the return value of the method is a PendingResult object. By adding a ResultCallback object to it, you can be notified when the result is available.
Inside the onResult() method of the ResultCallback interface, you must call the getEvents() method of the Events.LoadEventsResult object, which returns an EventBuffer. Once you find the desired Event in the buffer, you can call its getValue() method to get its current value.
The following code shows you how to fetch the value of the event_collect_ring event:
PendingResult<Events.LoadEventsResult> results =
Games.Events.load(apiClient, true);
results.setResultCallback(
new ResultCallback<Events.LoadEventsResult>() {
@Override
public void onResult(@NonNull Events.LoadEventsResult
loadEventsResult) {
// Fetch all events of the game
EventBuffer events = loadEventsResult.getEvents();
// Loop through all the events
for(int i = 0; i < events.getCount(); i++) {
Event currentEvent = events.get(i);
// Check if current event is the desired event
// and print its value
if(currentEvent.getEventId().equals(getString(
R.string.event_collect_ring)))
Log.d(TAG, "You have now collected " +
currentEvent.getValue() + " rings");
}
}
}
);6. Detecting Quest Completion
When a user completes a quest on time, your game must be able to reward the user using the rewards file you uploaded in the Play developer console. To detect quest completion, you must create a QuestUpdateListener object and register it with the quests API using the registerQuestUpdateListener() method of the Games.Quests class.
Inside the onQuestCompleted() method of the QuestUpdateListener interface, you must call the claim() method to claim the reward of the quest. You must pass a GoogleApiClient object, the quest ID, and the current milestone's ID to the method.
After the claim, you can fetch the reward file as a byte array by calling the getCompletionRewardData() method. Because our reward data is just a JSON file, you can pass the byte array to the constructor of the String class to convert it into a string.
Games.Quests.registerQuestUpdateListener(apiClient,
new QuestUpdateListener() {
@Override
public void onQuestCompleted(Quest quest) {
Games.Quests.claim(apiClient, quest.getQuestId(),
quest.getCurrentMilestone()
.getMilestoneId());
byte[] rewardData = quest.getCurrentMilestone()
.getCompletionRewardData();
String reward = new String(rewardData);
}
}
);At this point, you can convert the string into a JSONObject instance, and read the values of the keys inside it. The following code shows you how to fetch the values of two keys called points and max_lives:
try {
JSONObject rewardObject = new JSONObject(reward);
int points = rewardObject.getInt("points");
int maxLives = rewardObject.getInt("max_lives");
Log.d(TAG, "You have now gained "
+ points + " points and "
+ maxLives + " lives");
} catch(Exception e) {
Log.e(TAG, "Couldn't parse JSON");
}Note that the quests activity automatically updates itself when a quest has been completed. Here's what a completed quest looks like:
Conclusion
In this tutorial, you learned how to use the quests and events APIs to persuade users to play your game again and again. Note, however, that because these APIs have rate limits, you must try to avoid using them too often in your app. You can refer to the Play games services quality checklist page to learn about more restrictions and best practices.
To learn more about quests and events, you can refer to their official documentation. And in the meantime, check out some of our other posts on Firebase and Google Play Services!
![]()
Get Started With Google Play Games Services
![]()
Google Play Services: Awareness API
![]()
Get Started With Firebase for Android
![]()
What's New in Firebase? Updates From the Firebase Dev Summit
