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 :
- Configurez Xsolla In-game Store.
- Configurez l’authentification.
- 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 :
- Si vous avez connecté Xsolla Login, utilisez Xsolla Login JWT pour authentifier les requêtes.
- Si vous avez configuré votre propre système d’identification, utilisez le jeton d’accès Pay Station pour authentifier les requêtes.
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
- Configurez un projet de Compte éditeur en suivant les instructions.
- 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 :
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 :
- Votre application (client) envoie la requête d’authentification à votre serveur.
- Votre serveur envoie l’ID du commerçant et la clé API au serveur Xsolla et demande access_token.
- Le serveur Xsolla envoie access_token à votre serveur.
- Votre serveur envoie access_token à votre client.
access_token renvoyé est utilisé comme jeton d’autorisation pour l’authentification dans l’interface
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.
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.
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 :
- Méthodes serveur :
- Méthodes client :
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 :
- php
<?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 :
- php
{
"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 :
- php
<?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 :
- php
{
"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 :
- php
<?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 :
- php
{
"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
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 :
- js
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 :
- js
{
"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
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 :
- js
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 :
- js
{
"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
Implémentez la méthode API Consume item pour consommer un objet de l’inventaire utilisateur.
Requête :
- js
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 :Code | Description | Action |
---|---|---|
0401-5002 | Donné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-5003 | ID utilisateur non spécifié. | Vérifier la présence de l’ID utilisateur dans la requête. |
0401-5004 | Objets 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-5006 | Monnaie virtuelle non suffisante pour l’achat. | - |
0401-5007 | Tentative de consommation d’un objet non consommable. | - |
0401-5008 | Utilisateur non trouvé. | - |
0401-5009 | Lors de l’octroi de l’achat effectué sur une plateforme tierce, purchase n’a pas été passé. | - |
Code | Description | Action |
---|---|---|
0401-4001 | Objet non trouvé selon les critères. | Vérifier la liste des objets en appelant la méthode Get user’s inventory. |
Code | Description | Action |
---|---|---|
0401-1101 | Service 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-1102 | Données d’entrée de la requête erronées. | Vérifier la spécification API. |
0401-1016 | Mauvais encodage d’un des paramètres de la requête. | Vérifier le contenu de la requête. |
0401-1019 | Méthode non prise en charge. | Vérifier la requête. Les méthodes prises en charge se trouvent dans la réponse. |
0401-1020 | Erreur d’autorisation lors de l’utilisation du hachage de la clé du commerçant. | Vérifier la clé API. |
Faute de frappe ou autre erreur dans le texte ? Sélectionnez le texte concerné et appuyez sur Ctrl+Entée.