Create reward chain

How it works

The reward system encourages users to make purchases in the store using real currency. For each purchase, they earn value points and progress through a reward chain. If users are part of clans, their purchases contribute value points to the entire clan.

Example of a reward chain with value points earned per purchase:

Glossary

Prerequisites

Make sure your store contains items that users can purchase to earn value points.

Before creating a clan reward chain, set up user clans.

Create value points

To create value points:

1. Open your project in Publisher Account and go to the LiveOps > Canvas section.

2. In the value points list area, click the + icon.

3. Choose a value point type — Individual value points or Clan value points. Value point type is defined at the creation step and can’t be changed afterward.

4. Add an image (optional).

5. Enter a name.

6. Enter a unique value point SKU.

7. Click Next.

8. Assign value points:

   1. Click Add affected item.

   2. Select the items and specify how many value points users receive for purchasing each item.

   3. Click Select.

   If your store doesn’t contain any items yet, you can save the current settings and return to this step later.

9. Click Next.

10. Check the value points settings.

11. Click Create.

Create reward chain

To create a reward chain:

1. Open your project in Publisher Account and go to the LiveOps > Canvas section.
2. Proceed to create rewards in one of the following ways:
   1. In the toolbar, click the + icon and select Reward chain.
   2. In the reward chains list area, click the + icon.
   3. Open the context menu anywhere on the canvas and select Reward chain.

3. Choose a chain type — Individual reward chain or Clan reward chain. The reward chain type is defined at the creation step and can’t be changed afterward.

4. Specify the basic chain parameters:

   1. If you choose an individual reward chain:
   2. Specify the reward chain name.
   3. Provide a description.
   4. If you choose a clan reward chain:
      1. In the Clan type drop-down list, choose a type of a clan.
      2. Specify the reward chain name.
      3. Provide a description.
      4. Specify a title for the reward chain pop-up heading.
      5. Specify the tooltip text (what users need to do to earn rewards for their clan).
      6. Add a reward pop-up image (optional).

5. Click Next.

6. Set up value points — create new value points or select from existing.

7. Click Next.

8. Add a reward for each step of the chain. To add a reward for a single step:

   1. Click Add new step.

   2. Select items that users receive as a reward for this step and specify the quantity for each item.

   3. Click Add item.

9. In the list of the steps, specify the required amount of value points to claim the reward. The value points allocated to each subsequent step must be higher than the previous one. The maximum limit is 100,000 value points per step.

10. To change the order of rewards in the chain, drag the row to the desired position using the ☰ icon (optional).

11. After you have added rewards for each step, click Next.

12. Specify the validity period of the reward chain: a time zone, start date, and end date. If you don’t want to indicate the end of the validity period, check the No end date box.

Note

To add another reward chain validity period, click Add period. If a chain has multiple validity periods, each must have an end date. The chain ends at the last second of the specified minute. For example, if an end time is set to 12:00, the chain runs until 12:00:59.

If you use the same value points for multiple reward chains, leave at least 15 minutes between one chain period ending and the next starting. Value points and step progress are reset by a background job that runs at :00, :15, :30, and :45 each hour (not at the exact period end). If the next period starts sooner than the next of those times, users may still have their previous balance. If you want to reset the step progress immediately, call the Reset reward chain API method.

13. To automatically reset the progress in the reward chain, turn on the Reset value points toggle.

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

15. If you want to personalize the reward chain:

    1. Turn on the Personalized reward chain toggle.

    2. Select one of the chain display options:

       • Display to eligible users — in this case, the chain is displayed only to authorized users who meet the specified conditions.

       • Display to ineligible users — for such a chain, you don’‎t need to specify the personalization conditions — it is applied by default. It means it is displayed to unauthorized users, as well as in cases when no matching personalized reward chain is found for the authorized user.

    3. If you select Display to eligible users option, specify the condition:

       1. Specify the user attribute type — string, number, or date.

       2. Select the user attribute from the drop-down list.

       3. Select the comparison operator.

       4. Specify the user attribute value.

    4. To add more conditions, click Add condition and fill in the displayed fields (optional).

16. Click Next.

17. Check the chain.

18. To activate the chain immediately (optional), turn on the Create in Active status toggle.

19. Click Create.

Note

Active chains can’t be edited. To change a promotion’s settings, first deactivate it.

You can activate or deactivate the chain in the following ways:

• From the reward chain card
• From the reward chain list
• While editing the chain

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. If your site includes multiple pages, select the one you need:
   1. Click the current page title at the top of the builder.
   2. Select the necessary page from the drop-down list.
4. In the main area of the builder, choose a place where you want to add a new block and click Add block.
5. Select Reward system block.

6. In the drop-down list, select a reward chain.

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

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

Setup 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}

Setup specifics via API

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