Système de récompense

Glossaire

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.

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.

Flux utilisateur

1. L’utilisateur accède au site.
2. L’utilisateur voit le catalogue des objets, le système de récompenses, ainsi que le nombre de points de valeur disponibles pour chaque objet.
3. L’utilisateur se connecte
4. L’utilisateur peut maintenant voir sa progression dans le système de récompenses.
5. L’utilisateur effectue un achat et progresse dans la chaîne de récompenses.

Comment configurer

Pour configurer un système de récompenses, vous avez besoin des informations suivantes :

• dates de début et de fin du système de récompenses

• une image, une description, des UGS et des noms de points de valeur qui permettent de progresser dans la chaîne de récompenses individuelle et de clan ;
• le nombre de points de valeur ;
• les objets dans la chaîne de récompenses.

Voir les exemples ci-dessous.

Chaîne de récompenses :

Description	Exemple
Nom	Shard
Texte explicatif	Pour obtenir des récompenses, collectez les shards.
UGS	ExempleUGS003
Image ou son URL

Implémentez de votre côté :

• l’affichage des objets du système de récompenses dans le magasin :
  • le nombre de points de valeur octroyés pour l’achat d’objets dans le catalogue ;
  • les points de valeur ;
  • les étapes ;
  • les chaînes de récompenses ;
  • le solde des points de valeur de l’utilisateur autorisé ;
  • les récompenses.
• l’envoi des données de clan de l’utilisateur à Xsolla Login.

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.

Créer des points de valeur

Pour créer des points de valeur :

1. Ouvrez le projet dans le Compte éditeur et accédez à la section LiveOps > Rewards.
2. Dans l’onglet Rewards, cliquez sur Create value points.

3. Spécifiez les paramètres suivants :
   • Ajoutez une image (facultatif) ;
   • Entrez une UGS unique pour les points de valeur ;
   • Indiquez si les points de valeur seront utilisés pour les clans ;
   • Spécifiez un nom pour les points de valeur.

4. Cliquez sur Next.
5. Sélectionnez l’UGS de l’objet virtuel et indiquez le nombre de points de valeur que l’utilisateur recevra pour chaque achat.
6. Cliquez sur + pour ajouter le nombre requis d’objets.
7. Cliquez sur Save.

Les points de valeur créés apparaissent au-dessus des chaînes de récompenses. Les points de valeur de clan sont marqués en conséquence. Pour modifier les paramètres d’un point de valeur spécifique, cliquez sur Edit dans la ligne correspondante.

Créer une chaîne de récompenses

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 New reward chain — 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 et cliquez sur Save :
   1. Step name ;
   2. Required amount of value points to clame the reward ;
   3. Required amount of virtual items for the step.
8. Cliquez sur Next.

9. Pour 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 cliquez sur Next :
      • Show reward chain to specific users. Lorsque cette option est activée, la chaîne s'affiche uniquement aux utilisateurs autorisés qui remplissent les conditions spécifiées ;
      • Show reward chain to users who don't meet conditions. Lorsque cette option est activée, la chaîne s'affiche uniquement 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.
   3. Si vous avez choisi d'afficher la chaîne à des utilisateurs spécifiques :
      1. Cliquez sur Add condition et définissez les conditions de personnalisation :
         • User attribute est une caractéristique de l'utilisateur, telle que le pays ou l'âge. Les attributs se configurent dans la section Login ;
         • Attribute typ définit le format de la valeur de l'attribut : chaîne de caractères, nombre ou date ;
         • Comparison operator détermine comment la valeur de l'attribut utilisateur est comparée à la condition spécifiée ; par exemple, equals, greater than, less than ou contains ;
         • Valeur de l'attribut est la valeur spécifique utilisée pour la comparaison. Par exemple, si l'attribut utilisateur est l'âge, le type d'attribut est un nombre, l'opérateur de comparaison est supérieur à et la valeur de l'attribut est 18, la chaîne s'affichera uniquement aux utilisateurs de plus de 18 ans.
      2. Pour ajouter une autre condition de personnalisation, cliquez sur Add condition.
   4. Cliquez sur Next.

10. Créez le nombre d’étapes nécessaires, puis cliquez sur Save.

11. Cliquez sur Next.
12. Indiquez la période de validité de la chaîne de récompenses.
13. Si vous souhaitez que la chaîne de récompenses se renouvelle à un moment précis, réglez la bascule Make reward chain renewable sur On et définissez le mode de renouvellement.

14. Cliquez sur Save.

1. Dans le catalogue des récompenses, sélectionnez la chaîne de récompenses.
2. Cliquez sur ••• et choisissez Activate dans la liste déroulante.

Configurer le bloc Système de récompenses dans Site Builder

Pour ajouter un bloc Reward system à une page dans Site Builder :

1. Ouvrez le projet dans le Compte éditeur et accédez à la section Storefronts > Websites.
2. Dans le volet du site souhaité, cliquez sur Open Site Builder.

3. Cliquez sur Add block dans le modèle de site.
4. Sélectionnez Reward system dans la liste des blocs.

5. Dans la liste déroulante, choisissez une chaîne de récompenses configurée dans Shop Builder.

6. Personnalisez les couleurs du bouton et du texte (facultatif).
7. Cliquez sur Preview dans le coin supérieur droit du constructeur pour prévisualiser votre système de récompenses. Cliquez sur Publish pour publier le site.

Configuration via des appels 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.

1. Créez des points de valeur permettant d’accéder à des récompenses via l’API Créer un point de valeur.
2. Attribuez des points de valeur à des objets spécifiques via l’API Définir des points de valeur pour les objets : les utilisateurs recevront ces points après avoir acheté les objets.

3. Créez une chaîne de récompenses via l’API Créer une chaîne de récompenses. Pour créer une chaîne de récompenses personnalisée, passez la condition d’affichage dans le tableau attribute_conditions.

   Vous pouvez spécifier si une chaîne de récompenses personnalisée doit s’afficher à un utilisateur ne possédant pas l’attribut défini dans la condition. Pour ce faire, définissez le paramètre can_be_missing sur true.

   Vous pouvez également définir une chaîne de récompenses qui s’affichera si aucune chaîne personnalisée correspondante n’est trouvée pour l’utilisateur. Pour ce faire, définissez le paramètre is_always_visible sur false.

4. Activez le système de récompenses via l’API Basculer une chaîne de récompenses.

Vous pouvez également modifier, désactiver ou supprimer le système de récompenses, ainsi que supprimer les points de valeur associés aux objets.

Fonctionnalités permettant d'afficher le système de récompenses dans l'interface du magasin

Fonctionnalités d'affichage des points de valeur

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.

Définir le clan d'un utilisateur

Xsolla ne crée pas de clans et ne stocke aucune information sur leurs membres. Vous devez implémenter le système de clans de votre côté et passer les données associées à l’aide des attributs utilisateur.

Pour assurer l’envoi et le traitement corrects des données des clans :

1. Configurez le schéma d’attributs dans Login. Ajoutez l’attribut clan_id.

Exemple de schéma d’attributs dans 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. Implémentez l’envoi des données du 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}

• Si votre site utilise l’autorisation via Xsolla Login, utilisez l’API Update current user’s clan pour mettre à jour le clan de l’utilisateur.