Personnalisation du catalogue des objets

Ce tutoriel montre comment :

• personnaliser le catalogue en utilisant des attributs créés de votre côté (pour les partenaires qui utilisent le jeton d’accès Pay Station pour autoriser les utilisateurs) ;
• spécifier les règles de validation des attributs dans le schéma JSON et ajouter des attributs à l’utilisateur du côté de Xsolla (pour les partenaires qui utilisent le Xsolla Login pour autoriser les utilisateurs) ;
• créer une règle d’affichage du catalogue ;
• récupérer le catalogue des objets pour un utilisateur avec différentes valeurs d’attributs.

Prérequis

Avant de commencer, assurez-vous que :

• Vous avez créé un catalogue d’objets en jeu ou de clés de jeu, pour lequel la personnalisation sera configurée ;
• Vous avez exploré la section User attributes (pour les partenaires qui utilisent Xsolla Login pour autoriser les utilisateurs) ;
• Vous avez ajouté des utilisateurs dans les paramètres de votre projet de connexion dans la section User database > Users, pour lesquels vous pouvez ajouter des attributs (pour les partenaires qui utilisent Xsolla Login pour autoriser les utilisateurs).

Personnalisation en utilisant un jeton d'accès Pay Station pour autoriser les utilisateurs

Si vous utilisez un jeton d’accès Pay Station pour autoriser les utilisateurs, vous pouvez passer les attributs lors de l’obtention du jeton. Dans ce cas, procédez comme suit pour configurer la personnalisation :

1. Créez des attributs dans votre système.
2. Ajoutez des attributs aux utilisateurs dans votre système.
3. Implémentez une logique pour mettre à jour les valeurs des attributs lorsqu’elles changent pour un utilisateur dans le jeu.
4. Créez des règles d’affichage du catalogue avec vos attributs.
5. Passez les attributs lorsque vous obtenez le jeton d’accès Pay Station.
6. Utilisez le jeton reçu dans les méthodes de requête du catalogue des objets.

Personnalisation en utilisant Xsolla Login pour autoriser les utilisateurs

Si vous utilisez Xsolla Login pour autoriser les utilisateurs, vous devez :

1. Créer un schéma JSON pour les attributs utilisateur du côté de Xsolla et spécifier les attributs qu’il contient (facultatif).

2. Ajoutez des attributs aux utilisateurs et mettez à jour les valeurs des attributs en utilisant Login API.
3. Créez des règles d'affichage du catalogue avec les attributs créés.
4. Implémentez l'obtention d'un JWT utilisateur. Vous trouverez une liste de méthodes pour obtenir un JWT dans cet exemple.
5. Utilisez le jeton reçu dans les méthodes pour demander le catalogue des objets.

Il existe plusieurs façons d’ajouter des attributs à un utilisateur :

• Utilisez les méthodes de mise à jour d’attributs :
  • Update user’s attributes from server ;
  • Update user’s read-only attributes from server.

1. Utilisez ces méthodes pour ajouter des attributs à un utilisateur et mettre à jour les valeurs des attributs. Pour personnaliser le catalogue, il est essentiel de mettre à jour les valeurs des attributs : Mettez à jour les valeurs des attributs dans Xsolla lorsqu'elles changent pour l'utilisateur dans le jeu.

1. Exemple : Un utilisateur atteint un nouveau niveau, accomplit une quête ou effectue un achat.

1. Vous pouvez mettre à jour les valeurs d'un seul attribut ou de plusieurs attributs simultanément. L'exception concerne les attributs spécifiés comme obligatoires dans le schéma JSON. Si vous ne spécifiez pas de valeurs d'attributs obligatoires, vous ne pourrez pas appeler les méthodes API de mise à jour d'attributs.

• Passez les valeurs réelles des attributs directement lors de l'autorisation utilisateur si vous utilisez la méthode Auth by custom ID. Dans cette méthode, vous pouvez passer un tableau contenant les valeurs actuelles des attributs utilisateur.

Exemple de configuration de la personnalisation

Cet exemple montre comment configurer la personnalisation du catalogue : l’objet Medium Crystal Set n’est affiché que pour les utilisateurs ayant acheté le jeu MyTestGame.

Création du schéma des attributs

• Attribut “game” avec le type “string” — nom du jeu que l’utilisateur achète. L’attribut “game” est marqué comme obligatoire. Vous ne pouvez pas appeler de méthodes de mise à jour d’attribut si vous ne passez pas l’attribut “game” ;

• Attribut “purchase_number” avec type “integer” — nombre d’achats de l’utilisateur.

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"title": "Example",
	"description": "JSON Schema description.",
	"properties": {
		"game": {
			"description": "Name of the game played by a user.",
			"type": "string"
		},
		"purchase_number": {
			"description": "The number of purchases the user made.",
			"type": "integer"
		}
	},
	"additionalProperties": false,
	"required": [
		"game"
	],
	"type": "object"
}

Ajout d'attributs à un utilisateur

Ajoutez des attributs à un utilisateur à partir de la base de données utilisateur en utilisant la méthode Update user’s read-only attributes from server.

Dans la méthode Update user’s read-only attributes from the server, assurez-vous de spécifier :

• Jeton de serveur.
• Valeurs des attributs utilisateur.
• user_id — l’identifiant de l’utilisateur spécifié dans les paramètres de votre projet de connexion dans le Compte éditeur dans la section User database > Users.
• publisher_id — l’ID de commerçant affiché :
  • dans la section Company settings > Company ;
  • dans l’URL de la barre d’adresse du navigateur sur n’importe quelle page du Compte éditeur. L’URL est au format suivant : https:​//publisher.xsolla.com/<merchant ID>/<Publisher Account section>.
