Reward system

Glossary

How it works

The reward system allows you to incentivize users to make purchases in the store using real currency. If users are part of clans, their purchases contribute value points to the entire clan.

You can create individual and clan-based reward chains and grant users rewards for purchased items. The game can include multiple reward chains of any type. Each chain can have a maximum of 31 steps. For each level, you define the number of value points required to complete it.

You can also create a personalized reward chain. Personalization allows you to display the chain only to a specific group of authorized users based on their attributes. A personalized reward chain can be designed for either an individual user or a clan.

At each step in the reward chain, a user can receive between 1 and 10 rewards. A clan can also receive between 1 and 10 rewards per member at each step.

You can reward users with the following item types:

• virtual items
• virtual currency
• virtual currency packages
• bundles

To ensure the reward system works correctly, user authentication must be configured. For unauthenticated users, both individual and clan reward chains are displayed without progress. Authenticated users who are not members of a clan see only their individual reward chain. Clan reward chains appear as unavailable.

User flow

1. The user goes to the site.
2. The user sees the item catalog, reward system, and the number of value points available for each item.
3. The user logs in.
4. The user can now view their current progress in the reward system.
5. The user makes a purchase and progresses along the reward chain.

How to get it

To set up a reward system, you will need the following details:

• start and end dates of the reward system

• an image, description, SKUs, and names of value points that enable progress in the individual and clan reward chain
• the number of value points
• items in the reward chain

See the examples below.

Reward chain:

Description	Example
Name	Shard
Explanatory text	To get rewards, collect the shards.
SKU	ExampleSKU003
Image or its URL

Implement on your side:

• display of elements of the reward system in the store:
  • the number of value points that are awarded for purchasing items in the catalog
  • value points
  • steps
  • reward chains
  • the balance of the authorized user’s value points
  • rewards
• sending user’s clan data to Xsolla Login

To set up the reward system, implement the following API methods:

• Get virtual items list
• Get current user’s reward chains
• Get current user’s value point balance
• Claim step reward
• Update current user’s clan
• Get top 10 contributors to reward chain under clan

Define user’s clan

If you are not using Xsolla Site Builder, you need to pass the user’s clan in the user attributes for the clan reward chain to function correctly.

To add an attribute with a clan to a user, use the attribute update methods and pass the attributes array with the clan value in the request body.

Example:

 1
 2{
 3"attributes": [
 4{
 5
 6"key": "clan_id",
 7"value": "beetles"
 8}
 9],
10"publisher_id": 000000,
11"publisher_project_id": 000000
12}

You can pass current attribute values ​​directly during user authorization if you are using the Auth by custom ID API.

You can also update the user’s current clan using the API. First, update the user’s attributes in Xsolla Login, then call the Update current user’s clan API. If the attributes contain a new clan, the user will receive any unclaimed rewards from the previous clan’s reward chain, and their clan affiliation will be updated. If the user was previously a member of a clan but is no longer part of one, their clan membership will be revoked. The response from this method includes the rewards that the user has already claimed.

Set up via Publisher Account

Before creating a reward chain, you need to create value points, rewards and items that users and a clan can purchase to earn value points.

Create value points

To create value points:

1. In your project in Publisher Account, go to the Store > Live-ops and promotion tools section.
2. In the Rewards tab, click Create value points.

3. Specify the following parameters:
   • Add an image (optional).
   • Enter a unique SKU for the value points.
   • Indicate whether the value points will be used for a clan
   • Provide a name for the value points.

4. Click Next.
5. Select the SKU of the virtual item and specify the number of value points the user will receive per purchase.
6. Click + to add the required number of items.
7. Click Save.

The created value points are displayed above the reward chains. Clan value points are marked accordingly. To change the settings for a specific value point, click Edit in the corresponding row.

Create reward chain

To create the reward chain:

1. In your project in Publisher Account, go to the Store > Live-ops and promotion tools section.
2. Click Create reward.

3. Choose New reward chain type — Individual reward chain or Clan reward chain.
4. Specify the following parameters. If you choose an individual reward chain:
   1. Specify the reward chain name.
   2. Provide a description.
   3. In the drop-down list, select value points.

If you choose clan reward chain:
1. In the drop-down list Clan type, choose a type of a clan.
2. Set the parameters of the clan reward chain:
   1. Specify the reward chain name.
   2. Provide a description.
   3. Specify a title for the reward chain popup header.
   4. Specify the text for the popup tip (what users need to do to earn rewards for their clan).
   5. Add an image (optional).
   6. In the drop-down list, choose value points.

5. Click Next.
6. Click Add new step.
7. Specify the following parameters and click Save:
   1. Step name.
   2. Required amount of value points to clame the reward.
   3. Required amount of virtual items for the step.
8. Click Next.

9. If you want to personalize the reward chain:

   1. Set the Personalized reward chain toggle to active.
   2. Select one of the chain display options and click Next:
      • Show reward chain to specific users. When enabled, the chain is displayed only to authorized users who meet the specified conditions.
      • Show reward chain to users who don't meet conditions. When enabled, the chain is displayed only if no matching reward chain is found for the user — for example, if the user is not authorized or their attributes don’t match any personalized chain.
   3. If you selected to display the chain to specific users:
      1. Click Add condition and set the personalization conditions:
         • User attribute is a user characteristic, such as country or age. Attributes are configured in the Login section.
         • Attribute type defines the format of the attribute value: string, number, or date.
         • Comparison operator determines how the user attribute value is compared to the specified condition — for example, equals, greater than, less than, or contains.
         • Attribute value is the specific value used for comparison. For example, if the user attribute is age, the attribute type is number, the comparison operator is greater than, and the attribute value is 18, the chain will be shown only to users over 18.
      2. To add another personalization condition, click Add condition.
   4. Click Next.

10. Create the required number of steps and click Save.

11. Click Next.
12. Specify the validity period of the reward chain.
13. If you want the reward chain to renew at a specific time, set the Make reward chain renewable toggle to On and specify the update mode.

12. Click Save.

1. In the reward catalog, select the reward chain.
2. Click ••• and choose Activate from the drop-down list.

Set up via API calls

You can use methods from the Admin subsection of the Reward chains & Value points method group to manage the reward system.

1. Create value points that grant access to rewards via the Create value point API.
2. Assign value points to specific items via the Set value points for items API — users will receive these points after purchasing the items.

3. Create a reward system via the Create reward chain API. To create a personalized reward chain, pass the display condition in the attribute_conditions array.

   You can specify whether a personalized reward chain should be shown to a user who doesn’t have the attribute defined in the condition. To do this, pass true in the can_be_missing parameter.

   You can also define a reward chain that is shown to a user if no matching personalized chain is found. To do this, pass false in the is_always_visible parameter.

4. Activate the reward system via the Toggle reward chain API.

You can also modify, disable, or delete the reward system and remove value points from items.