Système de récompense

Comment ça marche

Le système de récompenses permet d’inciter les utilisateurs à effectuer des achats dans le magasin avec des devises réelles. Si l’utilisateur fait partie d’un clan, ses achats apportent des points de valeur à l’ensemble du clan.

Vous pouvez créer des chaînes de récompenses individuelles ou de clan et attribuer des récompenses aux utilisateurs pour les objets achetés. Le jeu peut comprendre plusieurs chaînes de récompenses de différents types. Chaque chaîne peut comporter jusqu’à 31 étapes. Pour chaque niveau, vous définissez le nombre de points de valeur nécessaires pour le compléter.

Vous pouvez également créer une chaîne de récompenses personnalisée. La personnalisation vous permet d’afficher la chaîne uniquement à un groupe spécifique d’utilisateurs autorisés selon leurs attributs. La chaîne de récompenses personnalisée peut être destinée à des utilisateurs individuels ou à un clan.

À chaque étape de la chaîne de récompenses, un utilisateur peut recevoir entre 1 et 10 récompenses. Un clan peut également recevoir entre 1 et 10 récompenses par membre à chaque étape.

Vous pouvez récompenser les utilisateurs avec les types d’objet suivants :

• objets virtuels ;
• monnaie virtuelle ;
• packages de monnaie virtuelle ;
• lots.

Configuration du système de récompenses

Configuration dans le Compte éditeur

Avant de créer une chaîne de récompenses, vous devez d’abord créer des points de valeur, des récompenses et des objets que les utilisateurs et les clans peuvent acheter pour gagner des points de valeur.

Pour créer des objets manuellement dans le projet depuis le Compte éditeur, accédez à la section Items catalog > All items. Pour des informations détaillées sur cette méthode et les autres façons de créer des objets, consultez la section Catalogue des objets de la documentation.

Pour créer des points de valeur :

1. Ouvrez le projet dans le Compte éditeur et accédez à la section LiveOps > Rewards.
2. Appuyez sur Create value points.

3. Spécifiez les paramètres suivants :
   • Ajoutez une image (facultatif) ;
   • Entrez un nom ;
   • Entrez une UGS unique ;
   • Si vous créez des points de valeur de clan, activez la bascule Use as clan value points. Ce paramètre ne peut pas être modifié une fois les points de valeur créés ;
   • Attribuez des points de valeur : sélectionnez les objets et indiquez le nombre de points de valeur que l’utilisateur reçoit pour l’achat de chaque objet. Si votre magasin ne contient encore aucun objet, vous pouvez enregistrer les paramètres actuels et revenir à cette étape ultérieurement.

4. Áppuyez sur Add row pour insérer le nombre de positions souhaité.
5. Appuyez sur Create value points.

Pour créer une chaîne de récompenses :

1. Ouvrez le projet dans le Compte éditeur et accédez à la section LiveOps > Rewards.
2. Cliquez sur Create reward.

3. Choisissez le type de chaîne — Individual reward chain ou Clan reward chain.
4. Spécifiez les paramètres suivants. Si vous choisissez une chaîne de récompenses individuelle :
   1. Indiquez le nom de la chaîne de récompenses ;
   2. Ajoutez une description ;
   3. Sélectionnez les points de valeur dans la liste déroulante.

Si vous choisissez la chaîne de récompenses de clan :
1. Dans la liste déroulante Clan type, choisissez un type de clan ;
2. Définissez les paramètres de la chaîne de récompenses du clan :
   1. Indiquez le nom de la chaîne de récompenses,
   2. Ajoutez une description,
   3. Indiquez un titre pour l'en-tête de la fenêtre contextuelle de la chaîne de récompenses,
   4. Spécifiez le texte de l'infobulle (ce que les utilisateurs doivent faire pour gagner des récompenses pour leur clan),
   5. Ajoutez une image (facultatif),
   6. Choisissez les points de valeur dans la liste déroulante.

5. Cliquez sur Next.
6. Cliquez sur Add new step.
7. Spécifiez les paramètres suivants :
   • Step name ;
   • Required amount of value points to claim the reward ;
   • Required amount of virtual items for the step.
8. Appuyez sur Save.

9. Ajoutez le nombre d’étapes requis et appuyez sur Next.

10. Si vous souhaitez personnaliser la chaîne de récompenses :

    1. Activez la bascule Personalized reward chain.
    2. Sélectionnez l’une des options d'affichage de la chaîne et appuyez sur Next :
       • Show reward chain to specific user. Définissez les conditions de personnalisation. La chaîne n’est affichée qu’aux utilisateurs autorisés qui remplissent les conditions spécifiées.
       • Show reward chain to users who don’t meet conditions. La chaîne n’est affichée que si aucune chaîne de récompenses correspondante n’est trouvée pour l’utilisateur, par exemple si l’utilisateur n’est pas autorisé ou si ses attributs ne correspondent à aucune chaîne personnalisée.
11. Cliquez sur Next.
12. Indiquez la période de validité de la chaîne de récompenses.
13. Vous pouvez activer la bascule Set time limit, puis définir la date et l’heure d’expiration de la chaîne de récompenses.
14. Pour réinitialiser automatiquement la progression dans la chaîne de récompenses, cochez la case Refresh user progress after the chain ends checkbox.
15. Si vous souhaitez renouveler la chaîne de récompenses à une date précise, activez la bascule Make reward chain renewable, puis indiquez le mode de mise à jour.

16. Appuyez sur Create.

1. Ouvrez le projet dans le Compte éditeur et accédez à la section LiveOps > Rewards.
2. Dans la ligne de la chaîne souhaitée, cliquez sur •••, puis sélectionnez Activate dans la liste déroulante.

Configuration via API

