Access
Connect cross-platform accounts & identity management
Rewards are an effective way to increase player retention and brand loyalty by granting players special items or other entitlements in recognition of their achievements. Players who are rewarded for their progress will engage with your game even more, to make sure they get the most rewards possible. Rewards come in several different types, including items, new maps, badges, and more.
The Rewards service works by integrating with our Statistics and Achievements services to define the benchmarks players must clear to earn rewards, and with our Entitlements and Fulfillment services to grant players the rewards they’ve earned.
Permissions are used to grant access to specific resources within our services. Make sure your account has the following permissions before you attempt to manage rewards in the Admin Portal. For a full list of permissions that impact achievements management, see the Social tab of the permissions reference.
Usage | Permission Tag | Action |
---|---|---|
Create a Reward | ADMIN:NAMESPACE:{namespace}:REWARD | Create |
Get a Reward | ADMIN:NAMESPACE:{namespace}:REWARD | Read |
Import Reward Configurations | ADMIN:NAMESPACE:{namespace}:REWARD | Create |
Export Reward Configurations | ADMIN:NAMESPACE:{namespace}:REWARD | Read |
Permissions work slightly differently depending on whether they are assigned to IAM Clients or Roles assigned to users. For more information, read the Authentication and Authorization documentation.
In the publisher namespace of the Admin Portal, go to the E-Commerce section and open the Rewards menu.
In the Rewards page, click the Add Configuration button.
TheAdd Rewards form appears, as shown below. Fill in the following fields with the required information:
Enter a unique identifier for your reward in the Reward Code field. The reward code must follow the formatting rules provided.
Enter a description of the reward in the Description field.
Select the trigger for the reward from the Event Topic dropdown menu. You can choose either Statistic, Achievement, or User Account.
NOTE
Choose Statistic if you want the reward to be granted to players that achieve a certain statistic. For example, you could create a statistic to measure consecutive days logged in and use it to reward players for logging into your game 7 days in a row.
Choose Achievement if you want the reward to be granted to a player when they earn a particular achievement.
Choose User Account if you want the reward to be granted to players after they make an account in your platform, using either their email address or an account from a 3rd party platform, such as Steam.
Advanced Settings
Enter the specific condition that indicates the target User ID in the event payload in the UserID Expression field, using the JSON path format. This field is optional. If left blank, the default value is $.[0].userId. Format:
$.eventPayloadObject.userId
Enter the specific condition that indicates the target User ID in the event payload in the Namespace Expression field, using the JSON path format. This field is optional. If left blank, the default value is $.[0].namespace. Format:
$.eventPayloadObject.namespace
Input the maximum number of times the reward can be awarded in the Max Awarded field.
Input the maximum number of times the reward can be awarded to a single player in the Max Awarded Per User field.
When you’re done, click Add. The new reward will be added to the list.
On the Rewards page of the Admin Portal, find the reward you wish to change and click View in the reward’s Action column.
Click Add Reward Condition.
The Add Reward Condition form appears. Fill in the fields with the required information:
Enter the name of the event that you want to trigger the reward in the Event Name field. Here’s the list of possible event names:
Event Topic | Event Name | Usage |
Statistics | statItemCreated | Use this event name if you want players to receive the reward upon creating a particular statistical value. |
Statistics | statItemUpdated | Use this event name if you want players to receive the reward upon reaching a particular statistical value. |
Achievement | userAchievementUnlocked | Use this event name if you want players to receive the reward upon earning a particular achievement. |
User Account | userAccountCreated | Use this event name if you want players to receive the reward upon creating an account in your platform, using the publisher namespace. |
User Account | gameUserAccountCreated | Use this event name if you want players to receive the reward upon creating an account in your platform, using the game namespace. |
User Account | userAccountVerified | Use this event name if you want players to receive the reward when their account is verified in your platform, using the game namespace |
User Account | userAccountLinked | Use this event name if you want players to receive the reward upon creating an account in your platform, using the game namespace |
User Account | userAccountUpgraded | Use this event name if you want players to receive the reward upon upgraing their account from a headless account to full account, using the game namespace |
User Account | thirdPartyAccountCreated | Use this event name 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. |
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: Statistics To grant players the reward for reaching a certain statistic, use this JSON path format.
$.[?(@.statCode == "input-your-stat-code" && @.latestValue == x)]
In this example, the player will receive the reward once they reach 30 points in the serverstat3 statistic.
$.[?(@.statCode == "serverstat3" && @.latestValue == 30)]
Event Topic: Achievements To grant players the reward for earning a certain achievement, use this JSON path format.
$.[?(@.userAchievement != null && @.userAchievement.status == 2 && @.userAchievement.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, or input 2 if the reward will be granted when the player receives the achievement.
In the .achievementCode field, input the code for the achievement to which the reward is related. This code can be found under the desired achievement in the Admin Portal.
In this example, the player will receive a reward when they receive the achievement for killing 10 enemies.
$.[?(@.status == 2 && @.achievementCode == "kill-enemies-achievement")]
Event Topic: User Account To grant players the reward for creating an account in your platform, use this JSON path format.
$.[?(@.userId != null && @.emailAddress != null)]
Event Topic: User Account, Third Party Login To grant players the reward upon creating an account on your platform from a third party platform such as Steam or Xbox, use this JSON path format.
$.[?(@.userId != null)]
Fill in the Reward Item fields with the required information:
When you’re done adding items, click Save. The new reward condition will be added to the list.
You can export a reward configuration in JSON format by following the steps below.
In the Rewards menu of the Admin Portal, open the dropdown menu next to the Add Configuration button. Then, click Export Configuration.
The download will be started. Once it’s finished, you can open the JSON file and see a list of your reward configs.
In the Rewards menu of the Admin Portal, open the dropdown menu next to the Add Configuration button. Then, click Import Configuration.
Fill in the Import Configuration form that appears.
Confirm the import configuration by typing IMPORT in the pop-up form below.
When the Rewards service successfully fulfills an item to a player, the game client will receive a notification through the Lobby service. The topic of the message sent to the game client is e-commerce/reward. You can retrieve the notifications from the game by setting the delegate SetMessageNotifDelegate. This allows the player to see any missed notifications. The payload of the function below will be in JSON format.
You can retrieve information about a reward granted to a player by using the following function. This function uses the reward code to find the reward information.
You can retrieve information about a reward granted to a player by using the following function. This function uses the reward ID to find the reward information.
You can retrieve all rewards with a particular event topic, either Achievement, Statistic, or User Account. You can also sort the displayed data. For Unity define your sorting method in the RewardSortBy field, and for Unreal Engine, define the sorting method in the EAccelByteRewardListSortBy field. Here are the possible sorting methods.
Sort | Usage |
---|---|
NONE | This option uses the default sorting, which is to sort by namespace and then reward code in ascending order. |
NAMESPACE_ASC | Sort by namespace in ascending order. |
NAMESPACE_DESC | Sort by namespace in descending order. |
REWARDCODE_ASC | Sort by reward code in ascending order. |
REWARDCODE_DESC | Sort by reward code in descending order. |