Objets virtuels

Présentation

Les objets virtuels sont des objets en jeu que les utilisateurs peuvent acheter contre des devises réelles ou de la monnaie virtuelle, ou encore recevoir en bonus. Ces objets sont dépourvus de forme physique et sont exclusivement utilisés dans le jeu. Exemples courants : skins, potions, armes, clés et autres éléments qui influencent le gameplay ou l’apparence des personnages.

Fonctionnalités principales :

• Configuration de prix flexible :
  • Possibilité de définir un prix pour un même objet à la fois en devises réelles et en monnaie virtuelle.
  • Possibilité de définir des prix pour un même objet dans plusieurs devises réelles et monnaies virtuelles. Dans ce cas, vous devez spécifier une devise par défaut pour chaque type : une pour les devises réelles, une pour les monnaies virtuelles.
  • Création d’objets gratuits.
  • Configuration des prix régionaux.
• Détection automatique de la devise et du pays.
• Paramètres de disponibilité :
  • Limiter la vente d’objets dans différentes régions.
  • Limiter le nombre d’objets disponibles à l’achat.
  • Limiter la durée d’affichage des objets dans le magasin.
  • Configuration des objets non disponibles à l’achat. Un objet peut être masqué dans le catalogue, tout en restant accessible via un lot ou comme bonus lors de l’achat d’un autre objet.
• Organisation du catalogue :
  • Création de groupes.
  • Tri des objets dans le catalogue.

Configuration dans le Compte éditeur

Créer un groupe

Les groupes vous permettent de construire un catalogue à plusieurs niveaux. Les objets qui ne sont pas affectés à un groupe seront placés dans le groupe Ungrouped. Le groupe Ungrouped ne peut être ni modifié ni supprimé.

Pour créer un groupe :

1. Dans votre projet, dans le Compte éditeur, accédez à la section Store > Virtual items.
2. Cliquez sur + et sélectionnez Create group dans la liste déroulante.

3. Spécifiez les paramètres suivants :
   • External ID — ID de groupe unique ;
   • Group name.
4. Pour que le groupe soit disponible dans le magasin, réglez la bascule Show group in Store sur On. Dans ce cas, le groupe sera créé avec le statut Enabled. Vous pouvez modifier le statut du groupe ultérieurement.
5. Cliquez sur Create group.

Note

Si un groupe a le statut Disabled, ce groupe :

• n’est pas renvoyé dans la réponse lors de l’appel à la méthode API Get item group list ;
• n’est pas affiché dans les propriétés de objets inclus dans ce groupe lors de l’appel aux méthodes API du client pour obtenir une liste des objets ;
• n’est pas disponible pour une utilisation dans Site Builder.

Pour modifier le statut du groupe après sa création, recherchez le groupe souhaité dans la section Store > Virtual items et sélectionnez le statut nécessaire dans la colonne Status.

Vous pouvez créer un catalogue à plusieurs niveaux en ajoutant de nouveaux groupes à l’intérieur des groupes existants. L’exception est le groupe Ungrouped, pour lequel la création de groupes imbriqués n’est pas disponible.

Pour imbriquer un groupe existant dans un autre groupe :

1. Dans votre projet, dans le Compte éditeur, accédez à la section Store > Virtual items.
2. Sélectionnez le groupe que vous souhaitez imbriquer dans un autre groupe existant.
3. Cliquez sur ••• et sélectionnez Edit group dans la liste déroulante.
4. Dans la liste déroulante Directory location, sélectionnez le groupe parent dans lequel vous souhaitez placer le groupe actuel.

5. Cliquez sur Save changes.

Créer un objet virtuel

Pour créer un objet virtuel :

1. Dans votre projet, dans le Compte éditeur, accédez à la section Store > Virtual items.
2. Cliquez sur + et sélectionnez Create item dans la liste déroulante.

