Biens gratuits

Comment ça marche

Les biens gratuits sont un type de biens que l’utilisateur peut obtenir sans dépenser de la monnaie virtuelle ou de devises réelles. Il peut s’agir de :

• Objets virtuels ;
• Lots ;
• Packages de monnaie virtuelle.

Les biens gratuits ne sont disponibles que pour les utilisateurs autorisés. Les utilisateurs non autorisés peuvent uniquement consulter le catalogue des biens gratuits.

Exemples d’utilisation :

• Vous pouvez offrir des biens gratuits à des dates importantes pour votre projet (par exemple, le jour où le projet a été créé) afin de récompenser les utilisateurs pour leur fidélité.
• Vous pouvez distribuer des kits de démarrage gratuits pour le jeu dans le magasin afin d’attirer de nouveaux utilisateurs sur le jeu.

Vous pouvez limiter la distribution gratuite d’objets uniques si l’utilisateur les possède déjà.

Qui peut l'utiliser

• Les partenaires qui ont déjà In-Game Store et qui souhaitent créer un nouveau type de produit : les biens gratuits.
• Les partenaires qui souhaitent fidéliser leurs utilisateurs actuels ou attirer de nouveaux joueurs.

Flux d'intégration

1. Créez des biens gratuits de la manière suivante :
   • dans le Compte éditeur ;
   • via appels API.
2. Configurez Store.
3. Obtenez le statut de la commande de l'utilisateur.

Création dans le Compte éditeur

1. Ouvrez votre projet dans le Compte éditeur.
2. Dans le menu latéral, cliquez sur Store.
3. Dans le volet Virtual Items, cliquez sur Configure.
4. Cliquez sur + et choisissez Create item dans la liste déroulante.
5. Spécifiez :
   • l’image ;
   • l’UGS ;
   • Un ou plusieurs groupes auxquels l’objet doit appartenir ;
   • le nom ;
   • la description ;
   • la propriété de l’objet : consommable, non consommable ou objet à durée limitée.
6. Dans le bloc Price settings, choisissez Free item.
7. Si vous souhaitez limiter la disponibilité des objets à des utilisateurs spécifiques, réglez la bascule Limit number of times one user can buy this item sur On et spécifiez le nombre.
8. Si vous souhaitez afficher l’objet dans le magasin, réglez la bascule Show item in store sur On.
9. Cliquez sur Create item.

Création via appels API

1. Pour créer des biens gratuits, utilisez les appels API de la sous-section Administrateur :
   • Pour les objets virtuels — Créer un objet virtuel ;
   • Pour les packages de monnaie — Créer un package de monnaie virtuelle ;
   • Pour les lots — Créer un lot.
   Lorsque vous créez ou modifiez un bien, passez is_free = true dans le corps de la requête.
2. Si vous souhaitez limiter la disponibilité des biens à des utilisateurs spécifiques, appelez n'importe quelle méthode API de création ou de modification d'un bien et spécifiez la valeur du paramètre limits.per_user.

Configurer Store

Achat rapide

{
  "method": "POST",
  "url": "https://mybestgame.com/xsolla/notification",
  "body": {
    "items": [
      {
        "sku": "gift_direct_game_reward-supercoin",
        "type": "virtual_currency",
        "is_pre_order": false,
        "quantity": 500,
        "amount": "0",
        "promotions": [

        ]
      },
      {
        "sku": "package-500_supercoin",
        "type": "bundle",
        "is_pre_order": false,
        "quantity": 1,
        "amount": "0",
        "promotions": [

        ]
      },
      {
        "sku": "xsolla-giveaway_offer_11_14_22",
        "type": "bundle",
        "is_pre_order": false,
        "quantity": 1,
        "amount": "0",
        "promotions": [

        ]
      }
    ],
    "notification_type": "order_paid",
    "order": {
      "id": 12345678,
      "mode": "default",
      "currency_type": "unknown",
      "currency": null,
      "amount": "0",
      "status": "paid",
      "platform": "xsolla",
      "comment": null,
      "invoice_id": null,
      "promotions": [

      ]
    },
    "user": {
      "external_id": "1234567812345678",
      "email": null
    }
  },
  "headers": {
    "Authorization": "Signature 3b840ccefea111dcdfd111db1fdc6df969a3ec11",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "type": "webhook_payment",
  "callback_parameters": {
    "order_id": 12345678
  }
}

• Si votre écouteur a correctement accepté et traité le webhook — code de réponse HTTP 200 ou 204.
• Si l’erreur attendue se produit — code de réponse HTTP 4xx.
Note
Dans ce cas, les biens sont ajoutés à l’inventaire du joueur et la commande est marquée comme réussie côté de Xsolla.
• Votre écouteur peut également renvoyer un code de réponse HTTP 5xx en cas d'erreurs temporaires sur votre serveur. Dans ce cas, le service d'alerte Xsolla utilise un mécanisme de relance.

Achat via le panier

Si l’utilisateur utilise le panier :

• Si le panier de l’utilisateur contient à la fois des biens payants et gratuits, utilisez les appels API standard Créer une commande à partir de tous les objets d’un panier spécifique et Créer une commande à partir de tous les objets du panier actuel pour créer des commandes. L’utilisateur paiera la commande au moyen du formulaire de paiement de Pay Station.
• Si le panier de l’utilisateur ne contient que des biens gratuits, utilisez les appels API Create order with free cart et Créer une commande à partir d’un panier gratuit spécifique pour récupérer le panier gratuit. Dans ce cas, l’interface de paiement ne sera pas utilisée.

L’exemple du webhook est similaire à celui de l’achat rapide.