Activer Player Inventory

L’inventaire est l’ensemble des objets du jeu que l’utilisateur peut acheter, gagner ou dépenser.

Xsolla Player Inventory permet aux partenaires de :

  • Synchroniser tous les achats et toutes les récompenses premium de l’utilisateur sur toutes les plateformes.
  • Utiliser l’API Xsolla pour ajouter des objets et de la monnaie à l’inventaire utilisateur ainsi que de les y retirer.

Player Inventory permet de gérer l’inventaire utilisateur en fonction de l’ID utilisateur. L’ID utilisateur est implémenté par le biais de Xsolla Login. Si vous avez configuré votre propre système d’identification, utilisez le jeton d’accès Pay Station pour les méthodes API client.

Pour activer Player Inventory :

  1. Configurez Xsolla In-game Store.
  2. Configurez l’authentification.
  3. Implémentez les méthodes de gestion de l’inventaire.

Configuration de l'authentification

Afin de garantir la sécurité, les méthodes d’octroi et de révocation sont appelées par le serveur de jeu. Il est nécessaire d’implémenter l’authentification d’accès de base pour les méthodes mentionnées ci-dessus.

Les méthodes permettant de récupérer l’inventaire utilisateur et de consommer des objets sont appelées côté client du jeu via le SDK ou l’API. Voici les options d’authentification possibles :

  1. Si vous avez connecté Xsolla Login, utilisez Xsolla Login JWT pour authentifier les requêtes.
  2. Si vous avez configuré votre propre système d’identification, utilisez le jeton d’accès Pay Station pour authentifier les requêtes.

Note
Si vous utilisez votre propre méthode d’identification utilisateur, passez user.id aux méthodes serveur d’octroi et de révocation des objets. Il doit être identique au user.id que vous utilisez pour le jeton d’accès Pay Station.

Authentification via Xsolla Login

  1. Configurez un projet de Compte éditeur en suivant les instructions.
  2. Implémentez l'appel aux méthodes d'autorisation à l'aide du JSON Web Token ou du protocole OAuth 2.0.

Si le stockage des données utilisateur est Xsolla, implémentez l’appel aux méthodes suivantes :

Note
Pour appeler les API de Xsolla, vous pouvez utiliser les méthodes SDK prêtes à l’emploi pour les moteurs de jeu et les plateformes :

Si le stockage des données utilisateur est PlayFab, utilisez la recette PlayFab.

Si les données de l’utilisateur sont conservées de votre côté, utilisez la recette stockage personnalisé.

Authentification par jeton d'accès Pay Station

Flux d’authentification :

  1. Votre application (client) envoie la requête d’authentification à votre serveur.
  2. Votre serveur envoie l’ID du commerçant et la clé API au serveur Xsolla et demande access_token.
  3. Le serveur Xsolla envoie access_token à votre serveur.
  4. Votre serveur envoie access_token à votre client.

access_token renvoyé est utilisé comme jeton d’autorisation pour l’authentification dans l’interface Commerce API et la création d’un magasin.

Configurer l'authentification d'accès de base

Les commandes serveur pour ajouter des objets à l’inventaire et de les y retirer à l’aide de l’API Xsolla utilisent l’authentification d’accès de base. Toutes les requêtes adressées à l’API doivent contenir l’en-tête Authorization: Basic <your_authorization_basic_key>, où <your_authorization_basic_key> est la paire merchant ID:API key encodée selon la norme Base64.

Accédez au Compte éditeur pour trouver ces paramètres :

  • 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>/<Publisher Account section>.

  • 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.
Avis

Pour plus d’informations sur l’utilisation des clés API, consultez la référence API.

Recommandations principales :

  • Enregistrez la clé API générée de votre côté. Lors de sa création dans le Compte éditeur, la clé API ne s’affiche qu’une seule fois.
  • Gardez votre clé API secrète. Elle donne accès à votre compte personnel et à vos projets dans le Compte éditeur.
  • Stockez la clé API sur votre serveur et non dans des fichiers binaires ou sur le client.

Copy
Full screen
Small screen

http

  • http
  • curl
  • php
  • C#
  • python
  • ruby
  • java
  • js
POST https://store.xsolla.com/api/v2/project/{project_id}/inventory/reward
Headers:
  Authorization: Basic <your_authorization_basic_key>
curl --request POST \
--url 'https://store.xsolla.com/api/v2/project/{project_id}/inventory/reward' \
--header 'authorization: Basic <your_authorization_basic_key>'
<?php

$uri = 'https://store.xsolla.com/api/v2/project/{project_id}/inventory/reward';

$auth = base64_encode('your_merchant_id:your_merchant_api_key');