Pour gérer le système de récompenses, utilisez les méthodes de la sous-section Administrateur du groupe de méthodes Chaînes de récompense et points de valeur.

Affichage du système de récompenses

Affichage via le constructeur de site

Pour que le système de récompenses fonctionne correctement, l’authentification utilisateur doit être configurée. Les utilisateurs non authentifiés verront les chaînes de récompenses, individuelles comme de clan, sans aucune progression. Les utilisateurs authentifiés mais non affiliés à un clan ne verront que leur chaîne de récompenses individuelle, tandis que celle de clan apparaîtra comme indisponible.

Pour afficher les chaînes de récompenses sur votre site :

1. Ouvrez le projet dans le Compte éditeur et accédez à la section Storefronts > Websites.
2. Sélectionnez votre site et appuyez sur Open Site Builder.
3. Dans la zone principale de l’éditeur, choisissez l’emplacement où vous souhaitez ajouter un nouveau bloc, puis appuyez sur Add block.
4. Choisissez le bloc Reward system.
5. Dans la liste déroulante, choisissez une chaîne de récompenses.

6. Personnalisez les couleurs du bouton et du texte (facultatif).
7. Pour prévisualiser la chaîne, appuyez sur Preview dans le coin supérieur droit du constructeur.

8. Pour appliquer les modifications, publiez le site :
   1. Dans le coin supérieur droit du constructeur, appuyez sur Publish.
   2. Sélectionnez les pages que vous souhaitez publier en cochant les cases correspondantes.
   3. Appuyez sur Publish.

Spécificités d’affichage des points de valeur dans le constructeur de site

Vous pouvez regrouper plusieurs chaînes de récompenses dans un même bloc et choisir leur mode d’affichage : en liste verticale ou sous forme d’onglets. Vous pouvez également personnaliser l’apparence de chaque chaîne de récompenses.

Les cartes d’objet n’affichent des points de valeur que pour les chaînes de récompenses ajoutées au site. Toutefois, lorsque les utilisateurs achètent des objets, les membres du clan reçoivent des points de valeur pour toutes les chaînes de récompenses actives, qu’elles soient affichées ou non sur le site.

Exemple :

Vous avez configuré deux chaînes de récompenses : une individuelle et une de clan. La chaîne individuelle utilise des points de valeur nommés Crystal, tandis que la chaîne de clan utilise des points de valeur nommés Magic Bubble.

Le catalogue des objets comprend un objet nommé Sword, auquel sont associés des points de valeur. Lorsqu’un membre de clan achète cet objet, il reçoit 20 Crystals et 40 Magic Bubbles.

Lorsque vous ajoutez le bloc Store dans le constructeur et que vous sélectionnez le type et le groupe d’objets qui contiennent l’objet Sword :

1. Si aucune chaîne de récompenses n’est ajoutée au site, l’objet Sword n’affichera aucun point de valeur.
2. Si seule une chaîne de récompenses individuelle est ajoutée et activée, l’objet Sword affichera uniquement 20 Crystals.
3. Si seule une chaîne de récompense de clan est ajoutée et activée, l’objet Sword n’affichera que 40 Magic Bubbles.
4. Si une chaîne de récompenses individuelle et une chaîne de récompenses de clan sont toutes deux ajoutées et activées, l’objet Sword affichera à la fois 20 Crystals et 40 Magic Bubbles.

Pour les membres de clan, 40 Magic Bubbles seront affichés comme valeur active.

Pour les utilisateurs sans clan, 40 Magic Bubbles seront affichés comme valeur verrouillée.

Affichage des chaînes de récompenses via des appels API

1. Dans l’interface de votre application, implémentez les éléments nécessaires pour afficher les étapes de la chaîne de récompenses.
2. Implémentez la logique pour gérer les chaînes en utilisant les appels API côté client suivants du groupe Chaînes de récompenses et points de valeur :

3. Assurez-vous que les objets sont correctement attribués à l’utilisateur.

Configurez un clan utilisateur

Si vous n’utilisez pas le constructeur de site, vous devez passer le clan de l’utilisateur dans les attributs utilisateur de Xsolla Login afin que la chaîne de récompenses du clan fonctionne correctement. Pour ce faire :

1. Configurez le schéma d’attributs dans 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. Pour ajouter ou mettre à jour l’attribut clan_id, utilisez les méthodes de mise à jour des attributs et transmettez dans le corps de la requête le tableau attributes avec la valeur clan_id.

 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}

Si vous utilisez l’authentification via Xsolla Login, appelez l’API Mise à jour du clan de l’utilisateur actuel pour modifier le clan de l’utilisateur. Si les attributs indiquent un nouveau clan, l’utilisateur recevra toutes les récompenses non réclamées de la chaîne de récompenses de son ancien clan, et son affiliation sera mise à jour. Si l’utilisateur appartenait auparavant à un clan, mais n’en fait plus partie, son affiliation sera révoquée. La réponse de cette méthode inclut les récompenses que l’utilisateur a déjà réclamées.

Spécificités d’affichage pour le Web Shop

Après avoir configuré le schéma d’attributs, implémentez le transfert des données de clan de l’utilisateur.

Lors de l’authentification par ID utilisateur, passez le clan de l’utilisateur dans la réponse au webhook Validation utilisateur dans Web Shop lors de l’autorisation :

• Pour ajouter ou actualiser l’attribut clan_id, passez un tableau d’objets attributes avec la clé d’attribut clan_id.

Exemple de réponse de webhook :

 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}

• Si l’utilisateur a quitté le clan sans en rejoindre un autre, vous devez passer la valeur clan_id dans le champ removing_keys.

Exemple de réponse de webhook :

 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}

Spécificités d’affichage via API

Vous pouvez passer les valeurs des attributs actuels directement lors de l’autorisation de l’utilisateur si vous utilisez l’API Auth by custom ID.