Créer une chaîne de récompenses

Comment ça marche

Le système de récompenses incite les utilisateurs à effectuer des achats en magasin avec des devises réelles. Chaque achat permet de gagner des points de valeur et de progresser dans une chaîne de récompenses. Si les utilisateurs appartiennent à un clan, leurs achats contribuent également aux points de valeur de l’ensemble du clan.

Exemple d’une chaîne de récompenses avec des points de valeur gagnés par achat :

Glossaire

Prérequis

Assurez-vous que votre magasin contient des objets que les utilisateurs peuvent acheter pour gagner des points de valeur.

Avant de créer une chaîne de récompenses de clan, configurez les clans d’utilisateurs.

Créer des points de valeur

Pour créer des points de valeur :

1. Ouvrez votre projet dans le Compte éditeur et allez dans la section LiveOps > Canvas.

2. Dans la zone de liste des points de valeur, cliquez sur l’icône +.

3. Choisissez un type de point de valeur — Individual value points ou Clan value points. Le type de point de valeur est défini lors de la création et ne peut être modifié par la suite.

4. Ajoutez une image (facultatif).

5. Entrez un nom.

6. Entrez un SKU unique pour le point de valeur.

7. Cliquez sur Next.

8. Attribuez des points de valeur :

   1. Cliquez sur Add affected item.

   2. Sélectionnez les objets et spécifiez combien de points de valeur les utilisateurs reçoivent pour l’achat de chaque objet.

   3. Cliquez sur Select.

   Si votre magasin ne contient pas encore d’objets, vous pouvez enregistrer les paramètres actuels et revenir à cette étape plus tard.

9. Cliquez sur Next.

10. Vérifiez les paramètres des points de valeur.

11. Cliquez sur Create.

Créer une chaîne de récompenses

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

1. Ouvrez votre projet dans le Compte éditeur et allez dans la section LiveOps > Canvas.
2. Procédez à la création de récompenses de l’une des manières suivantes :
   1. Dans la barre d’outils, cliquez sur l’icône + et sélectionnez Reward chain.
   2. Dans la zone de la liste des chaînes de récompenses, cliquez sur l’icône +.
   3. Ouvrez le menu contextuel n’importe où sur le canvas et sélectionnez Reward chain.

3. Choisissez un type de chaîne — Individual reward chain ou Clan reward chain. Le type de chaîne de récompenses est défini lors de la création et ne peut être modifié par la suite.

4. Spécifiez les paramètres de base de la chaîne :

   1. Si vous choisissez une chaîne de récompenses individuelle :
   2. Spécifiez le nom de la chaîne de récompenses.
   3. Fournissez une description.
   4. Si vous choisissez une chaîne de récompenses de clan :
      1. Dans la liste déroulante Clan type, choisissez un type de clan.
      2. Spécifiez le nom de la chaîne de récompenses.
      3. Fournissez une description.
      4. Spécifiez un titre pour l’en-tête de la fenêtre contextuelle de la chaîne de récompenses.
      5. Spécifiez le texte de l’infobulle (ce que les utilisateurs doivent faire pour gagner des récompenses pour leur clan).
      6. Ajoutez une image pour la fenêtre contextuelle de récompense (facultatif).

5. Cliquez sur Next.

6. Configurez les points de valeur — créez de nouveaux points de valeur ou sélectionnez parmi les existants.

7. Cliquez sur Next.

8. Ajoutez une récompense pour chaque étape de la chaîne. Pour ajouter une récompense pour une seule étape :

   1. Cliquez sur Add new step.

   2. Sélectionnez les objets que les utilisateurs reçoivent comme récompense pour cette étape et spécifiez la quantité pour chaque objet.

   3. Cliquez sur Add item.

9. Dans la liste des étapes, spécifiez le montant requis de points de valeur pour réclamer la récompense. Les points de valeur alloués à chaque étape suivante doivent être supérieurs à ceux de la précédente. La limite maximale est de 100 000 points de valeur par étape.

10. Pour changer l’ordre des récompenses dans la chaîne, faites glisser la ligne à la position souhaitée en utilisant l’icône ☰ (facultatif).

