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 via des clés de jeu

Cas d’utilisation :

• Objets gratuits offerts lors de jalons du projet ou à des dates spéciales, comme un anniversaire, pour récompenser la fidélité des utilisateurs.
• Extensions gratuites pour les utilisateurs ayant déjà acheté le jeu de base, en guise de récompense de fidélité.
• Packs de démarrage gratuits disponibles dans la boutique 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 autorisés. Les clés de jeu gratuites sont disponibles pour les utilisateurs autorisés et non autorisés. Vous ne pouvez configurer les limites sur le nombre d’objets gratuits que pour les utilisateurs autorisés.

Configurer les objets gratuits

2. Cliquez sur Create manually et sélectionnez Virtual items dans la liste déroulante.

3. Dans la section General settings, indiquez les éléments suivants :
   1. SKU
   2. Un ou plusieurs groupes auxquels l’objet doit appartenir (facultatif)
   3. Nom
   4. Description courte
   5. Description détaillée — pour l’ajouter, activez la bascule correspondante (facultatif)

4. Dans la section Media, téléchargez une ou plusieurs images ou vidéos (facultatif) — depuis votre appareil ou via un lien. Dans le magasin créé avec l’éditeur de site Xsolla, toutes les fiches d’objet affichent le fichier marqué Main, tandis que les autres fichiers ne sont disponibles que dans celles qui incluent 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 d’affichage de l’objet dans le magasin.
      5. No regular refresh.
   3. Définissez le planning de réinitialisation en précisant les paramètres correspondant à la période sélectionnée.

7. Pour configurer une durée d’affichage limitée pour 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 laisser la fin de la période d’affichage indéfinie, 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. Cliquez sur Create.
10. Dans la fenêtre qui s’ouvre, sélectionnez le statut de l’objet et cliquez sur Continue.

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

Configurer via l’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 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, transmettez 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 durée d’affichage de l’objet dans le magasin et définir des restrictions régionales.

Afficher les objets gratuits dans le catalogue

Les objets gratuits s’affichent dans le catalogue selon la méthode d’implémentation — via le Site Builder ou via l’API.

Afficher via le Site Builder

Pour afficher les objets gratuits sur le site web :

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

   

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

4. Si votre site comporte plusieurs pages, sélectionnez celle dont vous avez besoin :
   1. Cliquez 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, dans le champ Item type, sélectionnez le type d’objet gratuit et, le cas échéant, indiquez son groupe.
6. Configurez une disposition de fiche d’objet.
7. Après avoir effectué tous les changements nécessaires et préparé votre site pour le lancement :
   1. Dans l’angle supérieur droit du builder, cliquez sur Publish.
   2. Cochez les cases en face des pages à publier.
   3. Cliquez sur Publish.

Une fois le site publié, une section contenant des objets gratuits sera disponible. Si les objets n’apparaissent pas, vérifiez que leur statut est défini sur Available et qu’aucune limite d’affichage basée sur le temps n’est active.

Obtenir les informations sur les objets gratuits via l’API

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

• Get virtual items list
• Get virtual currency list
• Get virtual currency packages list
• Get bundles list
• Get games list

Accorder 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 utiliser le panier, utilisez l’appel API Create order with specified free item.

Si l’utilisateur achète des objets en utilisant 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 Create order with all items from particular cart ou Create order with all items from current cart. 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 Create order with free cart ou Create order with particular free cart. Dans ce cas, l’interface de paiement n’est pas utilisée.

  Dans les deux cas, Xsolla envoie le webhook Successful payment for order contenant 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’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 sont automatiquement ajoutés à l’inventaire PlayFab de l’utilisateur.
• Si vous utilisez un système de livraison personnalisé, toutes les monnaies 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 Successful payment for order. Reportez-vous à la section Configurer le suivi du statut de la commande pour plus de détails sur ce point et sur d’autres options de récupération des données d’achat.