Biens gratuits

Comment ça marche

Les objets gratuits sont des objets que les utilisateurs peuvent obtenir sans dépenser de monnaie virtuelle ni de devise réelle. Des objets gratuits sont disponibles dans les cas suivants :

• vente d’objets dans le jeu : objets virtuels, package de monnaie virtuelle et lots ;
• vente de jeux et de DLC via des clés de jeu.

• Objets gratuits offerts lors d’étapes clés d’un projet ou à des dates spéciales, comme un anniversaire, afin de récompenser les utilisateurs pour leur fidélité.
• Extensions gratuites offertes aux utilisateurs ayant déjà acheté le jeu de base, en récompense de leur fidélité.
• Packs de démarrage gratuits disponibles dans le magasin en ligne afin d’attirer de nouveaux utilisateurs sur le jeu.

Configurez les objets gratuits

Configuration dans le Compte éditeur

1. Ouvrez le projet dans le Compte éditeur et accédez à la section Items catalog > All items.
2. Appuyez sur Add et sélectionnez Virtual items dans la liste déroulante.

3. Spécifiez les paramètres suivants :
   • Image (facultatif) ;
   • UGS ;
   • Un ou plusieurs groupes auxquels le lot doit appartenir ;
   • Nom ;
   • Description (facultatif).
4. Dans la section des paramètres Price, sélectionnez Free item.
5. Pour limiter le nombre d’objets qu’un utilisateur peut acheter, activez la bascule Limit number of times one user can buy this item et entrez la quantité souhaitée.
6. Pour configurer la fréquence de réinitialisation de la limite :
   1. Dans la liste déroulante, sélectionnez une période :
      • Daily
      • Weekly
      • Monthly
      • Custom interval — l’intervalle est calculé à partir de la date de début d’affichage du lot
      • No regular refresh
   2. Configurez le calendrier de réinitialisation en fonction de la période sélectionnée.
7. Configurez l’affichage de l’objet dans le magasin :
   • Choisissez le statut ;
   • Définissez une durée d’affichage pour l’objet (facultatif) : indiquez le fuseau horaire ainsi que les dates de début et de fin. Si vous ne souhaitez pas indiquer de date de fin, cochez la case No end date.
8. Configurez les attributs des objets (facultatif) à l’aide de l’une des options suivantes :
   • Ajoutez les attributs et leurs valeurs au format JSON.
   • Créez manuellement des attributs et valeurs, puis associez-les à des objets spécifiques.
9. Appuyez sur Create item.

Configuration via API

Pour rendre un objet gratuit, passez “is_free”: true dans le corps de la requête lors de l’appel des API suivantes de la sous-section Administrateur :

• Créer un objet virtuel ou Mettre à jour un objet virtuel
• Créer un jeu, Mettre à jour un jeu par ID ou Mettre à jour un jeu par UGS
• Créer une monnaie virtuelle ou Mettre à jour une monnaie virtuelle
• Créer un package de monnaie virtuelle ou Mettre à jour un package de monnaie virtuelle
• Créer un lot ou Mettre à jour un lot

• limits avec la quantité maximale ;
• limits.recurrent_schedule avec la fréquence de réinitialisation.

Affichez les objets gratuits dans le catalogue

Les objets gratuits sont affichés dans le catalogue selon leur mode d’implémentation : au moyen du constructeur de site ou via API.

Affichage via le constructeur de site

Pour afficher les objets gratuits sur le site web :

1. Créez des objets gratuits.
2. Ouvrez le projet dans le Compte éditeur et accédez à la section Storefronts > Websites.
3. Dans le volet du site souhaité, appuyez sur Open Site Builder.

4. Dans la section Store, sélectionnez dans le champ Item type le type d’objet gratuit et, le cas échéant, son groupe.
5. Configurez une disposition de carte d’objet.
6. Après avoir effectué toutes les modifications nécessaires et préparé le site web pour le lancement :
   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.

