Rewards

Last updated on 15 July, 2022 1:44 AM

Overview

AccelByte Cloud's Rewards service is 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 be more likely to engage with your game more frequently in order to obtain as many rewards as possible. Rewards can be categorized into several different types including: items, new maps, badges, and more.

AccelByte Cloud's 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.

Prerequisites

• Make sure you have already created the statistic or achievement you want to trigger the reward.

Permissions

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 to Roles which are assigned to users. For more information, see the Authentication and Authorization documentation.

Manage Rewards in the Admin Portal

Create a New Reward Configuration

1. In the publisher namespace of the Admin Portal, go to the E-Commerce section and open the Rewards menu.

   

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

   

3. The Add Rewards form will appear, as shown below. Fill in the fields with the required information:

   

   • Enter a unique identifier for your reward in the Reward Code field. This 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.s

     NOTE

     Choose Statistic if you want your 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 for 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

   • Enter the maximum number of times the reward can be earned in your game namespace in the Max Awarded field.

   • Enter the maximum number of times the reward can be earned by a single player in the Max Awarded Per User field.

Once completed, click Add. Your new reward will be added to the Rewards list.

Add a Reward Condition

1. On the Rewards page of the Admin Portal, find the reward you wish to change and click View in the reward's Action column.

   

2. Click Add Reward Condition.

   

3. The Add Reward Condition form will appear. Fill in the fields with the required information:

   

   • Enter the name of the event you want to use to trigger the reward in the Event Name field. Below is a 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 upgrading 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)]

       • Input the statCode for the statistic you're using. This code can be found by looking up the desired statistic in the Admin Portal.

       • Input the statistical value at which the reward will be granted as the latestValue.

         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)]
       • 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.

     • 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)]
       • Input !=null in the userId field. This confirms that the user ID is not null.

   • Fill in the Reward Item fields with the required information:

     • Select the Item you want to grant as a reward. Any item published in your store can be granted as a reward.
     • 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 selected is any other type, you can leave this field blank.
     • To add more items to the reward, click Add More Items. You can select an additional item to add to the reward and set its quantity and duration.

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

   

Export Reward Configurations

1. In the Rewards menu of the Admin Portal, open the dropdown menu next to the Add Configuration button and click Export Configuration.

   

2. The download will begin. Once it has finished, you can open the JSON file to see a list of your reward configurations.

Import Reward Configurations

1. In the Rewards menu of the Admin Portal, open the dropdown menu next to the Add Configuration button and click Import Configuration.

   

2. The Import Configuration form will appear. Fill in the fields with the required information:

   

   • Choose the File to Import. The file should be in JSON format.
   • Select the Import Method.
     • Choose Replace if you want to replace an old config with a new one. The new config must have the same reward code as the config you want to replace. If you have multiple configs in your file, any configs with unique reward codes will also be imported.
     • Choose Leave Out if you want to add a new config without replacing any old configs. Using this method, any configs in your JSON file whose reward codes match existing configs will not be imported. Only configs with unique reward codes will be imported.

3. Once completed, click Import. Confirm the import configuration by typing IMPORT into the pop-up form that appears and then click Import once more to confirm.

   

Implement Rewards using the Client SDKs

Rewards Notification

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

Unreal Engine

FRegistry::Lobby.SetMessageNotifDelegate(THandler<FAccelByteModelsNotificationMessage>::CreateLambda([](FAccelByteModelsNotificationMessage Result)
{
    if (Result.Topic == "e-commerce/rewards")
    {
        UE_LOG(LogTemp, Log, TEXT("From: %s | Payload: %s"), *Result.From, *Result.Payload);
    }
}));

Unity

AccelBytePlugin.GetLobby().OnNotification += result =>
        {
            if (result.Value.topic == "e-commerce/rewards")
            {
                Debug.Log($"From: {result.Value.from} | Payload: {result.Value.payload}");
            }
        };

Retrieve Reward Information by the Reward Code

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.

Unreal Engine

FString RewardCode = FString("MyRewardCode");
FRegistry::Reward.GetRewardByRewardCode(RewardCode, THandler<FAccelByteModelsRewardInfo>::CreateLambda([](const FAccelByteModelsRewardInfo& Result)
{
    // Do something if GetRewardByRewardCode has been successful
}),
FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetRewardByRewardCode has an error
    UE_LOG(LogTemp, Log, TEXT("Error GetRewardByRewardCode, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Unity

string rewardCode = "MyRewardCode";
        AccelBytePlugin.GetReward().GetRewardByRewardCode(rewardCode, result =>
        {
            if (result.IsError)
            {
                // Do something if GetReward has an error
                Debug.Log($"Error GetRewardByRewardCode, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if GetReward has been successful
            }
        });

Retrieve Reward Information by Reward ID

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.

Unreal Engine

FString RewardId = FString("MyRewardId");
FRegistry::Reward.GetRewardByRewardId(RewardId, THandler<FAccelByteModelsRewardInfo>::CreateLambda([](const FAccelByteModelsRewardInfo& Result)
{
    // Do something if GetRewardByRewardId has been successful
}),
FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetRewardByRewardId has an error
    UE_LOG(LogTemp, Log, TEXT("Error GetRewardByRewardId, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Unity

string rewardId = "MyRewardId";
        AccelBytePlugin.GetReward().GetRewardByRewardId(rewardId, result =>
        {
            if (result.IsError)
            {
                // Do something if GetRewardByRewardId has an error
                Debug.Log($"Error GetRewardByRewardId, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if GetRewardByRewardId has been successful
            }
        });

Retrieve All Rewards

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. For Unreal Engine, define your sorting method in the EAccelByteRewardListSortBy field. The possible sorting methods are:

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.

Unreal Engine

FString EventTopic = FString("Achievement");
int32 Offset = 0;
int32 Limit = 10;
EAccelByteRewardListSortBy SortBy = EAccelByteRewardListSortBy::NONE;
FRegistry::Reward.QueryRewards(EventTopic, Offset, Limit, SortBy, THandler<FAccelByteModelsQueryReward>::CreateLambda([](const FAccelByteModelsQueryReward& Result)
{
    // Do something if QueryRewards has been successful
}),
FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if QueryRewards has an error
    UE_LOG(LogTemp, Log, TEXT("Error QueryRewards, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Unity

string eventTopic = "Achievement";
        int offset = 0;
        int limit = 20;
        RewardSortBy sortBy = RewardSortBy.NAMESPACE;
        AccelBytePlugin.GetReward().QueryRewards(eventTopic, sortBy, result =>
        {
            if (result.IsError)
            {
                // Do something if QueryRewards has an error
                Debug.Log($"Error QueryRewards, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if QueryRewards has been successful
            }
        }, offset, limit);

Related Concepts

• Learn more about how our Cloud Statistics service works.
• Take a look at our Cloud Achievements guide.
• Rewards are taken from items in your store, so make sure to learn about our Cloud E-commerce service.