Integrate rewards with supported events

Last updated on October 29, 2024

Overview

The AccelByte Gaming Services (AGS) reward service allows you to grant virtual items or other entitlements as a form of recognition for achieving a certain challenge or objective within a game. This works by integrating with other services in AGS, such as Identity and Access Management (IAM), statistics, and achievements, that will be used to define the goals that players must achieve to earn rewards.

In this guide, you will learn how to integrate rewards with the supported events from other services in AGS.

Goals

• Provide an understanding and overview about reward configurations.
• Provide an understanding on how to utilize available events for granting rewards to players.

Prerequisites

• Access to the AGS Admin Portal.
• Access to AccelByte Platform API documentation.
• Access to the AccelByte Achievement and Statistic API to configure the required information.

Supported events

The AGS reward service supports granting rewards to the players triggered by some events published by other services such as IAM, statistics, and achievements.

Understanding the event name and usage below will make it easier for you to choose the event you want to integrate with for your reward.

Event Topic	Event Name	Usage
Statistic	statItemCreated	This is suitable if you want players to receive the reward upon creating a particular statistical value.
Statistic	statItemUpdated	This is suitable if you want players to receive the reward upon reaching a particular statistical value.
Achievement	userAchievementUnlocked	This is suitable if you want players to receive the reward upon earning a particular achievement.
Achievement	achievementRewardClaimed	This is suitable if you want players to receive the reward upon successfully claiming a global achievement.
User Account	userAccountCreated	This is suitable if you want players to receive the reward upon creating an account in your platform using the publisher namespace.
User Account	gameUserAccountCreated	This is suitable if you want players to receive the reward upon creating an account in your platform using the game namespace.
User Account	userAccountVerified	This is suitable if you want players to receive the reward when their account is verified in your platform using the game namespace.
User Account	userAccountLinked	This is suitable if you want players to receive the reward upon linking an account in your platform with a third-party account using the game namespace.
User Account	userAccountUpgraded	This is suitable if you want players to receive the reward upon upgrading their account from a headless account to full account using the game namespace.
User Account	thirdPartyAccountCreated	This is suitable if you want players to receive the reward upon creating an account on your platform from a third-party platform. Both userAccountCreated and thirdPartyAccountCreated are contained within the User Account event topic.

Create a new reward configuration

1. In the AGS Admin Portal, go to Engagement > Rewards.

   

2. On the Rewards page, click the Add Configuration button.

   

3. On the Add Rewards form, fill in the required information:

   

   • You will be required to fill in the Reward Code as a unique identifier for your reward with the allowed format (e.g., road-to-champion) and fill in the Description to provide extra information about the reward you created.

   • Select the trigger for the reward from the Event Topic dropdown. You can choose either Statistic, Achievement, or User Account.

   • Advanced Settings:

     • There is an optional UserID Expression field that you can use to specify the condition that indicates the target User ID in the event payload using the JSON path format. If left blank, the default value is $.[0].userId. Format:

       $.eventPayloadObject.userId

     • Another optional field is Namespace Expression. You can use this to specify the condition that indicates the target namespace in the event payload using the JSON path format. If left blank, the default value is $.[0].namespace. Format:

       $.eventPayloadObject.namespace

   • You are also required to fill in the maximum number of times the reward can be earned in your game namespace in the Max Awarded field, as well as the maximum number of times the reward can be earned by a single player in the Max Awarded Per User field.

4. Click Add. The new reward is added to the rewards list.

Add a reward condition

1. On the Rewards page of the Admin Portal, find the reward you want to update and click on its View option.

   

2. On the reward details page, click Add Reward Condition.

   

3. On the Add Reward Condition form, fill in the required information:

   

   • Fill in the Event Name field with the event you want to use to trigger the reward. For more details, see the list of supported events.

   • Enter a name for the specific event condition that triggers the reward in the Condition Name field.

   • Enter the specific condition that triggers the reward in JSON path format in the Condition field. The format for each event topic is given below.

     • Event Topic: Statistic: This is to grant a reward to the players for reaching a certain statistic value.

       $.[?(@.statCode == "input-your-stat-code" && @.latestValue == x)]

       • Input the statCode for the statistic configuration that you are using. This code can be found on the Statistics page in the Admin Portal.

       • Input the statistic value at which the reward will be granted if it matches with the player's latestValue.

       • In this example, the player will receive the reward once they reach 150 points in the rewardpoints statistic:

         $.[?(@.statCode == "rewardpoints " && @.latestValue == 150)]

     • Event Topic: Achievement: This is to grant a reward to the players upon unlocking a certain achievement.

       $.[?(@.status == 2 && @.achievementCode == "input-your-achievement code")]

       • Define the Status. This determines when the player will receive the reward.

         • Input 1 if the player will receive the reward when the achievement is in progress.
         • Input 2 if the reward will be granted when the player receives the achievement.

       • Input the achievementCode for the achievement configuration that you are using. This code can be found on the Achievements page in the Admin Portal.

       • In this example, the player will receive the reward when they unlock the killingmachine achievement:

         $.[?(@.status == 2 && @.achievementCode == "killingmachine ")]

     • Event Topic: User Account, Third-Party Login This is to grant a reward to the player after creating an account on your platform, or creating an account on your platform from a third-party platform such as Steam, Xbox, PlayStation, etc.

       $.[?(@.userId != null && @.emailAddress != null)]
       • Input !=null in the userId field. This confirms that the user ID is not null.
       • Input !=null in the emailAddress field. This confirms that the email address is not null. For third-party logins, you can remove this field and only use userId.

   • Fill in the REWARD ITEMS fields with the required information:

     

     • Select the Item you want to grant as a reward. Please make sure that the item is already configured in your store (see the guide on stores for more information).
     • Input the quantity of the item you want to include in the reward in the Qty field.
     • If the reward item is a subscription, input how many days the subscription should last in the Duration field. If the item you have selected is any other type, you can leave this field blank.
     • To add more items to the reward, click Add More Items.

4. When you're done adding items, click Save. The new reward condition is added to the list.