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 en jeu : objets virtuels, packages de monnaie virtuelle et lots
• Vente de jeux et de DLC au moyen de clés de jeu

Cas d’utilisation :

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

Les objets virtuels, la monnaie virtuelle et les lots gratuits sont réservés aux utilisateurs authentifiés. Les clés de jeu gratuites sont accessibles avec ou sans authentification. Les limites sur le nombre d’objets gratuits ne peuvent être configurées que pour les utilisateurs authentifiés.

Configuration des objets gratuits

2. Appuyez sur Create manually, puis sélectionnez Virtual item dans la liste déroulante.

3. Dans la section General settings, indiquez les éléments suivants :
   • UGS
   • un ou plusieurs groupes auxquels l’objet doit appartenir (facultatif)
   • nom
   • description courte
   • description détaillée : pour l’ajouter, activez la bascule correspondante (facultatif)

4. Dans la sectionMedia, importez une ou plusieurs images ou vidéos depuis votre appareil ou via un lien (facultatif). Dans le magasin créé avec l’éditeur de site Xsolla, toutes les fiches d’objet affichent le fichier marqué Main. Les autres fichiers sont uniquement disponibles dans les fiches dotées d’une galerie de médias. Le fichier marqué Main est également renvoyé dans les réponses des appels API de récupération du catalogue.

5. Dans la section Price settings, sélectionnez Free item.

6. Pour limiter le nombre d’objets disponibles à l’achat :
   1. Activez la bascule dans la section Limits et indiquez la quantité.
   2. Configurez la fréquence de réinitialisation de la limite. Pour cela, sélectionnez une période dans la liste déroulante :
      1. Daily.
      2. Weekly.
      3. Monthly.
      4. Custom interval. L’intervalle est calculé à partir de la date de début daffichage de l’objet dans le magasin.
      5. No regular refresh.
   3. Définissez le calendrier de réinitialisation en renseignant les paramètres de la période sélectionnée.

7. Pour limiter la période d’affichage de l’objet (facultatif) :

   1. Activez la bascule dans la section Add specific display period.
   2. Indiquez le fuseau horaire ainsi que le début et la fin de la période.

   Pour ne pas définir de date de fin, activez la bascule No end date.

8. Configurez les attributs à l’aide de l’une des options suivantes (facultatif) :
   1. Ajouter des attributs et leurs valeurs au format JSON.
   2. Créer manuellement des attributs et leurs valeurs et les lier aux objets.

9. Appuyez Create.
10. Dans la fenêtre qui s’ouvre, sélectionnez le statut de l’objet et appuyez sur Continue.

L’objet créé apparaît dans la section All items.

Configuration via API

Pour rendre un objet gratuit, ajoutez “is_free”: true au 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 SKU
• 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 Si vous souhaitez limiter le nombre d’objets gratuits qu’un utilisateur peut recevoir, passez les paramètres suivants dans les appels de création ou de mise à jour de l’objet :
  • limits avec la quantité définie
  • limits.recurrent_schedule avec la fréquence de réinitialisation de la limite définie

Vous pouvez également configurer la limite de durée d’affichage de l’objet dans le magasin et définir des restrictions régionales.

Affichage des objets gratuits dans le catalogue

L’affichage des objets gratuits dans le catalogue dépend de la méthode dimplémentation : via le constructeur de site ou via l’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.

2. Ouvrez le projet dans votre compte pour les jeux mobiles et accédez à la section Web Shop.
3. Appuyez sur le volet du site souhaité.

4. Si votre site comporte plusieurs pages, sélectionnez celle dont vous avez besoin :
   1. Appuyez sur le titre de la page actuelle en haut de l’éditeur.
   2. Sélectionnez la page souhaitée dans la liste déroulante.
5. Dans la section Store, sélectionnez le type d’objet gratuit dans le champ Item type et, si nécessaire, indiquez son groupe..
6. Configurez une disposition de fiche d’objet.
7. Une fois les modifications terminées et votre site prêt à être lancé : 
   1. Appuyez sur Publish en haut à droite du constructeur de site.
   2. Cochez les pages à publier.
   3. Appuyez sur Publish.

Une fois le site publié, une section contenant les objets gratuits est disponible. Si les objets ne s’affichent pas, vérifiez que leur statut est défini sur Available et qu’aucune restriction d’affichage liée à la période n’est active.

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

Si votre catalogue est configuré via API, les données des objets gratuits sont renvoyées par les appels disponibles dans la sous-section Catalog :

• 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

Attribution des 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 passer par le panier, utilisez l’appel API Créer une commande à partir d’un objet gratuit spécifique.

Si l’utilisateur achète des objets via le panier, les scénarios suivants sont possibles :

• Si le panier de l’utilisateur contient des objets payants et gratuits, utilisez les appels 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 finalise 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 sur les objets utilisées pour accorder les objets à l’utilisateur. Pour les objets gratuits, le paramètre order.invoice_id dans le webhook est défini sur null.

Exemple d’ order 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 de distribution personnalisé, toute la monnaie virtuelle et tous les objets virtuels sont accordés de votre côté. Nous vous recommandons de configurer un gestionnaire de webhook pour recevoir les données de commande sur votre backend. Les données nécessaires sont incluses dans le webhook Paiement de commande réussi.

Pour en savoir plus sur cette méthode et les autres options de récupération des données d’achat, consultez la section Configurer le suivi du statut de la commande.