$headers = [
    'Authorization: Basic ' . $auth,
    'Content-Type: application/json',
    'Accept: application/json',
];

$request = curl_init($uri);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_POST, true);
curl_setopt($request, CURLOPT_POSTFIELDS, []);
curl_setopt($request, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($request);
print_r($response);
var client = new RestClient("https://store.xsolla.com/api/v2/project/{project_id}/inventory/reward");
var request = new RestRequest(Method.POST);
request.AddHeader("authorization", "Basic <your_authorization_basic_key>");
IRestResponse response = client.Execute(request);
import http.client

conn = http.client.HTTPSConnection("api.xsolla.com")

headers = { 'authorization': "Basic <your_authorization_basic_key>" }

conn.request("POST", "https://store.xsolla.com/api/v2/project/{project_id}/inventory/reward", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
require 'uri'
require 'net/http'

url = URI("https://store.xsolla.com/api/v2/project/{project_id}/inventory/reward
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Basic <your_authorization_basic_key>'

response = http.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://store.xsolla.com/api/v2/project/{project_id}/inventory/reward")
  .post()
  .addHeader("authorization", "Basic <your_authorization_basic_key>")
  .build();

Response response = client.newCall(request).execute();
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://store.xsolla.com/api/v2/project/{project_id}/inventory/reward");
xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");

xhr.send(data);

Méthodes de gestion de l'inventaire

Les méthodes de gestion de l’inventaire comprennent les groupes de méthodes suivants :

Grant items to users

Implémentez la méthode API Grant items to users pour ajouter l’objet spécifié à l’inventaire de l’utilisateur ou de la monnaie virtuelle à son solde.

Requête :

Copy
Full screen
Small screen
<?php
$uri = 'https://store.xsolla.com/api/v2/project/44056/inventory/reward';
$body = '
    [
        {
          "user": {
            "id": "0125760a-6810-11e9-84c0-42010aa80029"
          },
          "comment": "Quest completed",
          "platform": "xsolla",
          "items": [
            {
              "sku": "boots_1",
              "quantity": 5
            },
            {
              "sku": "crystal_pack_1",
              "quantity": 3
            }
          ]
        },
        {
          "user": {
            "id": "a7d10a4e-3f68-43cc-a6b2-893d2c68fd14"
          },
          "comment": "Daily reward",
          "platform": "xsolla",
          "items": [
            {
              "sku": "helmet_1",
              "quantity": 2
            },
            {
              "sku": "minigun_1",
              "quantity": 3
            }
          ]
        }
    ]';

$auth = base64_encode('44056:your_merchant_api_key');

$headers = [
    'Authorization: Basic ' . $auth,
    'Content-type: application/json'
];

$request = curl_init($uri);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_POSTFIELDS, $body);
curl_setopt($request, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($request);

Réponse :

Copy
Full screen
Small screen
{
    "count": 2,
    "operations": [
        {
            "user_id": "0125760a-6810-11e9-84c0-42010aa80029",
            "platform": "xsolla",
            "comment": "Quest completed",
            "items": [
                {
                    "sku": "boots_1",
                    "quantity": 5
                },
                {
                    "sku": "crystal_pack_1",
                    "quantity": 3
                }
            ]
        },
        {
            "user_id": "a7d10a4e-3f68-43cc-a6b2-893d2c68fd14",
            "platform": "xsolla",
            "comment": "Daily reward",
            "items": [
                {
                    "sku": "helmet_1",
                    "quantity": 2
                },
                {
                    "sku": "minigun_1",
                    "quantity": 3
                }
            ]
        }
  ]
}

Revoke inventory items

Implémentez la méthode API Revoke inventory items pour retirer l’objet spécifié de l’inventaire de l’utilisateur ou de la monnaie virtuelle de son solde.

Requête :

Copy
Full screen
Small screen
<?php
$uri = 'https://store.xsolla.com/api/v2/project/44056/inventory/revoke';
$body = '
    [
        {
          "user": {
            "id": "0125760a-6810-11e9-84c0-42010aa80029"
          },
          "comment": "Remove from inventory",        
          "items": [
            {
              "sku": "boots_1",
              "quantity": 5
            },
            {
              "sku": "crystal_pack_1",
              "quantity": 3
            }
          ]
        },
        {
          "user": {
            "id": "a7d10a4e-3f68-43cc-a6b2-893d2c68fd14"
          },
          "comment": "Cheater",
          "items": [
            {
              "sku": "helmet_1",
              "quantity": 2
            },
            {
              "sku": "minigun_1",
              "quantity": 3
            }
          ]
        }
    ]';

$auth = base64_encode('44056:your_merchant_api_key');

$headers = [
    'Authorization: Basic ' . $auth,
    'Content-type: application/json'
];

$request = curl_init($uri);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_POSTFIELDS, $body);
curl_setopt($request, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($request);
print_r($response);

Réponse :

Copy
Full screen
Small screen
{
    "count": 2,
    "operations": [
        {
            "user_id": "0125760a-6810-11e9-84c0-42010aa80029",
            "platform": "xsolla",
            "comment": "Remove from inventory",
            "items": [
                {
                    "sku": "boots_1",
                    "quantity": 5
                },
                {
                    "sku": "crystal_pack_1",
                    "quantity": 3
                }
            ]
        },
        {
            "user_id": "a7d10a4e-3f68-43cc-a6b2-893d2c68fd14",
            "platform": "xsolla",
            "comment": "Cheater",
            "items": [
                {
                    "sku": "helmet_1",
                    "quantity": 2
                },
                {
                    "sku": "minigun_1",
                    "quantity": 3
                }
            ]
        }
    ]
}

Grant items by purchase to users

Implémentez la méthode API Grant items by purchase to users pour ajouter un objet à l’inventaire de l’utilisateur lorsque l’achat est effectué sur une plateforme tierce.

Requête :

Copy
Full screen
Small screen
<?php
$uri = 'https://store.xsolla.com/api/v2/project/44056/inventory/purchase';
$body = '
    [
        {
          "user": {
            "id": "0125760a-6810-11e9-84c0-42010aa80029"
          },
          "comment": "Purchase in App Store",
          "platform": "app_store_ios",
          "purchase": {
            "amount": "3.99",
            "currency": "USD",
            "external_purchase_id": "MS6TGW7023",
            "external_purchase_date": "2020-01-25T05:00:00+05:00"
          },        
          "items": [
            {
              "sku": "boots_1",
              "quantity": 5
            },
            {
              "sku": "crystal_pack_1",
              "quantity": 3
            }
          ]
        },
        {
          "user": {
            "id": "a7d10a4e-3f68-43cc-a6b2-893d2c68fd14"
          },
          "comment": "Purchase in Google Play",
          "platform": "google_play",
          "purchase": {
            "amount": "1.99",
            "currency": "EUR",
            "external_purchase_id": "GPA.3357-9348-5932-89841",
            "external_purchase_date": "2020-02-14T05:00:00+05:00"
          },
          "items": [
            {
              "sku": "helmet_1",
              "quantity": 2
            },
            {
              "sku": "minigun_1",
              "quantity": 3
            }
          ]
        }
    ]';

$auth = base64_encode('44056:your_merchant_api_key');

$headers = [
    'Authorization: Basic ' . $auth,
    'Content-type: application/json'
];

$request = curl_init($uri);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_POSTFIELDS, $body);
curl_setopt($request, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($request);
print_r($response);

Réponse :

Copy
Full screen
Small screen

{
    "count": 2,
  "operations": [
    {
      "user_id": "0125760a-6810-11e9-84c0-42010aa80029",
      "platform": "app_store_ios",
      "comment": "Purchase in App Store",
      "items": [
        {
          "sku": "boots_1",
          "quantity": 5
        },
        {
          "sku": "crystal_pack_1",
          "quantity": 3
        }
      ],
      "order_id": 4125,
      "external_purchase_id": "MS6TGW7023",
      "external_purchase_date": "2020-01-25T05:00:00+05:00",
      "amount": "3.99",
      "currency": "USD"
    },
    {
      "user_id": "a7d10a4e-3f68-43cc-a6b2-893d2c68fd14",
      "platform": "google_play",
      "comment": "Purchase in Google Play",
      "items": [
        {
            "sku": "helmet_1",
          "quantity": 2
        },
        {
            "sku": "minigun_1",
          "quantity": 3
        }
      ],
      "order_id": 4126,
      "external_purchase_id": "GPA.3357-9348-5932-89841",
      "external_purchase_date": "2020-02-14T05:00:00+05:00",
      "amount": "1.99",
      "currency": "EUR"
    }
  ]
}

Get user’s inventory

Note
Pour appeler les API de Xsolla, vous pouvez utiliser les méthodes SDK prêtes à l’emploi pour les moteurs de jeu et les plateformes :

Implémentez la méthode API Get user’s inventory pour obtenir la liste des objets ajoutés à l’inventaire utilisateur après l’achat.

Requête :

Copy
Full screen
Small screen
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/user/inventory/items");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");

xhr.send(data);

Réponse :

Copy
Full screen
Small screen
{
  "items": [
    {
      "description": "Conquer your foes with vindication using the Basic Blaster! ",
      "image_url": "https://cdn.xsolla.net/img/misc/images/0c59a7698d4f66c1008b27ee752089b7.png",
      "instance_id": null,
      "long_description": "Conquer your foes with vindication using the Basic Blaster! Conquer your foes with vindication using the Basic Blaster! ",
      "name": "Xsolla Basic Blaster 1",
      "quantity": 22,
      "sku": "gun_1",
      "type": "virtual_good"
    },
    {
      "description": "Protect your noggin' with style",
      "image_url": "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png",
      "instance_id": null,
      "long_description": "merchant_virtual_items_virtual_item_long_description_159429",
      "name": "Xsolla Helmet",
      "quantity": 18,
      "sku": "helmet_1",
      "type": "virtual_good"
    }
  ]
}

Get user’s virtual balance

Note
Pour appeler les API de Xsolla, vous pouvez utiliser les méthodes SDK prêtes à l’emploi pour les moteurs de jeu et les plateformes :

Implémentez la méthode API Get user’s virtual balance pour obtenir des informations sur le solde actuel de la monnaie virtuelle de l’utilisateur.

Requête :

Copy
Full screen
Small screen
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
    if (this.readyState === this.DONE) {
        console.log(this.responseText);
    }
});
xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/user/virtual_currency_balance");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");
xhr.send(data);

