Reward system

How it works

The reward system allows you to encourage 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 step, 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 1 to 10 rewards. A clan can also receive 1 to 10 rewards per member at each step.

You can reward users with the following item types:

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

Set up reward system

Set up via Publisher Account

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

To create items manually in your project in Publisher Account, go to the Items catalog > All items section. Detailed information about this and other methods for creating items is available in the Items catalog section of documentation.

To create value points:

1. Open your project in Publisher Account and go to the LiveOps > Rewards section.
2. Click Create value points.

3. Specify the following parameters:
   • Add an image (optional).
   • Enter a name.
   • Enter a unique SKU.
   • If you create clan value points, turn on the Use as clan value points toggle. This setting can’t be changed after the value points are created.
   • Assign value points: select the items and specify how many value points users receive for purchasing each item. If your store doesn’t yet contain any items yet, you can save the current settings and return to this step later.

4. Click Add row to insert the desired number of items.
5. Click Create value points.

To create the reward chain:

1. Open your project in Publisher Account and go to the LiveOps > Rewards section.
2. Click Create reward.

3. Choose a 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 chose a clan reward chain:
1. In the Clan type drop-down list, choose a type of a clan.
2. Set the parameters of the clan reward chain:
   1. Specify the chain name.
   2. Provide a description.
   3. Specify a title for the reward chain popup header.
   4. Specify the tooltip text (what users need to do to earn rewards for their clan).
   5. Add an image (optional).
   6. In the drop-down list, select value points.

5. Click Next.
6. Click Add new step.
7. Specify the following parameters:
   • Name.
   • Required amount of value points to claim the reward.
   • Required amount of virtual items for the step.
8. Click Save.

9. Add the required number of steps and click Next.

10. If you want to personalize the reward chain:

    1. Turn on the Personalized reward chain toggle.
    2. Select one of the chain display options and click Next:
       • Show reward chain to specific users. Set the personalization conditions. In this case, the chain is displayed only to authorized users who meet the specified conditions.
       • Show reward chain to users who don't meet conditions. In this case, 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.
11. Click Next.
12. Specify the validity period of the reward chain.
13. You can turn on the Set time limit toggle and set the expiration date and time for the reward chain.
14. To automatically reset the progress in the reward chain, check the Refresh user progress after the chain ends box.
15. If you want the reward chain to renew at a specific time, turn on the Make reward chain renewable toggle and specify the update schedule.

16. Click Create.

1. In your project in Publisher Account, go to the LiveOps tools > Rewards section.
2. In the row of the desired chain, click •••, then select Activate from the drop-down list.

Set up via API

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

Display reward system

Display via site builder

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

To display reward chains on your site:

1. In your project in Publisher Account, go to the Storefronts > Websites section.
2. Select your site and click Open Site Builder.
3. In the main area of the builder, choose a place where you want to add a new block and click Add block.
4. Select Reward system block.
5. In the drop-down list, select a reward chain.

6. Customize the button and text colors (optional).
7. To preview the chain, click Preview in the upper-right corner of the builder.

8. To apply the changes, publish your site:
   1. In the upper-right corner of the site builder, click Publish.
   2. Check the boxes next to the pages you want to publish.
   3. Click Publish.

Value point display specifics in site builder

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.

Display reward chains via API

1. In your application UI, implement the elements to display rewards chain steps.
2. Implement the logic to work with chains using the following client-side API calls from the Reward chains & Value points group:

3. Ensure that items are correctly granted to the user.

Set up user clan

If you are not using site builder, you need to pass the user’s clan in Xsolla Login the user attributes for the clan reward chain to function correctly. To do this:

1. Set up the attribute schema in Xsolla 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. To add or update the clan_id attribute, use the attribute update methods and pass the attributes array containing objects with the clan_id attribute key.

 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 you use authorization via Xsolla Login, use the Update current user’s clan API call to update the user’s clan. 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.

Display specifics for Web Shop

After configuring the attribute schema, implement passing the user’s clan data.

If you use authentication by user ID, pass the user’s clan data 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, 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    {
 9      "key": "clan_id"
10    }
11  ]
12}

Display specifics via API

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