Skip to main content

Rewards

Last updated on

Overview

AccelByte Foundations’ Rewards are an effective way of increasing 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. There are several types of reward, 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.

Prerequisites

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

Managing Rewards in the Admin Portal

Create a New Reward Configuration

  1. In the game title on the Admin Portal, expand the E-Commerce section and open the Rewards menu.

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

    rewards

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

    rewards

    • Reward Code: Type a unique identifier for your reward. The reward code must follow the formatting rules in the pop-up that appears.
    • Description: Type a description of the reward.
    • Event Topic: Select one of the available event topics the reward should listen to.
      • Choose Statistic if you want the reward to be granted to players who 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 seven 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 create an account on your platform, using either their email address or an account from a third-party platform, such as Steam.
    • Advanced Settings: If you expand this option, two more fields appear as shown below.

    rewards

    • UserID Expression (Optional): Type the specific 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. Use the format $.eventPayloadObject.userId

    • Namespace Expression (Optional): Type the specific condition that indicates the target User ID in the event payload, using the JSON path format. This field is optional. If left blank, the default value is $.[0].namespace. Use the format $.eventPayloadObject.namespace

    • Max Awarded: Input the maximum number of times the reward can be awarded.

    • Max Awarded Per User: Input the maximum number of times the reward can be awarded to a single player.

  4. When you’re done, click Add. The new reward is added to the list.

Add a Reward Condition

  1. In the game title on the Admin Portal, expand the E-Commerce section and open the Rewards menu.

  2. On the Rewards page of the Admin Portal, click in the Action column next to the reward configuration you want to add conditions to and select View.

    rewards

  3. Click Add Reward Condition.

    rewards

  4. The Add Reward Condition form appears. Fill in the fields with the required information:

    rewards

    • Event Name: Type the name of the event that will trigger the reward. Here’s the list of possible event names:
    Event List
    Event TopicEvent NameUsage
    StatisticsstatItemCreatedTo reward players for creating a particular statistical value.
    StatisticsstatItemUpdatedTo reward players for reaching a particular statistical value.
    AchievementuserAchievementUnlockedTo reward players for earning a particular achievement.
    User AccountuserAccountCreatedTo reward players for creating an account in your platform, using the publisher namespace.
    User AccountgameUserAccountCreatedTo reward players for creating an account in your platform, using the game namespace.
    User AccountuserAccountVerifiedTo reward players for verifying when their account in your platform, using the game namespace
    User AccountuserAccountLinkedTo reward players for creating an account in your platform, using the game namespace
    User AccountuserAccountUpgradedTo reward players for upgrading their account from a headless account to full account, using the game namespace
    User AccountthirdPartyAccountCreatedTo reward players for creating an account on your platform from a third party platform. Both userAccountCreated and thirdPartyAccountCreated are contained within the User Account event topic.
    • Condition Name: Type a name for the specific event condition that triggers the reward.

    • Condition: Type the specific condition that triggers the reward in JSON path format. 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)]

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

        ii. 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")]

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

        ii. In the .achievementCode field, input the code for the achievement the reward relates to. 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)]

        i. Input !=null in the userId field. This confirms that the user ID is not null.

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

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

      • Item: Select the Item you want to grant as a reward. Any item published in your store can be granted as a reward.
      • Qty: Input the quantity of the item you want to include in the reward.
      • Duration (Days): If the reward item is a subscription, input how many days the subscription should last. 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.

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

    rewards

Import and Export Reward Configurations

As an administrator, you can export and import reward configurations from or to the Admin Portal. For example, you can export reward configurations to be used in other game titles.

  1. In the intended game title, expand the E-Commerce section and click Rewards. The Rewards page appears.

  2. Click the arrow next to the Add Configuration button.

    rewards

  3. Two options appear:

    • Export Configuration: All of the reward configurations of the selected game title will be downloaded to your computer in .JSON format.

    OR

    • Import Configuration: The Import Configuration form will appear. Click Select File to browse for the reward configuration you want to import, then choose the import method.

    rewards

    • Choose Replaceif you want to overwrite 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. Click Import when you’re done.

    A confirmation window appears. To confirm your selection, type IMPORT in the text box and then click the Import button.

    rewards

Implementing Rewards using the SDK

Rewards Notification

When the Rewards service successfully fulfils to send 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.

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);
}
}));

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.

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);
}));

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.

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);
}));

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, and for Unreal Engine, define the sorting method in the EAccelByteRewardListSortBy field. Here are the possible sorting methods.

SortUsage
NONEThis option uses the default sorting, which is to sort by namespace and then reward code in ascending order.
NAMESPACE_ASCSort by namespace in ascending order.
NAMESPACE_DESCSort by namespace in descending order.
REWARDCODE_ASCSort by reward code in ascending order.
REWARDCODE_DESCSort by reward code in descending order.
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);
}));