Clan reward system

Glossaire

Comment ça marche

The clan reward system gives you the opportunity to incentivize users who are united in a clan and regularly purchase items in the in-game store with real currency. In this case, users receive additional motivation to use the in-game store or web store. You can create clan reward chains by giving out rewards for a certain amount of real currency spent. There can be several chains in the game. The maximum length of one chain is 31 steps. Each step has an execution condition — to gain a given number of value points that show the clan progress in the reward system. When a user who is in a clan (a clan member) makes a purchase, the value points are shared with the entire clan.

At each step, a clan can receive from 1 to 10 rewards for each member. You can reward users by giving out the following item types:

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

Unauthorized users and users without clan can see clan reward chains as blocked.

Comment configurer

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

• Start and end dates of the reward system.

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

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
• personal value points
• clan value points
• steps
• personal reward chains
• clan reward chains
• the balance of the authorized user’s value points
• rewards
• integration of reward methods

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

Configuration dans le Compte éditeur

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

Create clan value points

To create clan value points:

1. Open your project in Publisher Account.
2. Click Store in the side menu.
3. In the Live-ops and promotion tools pane, click:

• Connect — if you don’t have promotions, rewards, or referral programs.
• Configure – if you previously connected promotions, rewards, or referral programs.

4. In the Rewards tab, click Create value points.

5. Specify the following parameters:

• Add an image (optional).
• Specify unique value points SKU.
• Specify that value point will use for a clan.
• Specify value points name.

6. Click Next.
7. Click + and select a virtual item’s SKU and the amount of value points that user will receive per purchase.

8. Click Save.

Clan value points are created and displayed above the reward chains. If necessary, you can change or delete them using the Edit button.

Create clan reward chain

To create a clan reward chain:

1. Open your project in Publisher Account.
2. Click Store in the side menu.
3. In the Live-ops and promotion tools pane, click:

• Connect — if you don’t have promotions, rewards, or referral programs.
• Configure – if you previously connected promotions, rewards, or referral programs.

4. In the Rewards tab, click Create reward.

5. Choose Clan reward chain type.

6. In the drop-down list Clan type, choose a type of the clan.
7. Specify the following parameters:

• Specify reward chain name.
• Specify description.
• Specify a title for the reward chain popup header.
• Specify the text for the popup tip: what you need to do to earn rewards for your clan.
• Add image (optional).
• In the drop-down list choose value points.

8. Click Next.
9. Click Add new step.
10. Specify the following parameters:

• Step name.
• Required amount of value points for claiming the reward.
• Required amount of virtual items for step.

11. Click Save.
    Note

    The value points for each level should be increasing. The recommended maximum length of one chain is 31 steps.
12. Click Next.
13. Specify validity period of the reward chain.
14. 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.

15. Click Save.

​​To activate the reward chain:

1. In the reward catalog, choose the reward chain.
2. Click ••• and choose Activate in 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. Open your project in Publisher Account.
2. In the side menu, click Site Builder.
3. In the pane of the desired site, click Open Site Builder.

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

6. In the drop-down list, choose a reward chain configured in the in-game store.

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

Features for displaying value points

You can select multiple reward chains in one block and choose how to display them: under each other or in tabs. Colors for each track can be customized. Item cards display value points only for those reward chains that have been added to the site. However, when purchasing items, clan members receive value points for all active reward chains, regardless of their display on the site.

Example:

You have 2 reward chains set up: a personal reward chain and a clan reward chain. The first chain has a bonus point called Crystal; the second one has a bonus point called Magic Bubble. In the item catalog, there is a product called Sword with value points: when purchasing this product, a clan member will be credited with 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 you have not added a reward chain to the site, the Sword item will not display value points.
2. If you have only added a personal reward chain to the site, and it is active, then the Sword item will only display 20 Crystals.
3. If you have only added a clan reward chain to the site, and it is active, then the Sword item will only display 40 Magic Bubbles.
4. If you have added both a personal and a clan reward chain to the site, then the Sword item will display both 20 Crystal 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.

Features of displaying tooltips for value points​​

A tooltip is displayed when hovering over value points only if the site has both types of reward tracks — personal and for the clan. The text in the tooltip for a personal reward chain contains information about how many value points the purchase will bring.

TOP-10 contributors

When hovering over the clan reward chain balance, a tooltip will display a list of the top 10 contributors to the reward chain for the user’s current clan. If you have chosen to authenticate by user ID on the site, we recommend returning the value of the user’s name parameter in the webhook response. This will be set as the value of the nickname parameter in the Login project, and the nickname itself will be displayed in the list of top 10 contributors to the reward chain. If you do not send the name parameter value in the webhook response, the list will display user IDs.

Defining the user clan

​​When authenticating by user ID, you need to implement sending the User validation webhook in Web Shop. The response must return an array of attributes objects with the clan_id attribute key. For attributes to work correctly, you need to configure the attribute scheme in Login.

{
  "user": {
    "id": "1234567890",
    "picture": "https://example.com",
    "name": "test-name"
  },
  "attributes": [
    {
     "key": "clan_id",
     "value": "beetles"
    }
  ]
}

In this case, the attribute will be automatically added to the user or updated. 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:

{
  "user": {
    "id": "1234567890",
    "picture": "https://example.com",
    "name": "test-name"
  },
  "removing_keys": [
    "key": "clan_id"
  ]
}

Example of attribute scheme in a Login project:

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"additionalProperties": false,
	"description": "JSON Schema example for user attributes. Not the actual schema.",
	"properties": {

		"clan_id": {
			"description": "name of clan",
			"type": "string"
		},
		"custom-id": {
			"description": "custom-id of a user.",
			"type": "number"
		},
		"had_ban": {
			"description": "Whether the user was banned.",
			"type": "boolean"
		},
		"last_purchase": {
			"description": "Date of user's last purchase.",
			"type": "string"
		},
	},
	"required": [],
	"title": "Example",
	"type": "object"
}

Configuration via des appels API

Pour travailler avec le système de récompense, utilisez les méthodes de la sous-section Admin du groupe de méthodes Reward chains & Value points.

1. Créez les points de valeur qui donnent accès aux récompenses dans le système de récompenses via l'API Create value point.
2. Utilisez l'API Set value points for items pour attribuer des points de valeur aux utilisateurs après l'achat de certains objets.
3. Créez le système de récompense via l'API Create reward chain.
4. Activez le système de récompense via l'API Toggle reward chain.

Vous pouvez modifier, désactiver ou supprimer le système de récompense, ainsi que supprimer les points de valeur des objets.