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

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 Reward system block in Site Builder

To add a Reward system block to a page in Site Builder:

1. In your project in Publisher Account, go to the Site Builder.
2. In the pane of the desired site, click Open Site Builder.

3. Click Add block in the site template.
4. Choose Reward system in the blocks list.

5. In the drop-down list, choose a reward chain configured in the Shop Builder.

6. Customize the button and text colors (optional).
7. Click Preview in the upper right corner of the builder to check your reward system. Click Publish to publish the site.

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.

Features for displaying reward system in the store interface

Features for displaying value points

You can select multiple reward chains within a single block and choose how they are displayed — either one below the other or in tabs. You can customize the appearance of each reward chain individually.

Item cards display value points only for the reward chains that have been added to the site. However, when users purchase items, clan members receive value points for all active reward chains, regardless of whether they are displayed on the site.

Example:

You have 2 reward chains set up: one individual reward chain and one clan reward chain. The individual chain has a value point named Crystal, and the clan chain has a value point called Magic Bubble.

In the item catalog, there is an item named Sword with assigned value points. When a clan member purchases this item, they will receive 20 Crystals and 40 Magic Bubbles.

When you add the Store block in the builder and select the type and group of items that contain the Sword item:

1. If no reward chain has been added to the site, the Sword item will not display any value points.
2. If only an individual reward chain has been added and is active, the Sword item will display 20 Crystals only.
3. If only a clan reward chain has been added and is active, the Sword item will display 40 Magic Bubbles only.
4. If both an individual and a clan reward chain have been added and are active, the Sword item will display both 20 Crystals and 40 Magic Bubbles.

For clan members, 40 Magic Bubbles will be displayed as an active value.

For users without a clan, 40 Magic Bubbles will be displayed as a locked value.

Defining the user clan

Xsolla does not create clans or store information about the clan members. You need to implement the clan system on your side and pass clan-related data using user attributes.

To ensure correct sending and processing of clan data:

1. Set up the attribute scheme in Login. Add the clan_id attribute.

Example of the attribute scheme in Login:

 1{
 2	"$schema": "https://json-schema.org/draft/2020-12/schema",
 3	"additionalProperties": false,
 4	"description": "JSON Schema example for user attributes. Not the actual schema.",
 5	"properties": {
 6
 7		"clan_id": {
 8			"description": "name of clan",
 9			"type": "string"
10		},
11		"custom-id": {
12			"description": "custom-id of a user.",
13			"type": "number"
14		},
15		"had_ban": {
16			"description": "Whether the user was banned.",
17			"type": "boolean"
18		},
19		"last_purchase": {
20			"description": "Date of user's last purchase.",
21			"type": "string"
22		},
23	},
24	"required": [],
25	"title": "Example",
26	"type": "object"
27}

2. Implement sending the user’s clan data:

• When authenticating by user ID, pass the user’s clan in the response to the User validation webhook in Web Shop webhook during authorization:
• To add or refresh the clan_id attribute, pass an array of attributes objects with the clan_id attribute key.

Example of a webhook response:

 1{
 2  "user": {
 3    "id": "1234567890",
 4    "picture": "https://example.com",
 5    "name": "test-name"
 6  },
 7  "attributes": [
 8    {
 9     "key": "clan_id",
10     "value": "beetles"
11    }
12  ]
13}

• If the user has left the clan and has not joined another, you need to pass the clan_id value in the removing_keys field.

Example of a webhook response:

 1{
 2  "user": {
 3    "id": "1234567890",
 4    "picture": "https://example.com",
 5    "name": "test-name"
 6  },
 7  "removing_keys": [
 8    "key": "clan_id"
 9  ]
10}

• If the site uses authorization via Xsolla Login, use the Update current user’s clan API to update the user’s clan.