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 Bezahlstation für Client-API-Methoden nutzen.
So aktivieren Sie Spielerinventar:
- Richten Sie den Xsolla-Ingame-Online-Shop 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 (Consume item) 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 Bezahlstation, 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 Bezahlstation 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:
- Registrieren (JWT oder OAuth 2.0)
- Authentifizierung (eine der folgenden Optionen):
- Passwort zurücksetzen
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 Bezahlstation
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 Xsolla-API-Inventar wird die Basisauthentifizierung genutzt. Alle Anfragen an die API müssen im Header Authorization: Basic <your_authorization_basic_key>
enthalten, wobei <your_authorization_basic_key>
dem, gemäß Base64-Standard, kodierten merchant_id:api_key
-Paar entspricht.
Navigieren Sie zum Xsolla-Kundenportal, um die Werte der project_id- und api_key-Parameter zu erhalten:
- project_id: Projekteinstellungen > Webhooks
- api_key: Firmeneinstellungen > API-Schlüssel
- 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
// if you use Xsolla SDK for PHP
use Xsolla\SDK\API\XsollaClient;
$xsollaClient = XsollaClient::factory(array(
'project_id' => PROJECT_ID,
'api_key' => API_KEY
));
$eventsList = $client->ListEvents(array());
// if you don’t use Xsolla SDK for PHP
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://store.xsolla.com/api/v2/project/{project_id}/inventory/rewards');
$request->setRequestMethod('POST');
$request->setHeaders(array(
'authorization' => 'Basic <your_authorization_basic_key>'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
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:
Grant items to users
Implementieren Sie die API-Methode Grant items to users, 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
}
]
}
]
}
Grant items by purchase to users
Implementieren Sie die API-Methode Grant items by purchase to users, 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"
}
]
}
Get user’s inventory
Implementieren Sie die API-Methode Get user’s inventory, 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"
}
]
}
Get user’s virtual balance
Implementieren Sie die API-Methode Get user’s virtual balance, 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"
}
]
}
Consume Item
Implementieren Sie die API-Methode Consume item, 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. | - |
Fehler bei der Gegenstandsverwaltung:
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-Kunden-Support oder Ihren Account Manager. |
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.