3. Définissez le statut de disponibilité de l’objet virtuel dans le catalogue. Sélectionnez l’une des options suivantes :
   • Unavailable (par défaut) — l’objet n’est pas disponible à l’achat dans le catalogue, ne peut pas être inclus dans un lot ou utilisé comme bonus pour l’achat d’un autre objet ;
   • Available — l’objet est disponible à l’achat dans le catalogue et peut être inclus dans un lot ou utilisé comme bonus pour l’achat d’un autre objet ;
   • Partially available — l’objet n’est pas disponible à l’achat dans le catalogue, mais peut être ajouté à un lot ou utilisé comme bonus pour l’achat d’un autre objet.
   Vous pouvez modifier le statut de disponibilité de l’objet ultérieurement.

4. Configurez les paramètres de base. Spécifiez les éléments suivants :
   • image (facultatif) ;
   • UGS ;
   • un ou plusieurs groupes auxquels l’article doit appartenir ;
   • nom de l’objet ;
   • description de l’objet (facultatif).

5. Laissez le type d’objet défini par défaut : Consumable (recommandé).

6. Configurez le prix de l’objet virtuel :
   • Pour créer un objet virtuel gratuit, dans le champ Paid or free, sélectionnez Free item ;
   • Pour créer un objet virtuel payant, dans le champ Paid or free, sélectionnez Paid item et indiquez le prix dans une ou plusieurs devises.
   • Configurez les prix régionaux (facultatif).

7. Limiter le nombre d’objets disponibles à l’achat (facultatif). Pour ce faire :
   1. Réglez la bascule Limit number of times one user can buy this item sur On, et spécifiez le nombre d’objets achetable par utilisateur.
   2. Configurez la fréquence d’actualisation de la limite :
      1. Si vous ne souhaitez pas réinitialiser la limite, sélectionnez No regular refresh dans la liste déroulante.
      2. Si vous souhaitez réinitialiser régulièrement la limite, sélectionnez une fréquence d’actualisation dans la liste déroulante et indiquez quand la réinitialisation doit avoir lieu.
8. Limiter la durée d’affichage des objets dans le magasin (facultatif). Pour ce faire, dans le champ Show item in store, sélectionnez Time period, indiquez le fuseau horaire ainsi que les dates de début et de fin de la période. Si vous ne souhaitez pas indiquer de date de fin d’affichage pour l’objet, cochez la case No end date.
9. Ajoutez des attributs supplémentaires (facultatif).
10. Cliquez sur Create item.

Interagir avec les objets virtuels via API

Utilisez les appels API de la sous-section Administrateur du groupe Objets et monnaie virtuels pour configurer les objets virtuels.

Une autorisation de base est requise pour utiliser les appels API. Passez le code Authorization:Basic <your_authorization_basic_key>, où <your_authorization_basic_key> est la paire merchant ID:API key encodée conformément à la norme Base64. Accédez au Compte éditeur pour trouver les paramètres suivants :

• Merchant ID est 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>/.

• L'API key ne s'affiche dans le Compte éditeur qu'une seule fois lors de sa création, vous devez donc la conserver de votre côté. Vous pouvez créer une nouvelle clé dans les sections suivantes :
  • Company settings > API keys ;
  • Project settings > API keys.

Utilisez les appels API de la sous-section Catalogue du groupe Objets et monnaie virtuels pour obtenir le catalogue des objets virtuels côté client. Ces appels ne nécessitent pas d’autorisation de base.

Utilisez l’appel API Lire une liste d’objets virtuels pour obtenir la liste complète des objets non divisés en groupes. Pour obtenir la liste des objets du groupe défini, passez le paramètre external_id à l’appel Lire une liste d’objets par groupe spécifique.

Paramètres avancés pour les objets virtuels

Limiter le nombre d'objets disponibles à l'achat

Vous pouvez limiter le nombre d’achats d’un objet virtuel spécifique par utilisateur. Cela permet de contrôler la disponibilité des objets et de créer des offres exclusives.

Voici quelques cas d’usage :

• Limiter l’achat d’un objet virtuel à une fois par jour, par semaine ou par mois.
• Proposer un objet de bienvenue que chaque utilisateur peut acheter une seule fois.