• publisher_project_id — l’ID de projet qui se trouve dans le Compte éditeur à côté du nom du projet.

En premier lieu, obtenez le jeton de serveur en utilisant la méthode Generate JWT.

Puis, procédez avec la méthode Update user’s read-only attributes from the server.

Le corps de la requête avec un tableau des attributes est au format suivant :

{
  "attributes": [
    {
      "key": "game",
      "permission": "private",
      "value": "MyTestGame"
    },
 {   
     "key": "purchase_number",
      "permission": "private",
      "value": "30"
    }

  ],
  "publisher_id": 000000,
  "publisher_project_id": 000000
}

Après l’exécution de la requête, l’utilisateur qui initialement ne possédait pas d’attributs en possède désormais avec leurs valeurs spécifiées :

Création d'une règle d'affichage du catalogue

Configurez une règle pour afficher l’objet Medium Crystal Set uniquement aux utilisateurs ayant acheté le jeu MyTestGame.

Pour ce faire :

1. Dans le Compte éditeur, accédez à Store > Catalog management > Catalog display rules.
2. Cliquez sur Create rule et complétez les champs requis :
   1. clé d’attribut dans le champ User attribute — game ;
   2. type — string ;
   3. opérateur de comparaison — equal to ;
   4. valeur — MyTestGame.

3. Spécifiez l'objet qui doit s'afficher si la condition est satisfaite. Dans l'exemple ci-dessous, le Medium Crystal Set est affiché pour les utilisateurs qui possèdent le jeu MyTestGame.

4. Vérifiez la règle, activez-la et enregistrez-la.

Obtention du jeton

Obtention du JWT Xsolla Login

• Auth by username and password ;
• Auth via social provider ;
• Passwordless auth by email ;
• Passwordless auth by phone number ;
• Auth via device ID ;
• Auth by custom ID ;
• Et d’autres méthodes du groupe de méthodes JWT ou OAuth 2.0. pour obtenir le jeton utilisateur.

Obtention du jeton d'accès Pay Station

Obtenez le jeton d’accès Pay Station avec l’attribut requis. Pour ce faire, passez “game”: “MyTestGame” dans l’objet attributes dans la méthode Create token.

Exemple de corps de la requête :

{
  "settings": {
    "currency": "USD",
    "language": "en",
    "project_id": 000001,
    "ui": {
      "size": "medium"
    }
  },
  "user": {
    "email": {
      "value": "email@example.com"
    },
    "id": {
      "value": "user_2"
    },
    "name": {
      "value": "John Smith"
    },
    "attributes": {
      "game": "MyTestGame"
    }
  }
}

Obtention du catalogue des objets

Obtention du catalogue des objets en utilisant le jeton JWT Xsolla Login

Récupérez le catalogue en utilisant le jeton de l’utilisateur auquel vous avez ajouté l’attribut game avec pour valeur MyTestGame. Pour ce faire, spécifiez ce qui suit dans la méthode Get virtual items list :

• le JWT utilisateur obtenu dans l’en-tête d’autorisation ;
• l’ID du projet dans le Compte éditeur en tant que paramètre de chemin d’accès.

La réponse comprend trois objets :

• Empire Key ;
• Small Crystal Pack ;
• Medium Crystal Set, pour lequel la règle de personnalisation est configurée.

"attributes": [
{
    "attr_type": "server",
    "key": "game",
    "permission": "private",
    "value": "OtherGame",
    "read_only": true
 },
{
    "attr_type": "server",
    "key": "purchase_number",
    "permission": "private",
    "value": "30",
    "read_only": true
  }
]

La méthode Get virtual items list avec le jeton obtenu renvoie deux objets : Empire Key et Small Crystal Pack. Le Medium Crystal Set, auquel une règle de personnalisation a été appliquée, n’est pas inclus dans la réponse.

Pour comparaison, passons maintenant l’attribut game avec pour valeur MyTestGame.

Voici le tableau des attributes dans la méthode Auth by custom ID pour l’utilisateur qui possède le jeu MyTestGame :

"attributes": [
{
    "attr_type": "server",
    "key": "game",
    "permission": "private",
    "value": "MyTestGame",
    "read_only": true
 },
{
    "attr_type": "server",
    "key": "purchase_number",
    "permission": "private",
    "value": "30",
    "read_only": true
  }
]

Spécifiez le jeton obtenu lorsque vous demandez le catalogue des objets dans la méthode Get virtual items list.

En conséquence, le Medium Crystal Set est inclus dans la réponse :

Obtention du catalogue des objets en utilisant le jeton d'accès Pay Station

Pour obtenir le catalogue des objets personnalisés, spécifiez ce qui suit dans la méthode Get virtual items list :

• le jeton d’accès Pay Station obtenu dans l’en-tête d’autorisation ;
• l’ID du projet dans le Compte éditeur en tant que paramètre de chemin d’accès.

La réponse comprend trois objets :

• Empire Key ;
• Small Crystal Pack ;
• Medium Crystal Set, pour lequel la règle de personnalisation est configurée.

Vous pouvez vérifier la réponse lors de l’obtention du catalogue des objets pour voir si l’utilisateur ne possède pas l’attribut game avec pour valeur MyTestGame.

Lorsque vous recevez le jeton d’accès Pay Station, supprimez l’objet attributes et demandez à nouveau le catalogue des objets en utilisant la méthode Get virtual items list. Maintenant, la réponse n’inclut pas le Medium Crystal Set :