Réponse :

Copy
Full screen
Small screen

{
  "items": [
    {
      "amount": 683,
      "description": "Main in-game currency",
      "image_url": "https://cdn3.xsolla.com/img/misc/images/91df536af4616519f639664854c13d75.png",
      "name": "Crystals",
      "sku": "crystal",
      "type": "virtual_currency"
    },
    {
      "amount": 450,
      "description": "Money for in-store purchases",
      "image_url": "https://cdn3.xsolla.com/img/misc/images/fda67a3feedaa706b4e4ae05a9edd6ab.png",
      "name": "Gold",
      "sku": "gold",
      "type": "virtual_currency"
    }
  ]
}

Consume item

Note
Pour appeler les API de Xsolla, vous pouvez utiliser les méthodes SDK prêtes à l’emploi pour les moteurs de jeu et les plateformes :

Implémentez la méthode API Consume item pour consommer un objet de l’inventaire utilisateur.

Requête :

Copy
Full screen
Small screen
let data = JSON.stringify({
  "sku": "gun_1",
  "quantity": 1,
  "instance_id": null
});

let xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://store.xsolla.com/api/v2/project/44056/user/inventory/item/consume");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");

xhr.send(data);

Liste des erreurs

Erreurs de gestion de l’utilisateur ou de l’inventaire utilisateur :
CodeDescriptionAction
0401-5002Données, passées pour l’ajout de l’objet à l’inventaire utilisateur, erronées.item_id doit être spécifié, tandis que instance_id ou la quantité doivent être définis sur la valeur null.
0401-5003ID utilisateur non spécifié.Vérifier la présence de l’ID utilisateur dans la requête.
0401-5004Objets non trouvés dans l’inventaire utilisateur.S’assurer que l’objet se trouve dans l’inventaire. L’état de l’inventaire est vérifié via la méthode Get user’s inventory.
0401-5006Monnaie virtuelle non suffisante pour l’achat.-
0401-5007Tentative de consommation d’un objet non consommable.-
0401-5008Utilisateur non trouvé.-
0401-5009Lors de l’octroi de l’achat effectué sur une plateforme tierce, purchase n’a pas été passé.-
Erreurs de gestion des objets :
CodeDescriptionAction
0401-4001Objet non trouvé selon les critères.Vérifier la liste des objets en appelant la méthode Get user’s inventory.
Erreurs de gestion de Commerce API :
CodeDescriptionAction
0401-1101Service non disponible (mauvaise adresse, problèmes de connexion).Vérifier l’état du système à l’adresse status.xsolla.com ; contacter l’équipe du service client Xsolla, votre responsable de la réussite client ou envoyer un e-mail à csm@xsolla.com.
0401-1102Données d’entrée de la requête erronées.Vérifier la spécification API.
0401-1016Mauvais encodage d’un des paramètres de la requête.Vérifier le contenu de la requête.
0401-1019Méthode non prise en charge.Vérifier la requête. Les méthodes prises en charge se trouvent dans la réponse.
0401-1020Erreur d’autorisation lors de l’utilisation du hachage de la clé du commerçant.Vérifier la clé API.
Votre progression
Merci pour votre commentaire !
Dernière mise à jour: 22 Janvier 2024

Faute de frappe ou autre erreur dans le texte ? Sélectionnez le texte concerné et appuyez sur Ctrl+Entée.

Signaler un problème
Nous améliorons continuellement notre contenu grâce à vos commentaires.
Indiquez votre adresse e-mail pour un suivi
Merci pour votre commentaire !