Récupérez des informations sur les objets gratuits via API

Si votre catalogue est configuré via API, les données relatives aux objets gratuits sont renvoyées par les appels de la sous-section Catalogue :

• Lire la liste des objets virtuels
• Lire la liste des monnaies virtuelles
• Lire la liste des packages de monnaie virtuelle
• Lire la liste des lots
• Lire la liste des jeux

Attribuez les objets gratuits aux utilisateurs

Le traitement d’une commande contenant des objets gratuits dépend de l’utilisation ou non du panier lors de l’achat. Si l’utilisateur achète un objet sans utiliser le panier, utilisez l’appel API Créer une commande avec un bien gratuit spécifique. Si l’utilisateur achète des objets en utilisant le panier, les scénarios suivants sont possibles :

• Si le panier de l’utilisateur contient à la fois des objets payants et gratuits, utilisez les appels API de création de commande Créer une commande à partir de tous les objets d’un panier spécifique ou Créer une commande à partir de tous les objets du panier actuel. Dans ce cas, l’utilisateur effectue le paiement via l’interface de paiement.
• Si le panier de l’utilisateur ne contient que des objets gratuits, utilisez les appels API Créer une commande à partir d’un panier gratuit ou Créer une commande à partir d’un panier gratuit spécifique. Dans ce cas, l’interface de paiement n’est pas utilisée.

Dans les deux cas, Xsolla envoie le webhook Paiement de commande réussi avec les données utilisées pour attribuer les objets à l’utilisateur. Pour les objets gratuits, le paramètre order.invoice_id du webhook est défini sur null.

Exemple d’objet de commande pour des objets gratuits :

 1{
 2  "method": "POST",
 3  "url": "https://mybestgame.com/xsolla/notification",
 4  "body": {
 5    "items": [
 6      {
 7        "sku": "gift_direct_game_reward-supercoin",
 8        "type": "virtual_currency",
 9        "is_pre_order": false,
10        "quantity": 500,
11        "amount": "0",
12        "promotions": [
13
14        ]
15      },
16      {
17        "sku": "package-500_supercoin",
18        "type": "bundle",
19        "is_pre_order": false,
20        "quantity": 1,
21        "amount": "0",
22        "promotions": [
23
24        ]
25      },
26      {
27        "sku": "xsolla-giveaway_offer_11_14_22",
28        "type": "bundle",
29        "is_pre_order": false,
30        "quantity": 1,
31        "amount": "0",
32        "promotions": [
33
34        ]
35      }
36    ],
37    "notification_type": "order_paid",
38    "order": {
39      "id": 12345678,
40      "mode": "default",
41      "currency_type": "unknown",
42      "currency": null,
43      "amount": "0",
44      "status": "paid",
45      "platform": "xsolla",
46      "comment": null,
47      "invoice_id": null,
48      "promotions": [
49
50      ]
51    },
52    "user": {
53      "external_id": "1234567812345678",
54      "email": null
55    }
56  },
57  "headers": {
58    "Authorization": "Signature 3b840ccefea111dcdfd111db1fdc6df969a3ec11",
59    "Accept": "application/json",
60    "Content-Type": "application/json"
61  },
62  "type": "webhook_payment",
63  "callback_parameters": {
64    "order_id": 12345678
65  }
66}

Selon les paramètres d’intégration du projet, les objets sont attribués à l’utilisateur de l’une des manières suivantes :

• Si vous avez intégré PlayFab, la monnaie virtuelle et les objets virtuels sont automatiquement ajoutés à l’inventaire PlayFab de l’utilisateur.
• Si vous utilisez un système d’attribution personnalisé, la monnaie virtuelle et les objets virtuels sont attribués de votre côté. Nous recommandons de configurer un gestionnaire de webhook pour recevoir les données de commande sur votre backend. Les informations nécessaires sont incluses dans le webhook Paiement de commande réussi.