Il existe deux façons de configurer les limites d’achat :

• Dans le Compte éditeur : Lors de la création ou de la modification d’un objet, réglez la bascule Limit number of times one user can buy this item sur On, indiquez la quantité disponible à l’achat et configurez le calendrier d’actualisation ;
• Via API : Lors de la création ou de la modification d’un objet, passez les paramètres de limite d’achat dans l’objet limits dans le corps de la requête.

L’application des limites est entièrement gérée côté Xsolla. Le système suit le nombre d’achats effectués par chaque utilisateur pour un objet donné et empêche les achats dépassant la limite configurée.

Si un jeton d’accès utilisateur est inclus dans une requête de catalogue (lors de l’appel de méthodes API de la sous-section Catalogue du groupe Virtual Items & Currency), Xsolla calcule le nombre d’unités de chaque bien que l’utilisateur spécifique peut encore acheter. La réponse comprendra l’objet limits contenant la quantité totale autorisée (le paramètre total) et la quantité restante disponible pour cet utilisateur (le paramètre available). Ces valeurs peuvent être utilisées pour afficher la disponibilité dans l’interface.

Si le jeton d’accès utilisateur n’est pas fourni dans la requête, la valeur du paramètre available correspondra toujours à la limite totale dans la réponse.

Exemple de réponse contenant des biens avec des limites d’achat :

 1{
 2  "items": [
 3    {
 4      "sku": "big_rocket",
 5      "name": "Big Rocket",
 6      "groups": [
 7        {
 8          "external_id": "accessory",
 9          "name": "Accessory"
10        }
11      ],
12      "attributes": [
13        {
14          "external_id": "stack_size",
15          "name": "Stack size",
16          "values": [
17            {
18              "external_id": "size_e3364991f92e751689a68b96598a5a5a84010b85",
19              "value": "5"
20            }
21          ]
22        }
23      ],
24      "type": "virtual_good",
25      "description": "Big Rocket - description",
26      "image_url": "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png",
27      "is_free": false,
28      "price": {
29        "amount": "100.99",
30        "amount_without_discount": "100.99",
31        "currency": "USD"
32      },
33      "virtual_prices": [
34        {
35          "amount": 100,
36          "sku": "vc_test",
37          "is_default": true,
38          "amount_without_discount": 100,
39          "image_url": "http://image.png",
40          "name": "SHOTGUN FOR TRUE RAIDERS",
41          "type": "virtual_currency",
42          "description": "description"
43        }
44      ],
45      "can_be_bought": true,
46      "inventory_options": {
47        "consumable": {
48          "usages_count": 1
49        },
50        "expiration_period": {
51          "type": "day",
52          "value": 1
53        }
54      },
55      "virtual_item_type": "non_renewing_subscription",
56      "limits": {
57        "per_user": {
58            "total": 5,
59            "available": 5
60        },
61        "per_item": null
62      },
63}

En outre, Xsolla applique la limite d’achat à la fois lors de l’initialisation de la commande et lors de la finalisation de la commande. Si un utilisateur ouvre plusieurs onglets ou tente de créer plusieurs commandes simultanément, le système empêchera le dépassement de la limite : les commandes non payées contenant des objets déjà achetés seront annulées.

Limiter la durée d'affichage des objets dans le magasin

Vous pouvez spécifier une période d’affichage pour les objets dans le magasin afin de :

• maintenir la pertinence du catalogue à un moment donné, par exemple pendant les soldes de fin d’années ;
• créer un objet à l’avance sans l’afficher dans le catalogue ;
• inciter les utilisateurs à acheter en affichant une minuterie à côté de l’objet.

Pour configurer la durée d’affichage d’un objet dans le magasin, procédez comme suit :

• Dans le Compte éditeur : Lors de la création ou de la modification d’un objet, dans le champ Show item in store, sélectionnez Time period et indiquez le fuseau horaire, les dates de début et de fin. Pour laisser la date de fin ouverte, cochez la case No end date.
• Via API : Lors de la création ou de la mise à jour d’un bien, inclure les paramètres suivants dans l’objet periods :
  • periods[0].date_from — la date et l’heure de début de la période d’affichage (format :YYYY-MM-DDThh:mm:ss±hh:mm ) ;
  • periods[0].date_until — la date et l’heure de fin de la période d’affichage. Pour omettre la date de fin, passez null.

Vous pouvez définir plusieurs périodes d’affichage à via API en transmettant un tableau d’objets, chacun comportant une date de début et une date de fin.

Exemple de tableau de périodes :

 1"periods": [
 2      {
 3        "date_from": "2022-06-10T14:00:00+03:00",
 4        "date_until": "2022-06-30T14:00:00+03:00"
 5      },
 6       {
 7        "date_from": "2022-07-10T14:00:00+03:00",
 8        "date_until": "2022-07-30T14:00:00+03:00"
 9      },
10       {
11        "date_from": "2022-08-10T14:00:00+03:00",
12        "date_until": "2022-08-30T14:00:00+03:00"
13      }
14]

Configurez des restrictions régionales

Vous pouvez configurer les régions dans lesquelles un objet virtuel sera disponible à l’achat. Cela vous permet de contrôler qui voit l’objet et où. Par exemple, vous pouvez masquer l’objet pour les utilisateurs de certains pays ou le rendre disponible uniquement dans des régions spécifiques dans le cadre d’une campagne promotionnelle régionale.

Pour configurer des restrictions régionales pour les objets virtuels, incluez un tableau d’objets regions avec les ID de région correspondants dans le corps de la requête lorsque vous appelez les méthodes API Créer un objet virtuel ou Mettre à jour un objet virtuel.

Exemple de tableau de régions :

1"regions": [{
2     “id”: “123”
3  }, {
4     “id”: “456”
5  }
6]

Configurez les prix régionaux

Vous pouvez définir des prix régionaux pour ajuster le coût des objets virtuels en fonction des conditions économiques propres à chaque pays. Cette approche permet de rendre les offres plus accessibles dans les régions au pouvoir d’achat variable, ce qui augmente le taux de conversion et stimule les ventes globales.

Vous pouvez configurer les prix régionaux comme suit :

• Dans le Compte éditeur (configuration manuelle) : Lors de la création ou de la modification d’un objet, accédez à la section Price settings, réglez la bascule Prices in real currency sur On, puis cliquez sur Set up prices. Vous pouvez saisir les prix manuellement ou les calculer automatiquement en fonction des devises et des taxes.
• Via l’importation CSV dans le Compte éditeur : dans le fichier CSV, vous pouvez ajouter plusieurs lignes indiquant les prix des objets pour différentes régions. Pour plus d’informations sur la structure du fichier et des exemples, consultez l’instruction Prix locaux.

 1SKU,Currency,Amount,Country,IsDefault,Platform
 2game-key-1,EUR,9.09,,1,steam
 3game-key-1,EUR,9.2,DE,0,steam
 4game-key-1,EUR,8.09,IT,0,steam
 5game-key-1,USD,10.1,US,0,steam
 6game-key-1,MYR,47,MY,0,steam
 7game-key-2,EUR,2.09,,1,steam
 8game-key-2,EUR,2.2,DE,0,steam
 9game-key-2,EUR,1.79,IT,0,steam
10game-key-2,USD,2.3,US,0,steam
11game-key-2,MYR,24,MY,0,steam

• Via API : Lors de la création ou mise à jour d’un objet, incluez le tableauprices dans le corps de la requête avec les paramètres de prix régionaux.

 1"prices": [
 2      {
 3        "amount": 100,
 4        "currency": "USD",
 5        "is_enabled": true,
 6        "is_default": true
 7      },
 8      {
 9        "amount": 200,
10        "currency": "CZK",
11        "country_iso": "CZ",
12        "is_enabled": false,
13        "is_default": false
14      }
15    ]

Liens utiles