11. Après avoir ajouté les récompenses pour chaque étape, cliquez sur Next.

12. Spécifiez la période de validité de la chaîne de récompenses : un fuseau horaire, une date de début et une date de fin. Si vous ne souhaitez pas indiquer la fin de la période de validité, cochez la case No end date.

Note

Pour ajouter une autre période de validité à la chaîne de récompenses, cliquez sur Add period. Si une chaîne comporte plusieurs périodes de validité, chacune doit avoir une date de fin. La chaîne se termine à la dernière seconde de la minute spécifiée. Par exemple, si une heure de fin est fixée à 12:00, la chaîne fonctionne jusqu’à 12:00:59.

Si vous utilisez les mêmes points de valeur pour plusieurs chaînes de récompenses, laissez au moins 15 minutes entre la fin d’une période de chaîne et le début de la suivante. Les points de valeur et la progression des étapes sont réinitialisés par un travail en arrière-plan qui s’exécute à :00, :15, :30 et :45 chaque heure (pas exactement à la fin de la période). Si la période suivante commence avant l’un de ces moments, les utilisateurs peuvent encore avoir leur solde précédent. Si vous souhaitez réinitialiser immédiatement la progression des étapes, appelez la méthode API Réinitialiser la chaîne de récompenses.

13. Pour réinitialiser automatiquement la progression dans la chaîne de récompenses, activez la bascule Reset value points.

14. Si vous souhaitez que la chaîne de récompenses se renouvelle à un moment précis, activez la bascule Make reward chain renewable et spécifiez le calendrier de mise à jour.

15. 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 :

       • Display to eligible users — dans ce cas, la chaîne est affichée uniquement aux utilisateurs autorisés qui remplissent les conditions spécifiées.

       • Display to ineligible users — pour une telle chaîne, vous n’avez pas besoin de spécifier les conditions de personnalisation — elle est appliquée par défaut. Cela signifie qu’elle est affichée aux utilisateurs non autorisés, ainsi que dans les cas où aucune chaîne de récompenses personnalisée correspondante n’est trouvée pour l’utilisateur autorisé.

    3. Si vous sélectionnez l’option Display to eligible users, spécifiez la condition :

       1. Spécifiez le type d’attribut utilisateur — chaîne, nombre ou date.

       2. Sélectionnez l’attribut utilisateur dans la liste déroulante.

       3. Sélectionnez l’opérateur de comparaison.

       4. Spécifiez la valeur de l’attribut utilisateur.

    4. Pour ajouter d’autres conditions, cliquez sur Add condition et remplissez les champs affichés (facultatif).

16. Cliquez sur Next.

17. Vérifiez la chaîne.

18. Pour activer la chaîne immédiatement (facultatif), activez la bascule Create in Active status.

19. Cliquez sur Create.

Note

Les chaînes actives ne peuvent pas être modifiées. Pour changer les paramètres d’une promotion, désactivez-la d’abord.

Vous pouvez activer ou désactiver la chaîne de la manière suivante :

• Depuis la carte de la chaîne de récompenses
• Depuis la liste des chaînes de récompenses
• Lors de l’édition de la chaîne

Affichage du système de récompenses

Affichage via le constructeur de site

Pour garantir le bon fonctionnement du système de récompenses, l’authentification des utilisateurs doit être configurée. Pour les utilisateurs non authentifiés, les chaînes de récompenses individuelles et de clan s’affichent sans progression.

Les utilisateurs authentifiés qui ne sont membres d’aucun clan voient uniquement leur chaîne de récompenses individuelle. Les chaînes de récompenses de clan s’affichent comme indisponibles.

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. Si votre site comporte plusieurs pages, sélectionnez celle qui vous intéresse :
   1. Appuyez sur le titre de la page actuelle en haut du constructeur.
   2. Sélectionnez la page souhaitée dans la liste déroulante.
4. Dans la zone principale de l’éditeur, choisissez l’emplacement où vous souhaitez ajouter un nouveau bloc, puis appuyez sur Add block.
5. Choisissez le bloc Reward system.

6. Dans la liste déroulante, choisissez une chaîne de récompenses.

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

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

Paramètres de configuration du 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}

Paramètres de configuration 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.