Spielerinventar aktivieren
Das Inventar umfasst alle Gegenstände des Spiels, die sich kaufen, verdienen oder ausgeben lassen.
Xsolla-Spielerinventar ermöglicht Partnern folgendes:
- Synchronisierung sämtlicher Käufe und Premium-Belohnungen des Benutzers auf allen Plattformen.
- Nutzung der Xsolla-API zum Gewähren oder Widerrufen von Gegenständen und Währung im Inventar des Benutzers.
Mithilfe des Features “Spielerinventar” lassen sich die Inventare von Benutzern anhand deren ID verwalten. Die Benutzeridentifikation wird über Xsolla Login implementiert. Wenn Sie Ihr eigenes Identifikationssystem konfiguriert haben, können Sie den Zugriffstoken der Pay Station für Client-API-Methoden nutzen.
So aktivieren Sie Spielerinventar:
- Richten Sie den Xsolla-In-Game-Store ein.
- Konfigurieren Sie die Authentifizierung.
- Implementieren Sie die Methoden für die Inventarverwaltung.
Authentifizierungseinrichtung
Aus Sicherheitsgründen werden die Methoden zum Gewähren (Granting) und Widerrufen (Revoking) vom Spielserver aufgerufen. Für die zuvor genannten Methoden ist die Implementierung der Basisauthentifizierung erforderlich.
Die Methoden zum Abrufen der Benutzerinventars (Get the user’s inventory) und zum Verbrauchen von Gegenständen (Artikel verbrauchen) werden durch den Spiel-Client via SDK oder API aufgerufen. Die möglichen Authentifizierungsoptionen lauten wie folgt:
- Wenn Sie Xsolla Login verknüpft haben, nutzen Sie den Xsolla Login-JWT, um Anfragen zu authentifizieren.
- Wenn Sie Ihr eigenes Identifikationssystem eingerichtet haben, nutzen Sie den Zugriffstoken der Pay Station, um Anfragen zu authentifizieren.
user.id
an die serverbasierten Methoden zum Gewähren und Widerrufen von Gegenständen. Sie sollte mit der von Ihnen für den Zugriffstoken der Pay Station genutzten user.id
übereinstimmen.Authentifizierung über Xsolla Login
- Richten Sie ein Projekt im Kundenportal ein. Befolgen Sie dabei die Anweisungen.
- Implementieren Sie den Aufruf der Autorisierungsmethoden mithilfe des JSON-Web-Tokens oder OAuth 2.0-Protokolls
Wenn die Nutzerdaten bei Xsolla hinterlegt sind, implementieren Sie den Aufruf der folgenden Methoden:
Sind die Nutzerdaten bei PlayFab hinterlegt, nutzen Sie die PlayFab-Anleitung.
Sind die Nutzerdaten bei Ihnen hinterlegt, nutzen Sie die Anleitung Kundenseitiger Speicherort.
Authentifizierung über den Zugriffstoken der Pay Station
Authentifizierungsablauf:
- Ihre Anwendung (Client) sendet die Authentifizierungsanfrage an Ihren Server.
- Ihr Server sendet die Händler-ID und den API-Schlüssel an den Xsolla-Server und fragt den access_token an.
- Der Xsolla-Server sendet den access_token an Ihren Server.
- Ihr Server sendet den access_token an Ihren Client.
Der empfangene access_token wird als Autorisierungstoken zur Authentifizierung in der
Basisauthentifizierung einrichten
Für die Serverbefehle zum Gewähren und Widerrufen von Gegenständen aus dem Inventar nutzt die Xsolla-API die Basisauthentifizierung. Alle Anfragen an die API müssen den Header Authorization: Basic <your_authorization_basic_key>
enthalten, wobei <your_authorization_basic_key>
das gemäß dem Base64-Standard, kodierte Paar Händler-ID:API-Schlüssel ist.
Diese Parameter finden Sie im Kundenportal:
- Die Händler-ID finden Sie:
- unter Firmeneinstellungen > Firma.
- in der URL in der Adresszeile des Browsers auf einer beliebigen Seite im Kundenportal. Die URL weist das folgende Format auf:
https://publisher.xsolla.com/<merchant ID>/<Publisher Account section>
.
- Der API-Schlüssel wird im Kundenportal nur einmal angezeigt, nämlich dann, wenn er erstellt wird. Sie sind selbst dafür verantwortlich, den Schlüssel zu speichern. Einen neuen Schlüssel können Sie in den folgenden Abschnitten erstellen:
- Firmeneinstellungen > API-Schlüssel
- Projekteinstellungen > API-Schlüssel
Weitere Informationen über die Arbeit mit API-Schlüsseln finden Sie in der API-Referenz.
Wichtige Empfehlungen:
- Sie sind selbst dafür verantwortlich, den generierten API-Schlüssel zu speichern. Der API-Schlüssel wird im Kundenportal nur einmal angezeigt, nämlich dann, wenn er erstellt wird.
- Halten Sie Ihren API-Schlüssel geheim. Er gewährt den Zugang zu Ihrem persönlichen Konto und Ihren Projekten im Kundenportal.
- Der API-Schlüssel muss auf Ihrem Server gespeichert sein, niemals in Binärdateien oder im Frontend.
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);
Methoden zur Inventarverwaltung
Methoden zur Inventarverwaltung umfassen die folgenden Gruppen von Methoden:
- Server-Methoden:
- Client-Methoden:
Benutzern Artikel gewähren
Implementieren Sie die API-Methode Benutzern Artikel gewähren, um bestimmte Gegenstände zum Inventar des Benutzers bzw. virtuelle Währung zu dessen Guthaben hinzuzufügen.
Anfrage:
- 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);
Antwort:
- 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
Implementieren Sie die API-Methode Revoke inventory items, um bestimmte Gegenstände aus dem Inventar des Benutzers bzw. virtuelle Währung von dessen Guthaben zu entfernen.
Anfrage:
- 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);
Antwort:
- 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
}
]
}
]
}
Benutzern gekaufte Artikel gewähren
Implementieren Sie die API-Methode Benutzern gekaufte Artikel gewähren, um den Gegenstand zum Inventar des Benutzers hinzuzufügen, wenn der Kauf auf der Plattform eines Drittanbieters erfolgt.
Anfrage:
- 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);
Antwort:
- 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"
}
]
}
Inventar des aktuellen Benutzers abrufen
Implementieren Sie die API-Methode Inventar des aktuellen Benutzers abrufen, um die Liste der Gegenstände, die nach dem Kauf zum Benutzerinventar hinzugefügt wurden, abzurufen.
Anfrage:
- 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);
Antwort:
- 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"
}
]
}
Virtuelles Guthaben des aktuellen Benutzers abrufen
Implementieren Sie die API-Methode Virtuelles Guthaben des aktuellen Benutzers abrufen, um Informationen über das derzeitige virtuelle Währungsguthaben des Benutzers abzurufen.
Anfrage:
- 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);
Antwort:
- 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"
}
]
}
Artikel aufbrauchen
Implementieren Sie die API-Methode Artikel verbrauchen, um das Verbrauchen des Gegenstand aus dem Inventar des Benutzers zu ermöglichen.
Anfrage:
- 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);
Fehlerliste
Fehler bei der Verwaltung des Benutzerinventars:Code | Beschreibung | Aktion |
---|---|---|
0401-5002 | Die Daten zum Hinzufügen des Gegenstands in das Benutzerinventar sind falsch. | item_id muss angegeben sein und instance_id oder quantity muss den Wert null aufweisen. |
0401-5003 | Keine Benutzer-ID angegeben. | Prüfen Sie, ob die Benutzer-ID in der Anfrage enthalten ist. |
0401-5004 | Gegenstände wurden nicht im Inventar des Benutzers gefunden. | Der Gegenstand muss im Inventar vorliegen. Der Inventarstatus lässt sich mithilfe der Methode Get user’s inventory prüfen. |
0401-5006 | Nicht genug virtuelle Währung für den Kauf. | - |
0401-5007 | Es wurde versucht, einen aufbrauchbaren Gegenstand zu verbrauchen. | - |
0401-5008 | Benutzer nicht gefunden. | - |
0401-5009 | purchase beim Gewähren des Kaufs von Drittanbieter-Plattform nicht übermittelt. | - |
Code | Beschreibung | Aktion |
---|---|---|
0401-4001 | Gegenstand anhand von Kriterien nicht gefunden. | Prüfen Sie die Liste der Gegenstände. Rufen Sie dazu die Methode Get user’s inventory auf. |
Code | Beschreibung | Aktion |
---|---|---|
0401-1101 | Dienst nicht verfügbar (falsche Adresse, Verbindungsprobleme). | Prüfen Sie den Systemstatus unter status.xsolla.com; wenden Sie sich an den Xsolla-Kundensupport, an Ihren Customer Success Manager oder senden Sie eine E-Mail an csm@xsolla.com. |
0401-1102 | Eingegebene Anfragedaten sind falsch. | Prüfen Sie die API-Spezifikation. |
0401-1016 | Falsche Kodierung eines der Anfrageparameter. | Prüfen Sie den Inhalt der Anfrage. |
0401-1019 | Methode nicht unterstützt. | Prüfen Sie die Anfrage. Unterstützte Methoden befinden sich in der Antwort. |
0401-1020 | Autorisierungsfehler bei der Verwendung des Schlüssel-Hashes des Händlers. | Prüfen Sie den API-Schlüssel. |
Haben Sie einen Tippfehler oder einen anderen Textfehler gefunden? Wählen Sie den Text aus und drücken Sie Strg+Eingabe.