Quests and Events

danger

Quests have been deprecated in Google Play Games. This functionality has been removed from the Play Games service so currently no services support Quests.

We have left this functionality in the extension in case a service implements a quest like functionality in the future.

Player Events allow you to collect cumulative data generated by your players during gameplay and store them in the game service 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.

Quests complement the Player Events by allowing you to introduce new time-bound challenges (or quests) that are based on events data. Quests allow you to re-engage players and incentivize them with some in-game reward or benefit if they succeed, without having to republish your entire game.

You should check whether Quests and Events are supported on your device and service by checking the isSupported flag:

if (GameServices.service.quests.isSupported)
{
    // Quests and Events are supported
}

Integrating Player Events

The first step is to define your events in the game service you are using.

Google Play Games have deprecated this functionality

• Google Play
  • Go to the Events page for your game in the Developer Console
  • Click on the "Add new event" button and configure the event properties
  • Publish your event definitions
  • More information here

Loading Events

Loading the Player Events available to your player is a simple call to loadEvents using the quests functionality.

GameServices.service.quests.addEventListener( PlayerEventEvent.EVENTS_LOAD_SUCCESS, eventsLoadSuccessHandler );
GameServices.service.quests.addEventListener( PlayerEventEvent.EVENTS_LOAD_ERROR,   eventsLoadErrorHandler );

GameServices.service.quests.loadEvents();

Then in your event handlers:

private function eventsLoadSuccessHandler( event:PlayerEventEvent ):void
{
    trace( "EVENTS LOAD SUCCESS" );         
    for each (var e:PlayerEvent in event.events)
    {
        message( "\t event: ["+e.eventId+"] "+ e.name );
    }
}

private function eventsLoadErrorHandler( event:PlayerEventEvent ):void
{
    trace( "EVENTS LOAD ERROR:" + event.message );
}

Updating an Event

Once you have loaded the Player Events you can increment an event when your events occur during game play:

var eventId:String = "some_event_id";

GameServices.service.quests.incrementEvent( eventId );

Integrating Quests

Similar to events, you will need to define your quests in the game service you are using.

Google Play Games have deprecated this functionality

• Google Play
  • Go to the Quests page for your game in the Developer Console
  • Click on the "Add new quest" button and configure the quest properties
  • Specify the events that represent player actions or milestones needed to complete the quest
  • Publish your quests
  • More information here

Displaying the Quests UI

You can present a native UI to show your players the available quests within your game. Through this UI your players can accept quests and start tracking events towards quests.

GameServices.service.quests.addEventListener( QuestEvent.QUESTS_UI_CLOSED, questsUIClosedHandler );
GameServices.service.quests.displayUI();

private function questsUIClosedHandler( event:QuestEvent ):void
{
    trace( "QUESTS UI CLOSED" );
}

Loading Quests

You can load the list of available quests and present them to your players as you require.

GameServices.service.quests.addEventListener( QuestEvent.QUESTS_LOAD_SUCCESS, questsLoadSuccessHandler );
GameServices.service.quests.addEventListener( QuestEvent.QUESTS_LOAD_ERROR, questsLoadErrorHandler );

GameServices.service.quests.loadQuests();

This will load an array of Quest objects and return them in the success event:

private function questsLoadSuccessHandler( event:QuestEvent ):void
{
    trace( "QUESTS LOAD SUCCESS" );
    for each (var quest:Quest in event.quests)
    {
        trace( "\t quest: ["+quest.questId+"] "+ quest.name );
    }
}

private function questsLoadErrorHandler( event:QuestEvent ):void
{
    trace( "QUESTS LOAD ERROR: "+ event.message  );
}

Quest States

A quest is in an inactive state until your player "accepts" the quest. Once a quest is accepted any events that you track will then be counted towards the progress of the quest.

To accept a quest call the accept function with the quest id of interest.

GameServices.service.quests.addEventListener( QuestEvent.QUEST_ACCEPT_SUCCESS, questsAcceptSuccessHandler );
GameServices.service.quests.addEventListener( QuestEvent.QUEST_ACCEPT_ERROR, questsAcceptErrorHandler );

GameServices.service.quests.accept( questId );

private function questsAcceptSuccessHandler( event:QuestEvent ):void
{
    trace( "ACCEPT SUCCESS: " );
}

private function questsAcceptErrorHandler( event:QuestEvent ):void
{
    trace( "ACCEPT ERROR:" + event.message );
}

Once a quest has been accepted, any events that occur that contribute to a quest will automatically be added towards the players quest progress and when the conditions are met the quest will be marked as completed and a small service UI element will be displayed to the user.

You should make sure you call the listenForCompletion function at some point before you increment any events and also add an event listener for the QuestEvent.QUEST_COMPLETED. This makes sure your application has registered for quest completion events.

GameServices.service.quests.addEventListener( QuestEvent.QUEST_COMPLETED, questsCompletedHandler );
GameServices.service.quests.addEventListener( QuestEvent.QUEST_CLAIM_SUCCESS, questsClaimSuccessHandler );
GameServices.service.quests.addEventListener( QuestEvent.QUEST_CLAIM_ERROR, questsClaimErrorHandler );

// Calling this enables the QUEST_COMPLETED event when your player completes a quest
GameServices.service.quests.listenForCompletion();

Once a quest is completed your user can "claim" the reward. You can do this in your interface by calling the GameServices.service.quests.claim() function when you require or the user can claim a reward through the native UI. You should account for both scenarios by making sure you always have an event listener for the QuestEvent.QUEST_CLAIM_SUCCESS event, and reward your player when this event occurs.

private function questsCompletedHandler( event:QuestEvent ):void
{
    var quest:Quest = event.quests[0];
    trace( "QUEST COMPLETED: " + quest.questId + "::"+ quest.currentMilestone.milestoneId );
    
    // Call this when your user claims the reward
    GameServices.service.quests.claim( quest.questId, quest.currentMilestone.milestoneId );
}

private function questsClaimSuccessHandler( event:QuestEvent ):void
{
    // Use the rewardData as required to give your player the quest reward
    trace( "CLAIM SUCCESS: " + event.quests[0].currentMilestone.rewardData.toString() );
}

private function questsClaimErrorHandler( event:QuestEvent ):void
{
    trace( "CLAIM ERROR:" + event.message );
}