So nutzen Sie Pay Station in Kombination mit der PlayFab-Authentifizierung
Wenn Sie in Ihrer Anwendung bereits eine auf PlayFab beruhende Benutzerauthentifizierung implementiert haben, können Sie bei PlayFab einen Zahlungstoken generieren und ihn dann an den Anwendungs-Client übermitteln, um das Zahlungsportal zu öffnen.
Bei dieser Integrationsoption müssen Sie die Logik, gemäß der das Land des Nutzers und die entsprechende Zahlungswährung ermittelt wird, selbst implementieren.
Integrationsablauf:
- Registrieren Sie sich im Kundenportal, und erstellen Sie ein neues Projekt. Im weiteren Verlauf dieser Anleitung benötigen Sie die ID des erstellten Projekts.
- Katalog einrichten:
- Erstellen Sie einen Artikelkatalog bei Xsolla. Sie können Artikel manuell hinzufügen oder diese aus Google Play oder PlayFab importieren.
- Implementieren Sie mithilfe des SDK, dass der Artikelkatalog aufseiten des Anwendungs-Clients abgerufen und angezeigt wird.
- Artikelverkauf einrichten:
- Legen Sie mithilfe eines PlayFab-Cloud-Skripts eine Bestellung mit Nutzer- und Artikeldaten aufseiten des Anwendung-Clients an.
- Implementieren Sie mithilfe des SDK, dass das Zahlungsportal aufseiten des Anwendungs-Clients geöffnet wird.
Sie müssen die Xsolla-Lizenzvereinbarung unterzeichnen, um die Integration abzuschließen und echte Zahlungen entgegennehmen zu können.
Sie können die Lizenzvereinbarung jederzeit unterzeichnen. Denken Sie jedoch daran, dass die Prüfung bis zu drei Werktage dauern kann.
Projekt erstellen
Im Kundenportal registrieren
Das Kundenportal ist das wichtigste Tool für die Konfiguration der Xsolla-Funktionen und auch für die Arbeit mit Analytics und Transaktionen unerlässlich.
Die bei der Registrierung angegebenen Daten zu Ihrer Firma und zu Ihrer Anwendung dienen dazu, eine Entwurfsfassung der Xsolla-Lizenzvereinbarung zu erstellen und für Sie geeignete Lösungen vorzuschlagen. Sie können die Daten später ändern, allerdings verkürzt sich die Dauer bis zur Lizenzvereinbarungsunterzeichnung, wenn Sie bei der Registrierung korrekte Angaben machen.
Wechseln Sie zum Kundenportal, und erstellen Sie ein Konto, um sich zu registrieren.
Das Passwort für das Kundenportal darf Buchstaben, Ziffern und Sonderzeichen enthalten. Passwortanforderungen:
- mindestens 8 Zeichen lang
- mindestens eine Ziffer
- mindestens ein Großbuchstabe
- mindestens ein Kleinbuchstabe
Für eine optimale Passwortsicherheit empfehlen wir:
- das Passwort mindestens alle 90 Tage zu ändern
- ein neues Passwort zu vergeben, das nicht mit den letzten vier Passwörtern Ihres Kontos übereinstimmt
- ein einzigartiges Passwort zu vergeben, das Sie nirgendwo anders verwenden
- das Passwort nicht an einem Ort zu speichern, an dem es leicht zugänglich ist
- das Passwort in einem Passwortmanager zu speichern
Das Kundenportal verwendet die Zwei-Faktor-Authentifizierung und sendet bei jedem Authentifizierungsversuch einen Bestätigungscode.
Projekt im Kundenportal erstellen
Wenn Sie mehrere Anwendungen haben, empfehlen wir Ihnen, für jede Anwendung ein eigenes Projekt zu erstellen. Auf der Grundlage der bei der Projekterstellung angegebenen Daten generiert Xsolla Empfehlungen und schlägt für Sie geeignete Lösungen vor.
So erstellen Sie ein neues Projekt:
- Öffnen Sie das Kundenportal.
- Klicken Sie in der Seitenleiste auf Projekt erstellen.
- Vergeben Sie einen englischen Namen für Ihr Projekt (erforderlich).
- Wählen Sie eine oder mehrere Release-Plattformen für Ihr Spiel aus (erforderlich).
- Geben Sie einen Link zu Ihrem Spiel ein. Wenn Ihr Spiel noch keine Website hat, geben Sie einen Link zu einer Quelle ein, die Informationen über das Spiel enthält (erforderlich).
- Wählen Sie die Spiel-Engine aus.
- Wählen Sie die Monetarisierungsoptionen, die Sie verwenden oder planen zu verwenden.
- Geben Sie an, ob das Spiel bereits veröffentlicht wurde. Wenn das Spiel noch nicht veröffentlicht wurde, geben Sie den geplanten Release-Termin an.
- Klicken Sie auf Projekt erstellen.
Während des Integrationsprozesses benötigen Sie die Projekt-ID. Diese wird im Kundenportal neben dem Projektnamen angezeigt.
Katalog einrichten
Artikel im Kundenportal erstellen
Sie müssen einen Katalog bei Xsolla erstellen. Sie können Artikel manuell hinzufügen oder aus Google Play oder PlayFab importieren. Beim Import von Google Play können Sie maximal 100 Artikel auf einmal importieren.
In dieser Anleitung werden die grundlegenden Schritte zur Erstellung eines virtuellen Gegenstands erläutert. Später können Sie Ihrem Katalog weitere Artikel (virtuelle Währung, Bundles, Spielschlüssel) hinzufügen, Artikelgruppen erstellen, Werbekampagnen einrichten, regionale Preise festlegen usw.
So erstellen Sie einen virtuellen Gegenstand im Katalog:
- Öffnen Sie Ihr Projekt im Kundenportal.
- Klicken Sie in der Seitenleiste auf Store.
- Klicken Sie bei Virtuelle Gegenstände auf Verknüpfen.
- Wählen Sie in der Drop-down-Liste den Menüpunkt Artikel anlegen.
- Legen Sie die Grundeinstellungen des Artikels fest:
- Bild (optional)
- SKU (individuelle Artikel-ID)
- Gegenstandsname
- Beschreibung (optional)
- Legen Sie den Artikelpreis fest:
- Stellen Sie den Schalter Preise in echter Währung auf Ein.
- Im Feld Standard-Währung können Sie wahlweise die Währung ändern. Legen Sie den Artikelpreis fest.
- Sollten Sie die Währung im Feld Standard-Währung geändert haben, müssen Sie unter Preis in echter Währung dieselbe Währung auswählen.
- Ändern Sie den Artikelstatus in Verfügbar.
- Klicken Sie auf Artikel anlegen.
SDK installieren und einrichten
- Laden Sie den Epic Games Launcher herunter.
- Erstellen Sie ein neues Unreal Engine-Projekt.
- SDK herunterladen und installieren:
- So laden Sie das SDK vom Unreal Engine Marketplace herunter und installieren es:
- Wechseln Sie zur SDK-Seite auf dem Unreal Engine Marketplace.
- Klicken Sie auf
Open in Launcher .
- So laden Sie das SDK vom Unreal Engine Marketplace herunter und installieren es:
- Wechseln Sie zum Epic Games Launcher.
- Klicken Sie auf
Install to Engine . - Öffnen Sie Ihr Unreal Engine-Projekt in Unreal Editor.
- Navigieren Sie zu
Settings > Plugins > Installed > Xsolla SDK . Aktivieren Sie das KontrollkästchenEnabled , und klicken Sie aufRestart Now , um die Einstellungen zu speichern und Unreal Editor neu zu starten.
- Klicken Sie auf
- So laden Sie das SDK von GitHub herunter und installieren es:
- Laden Sie das Archiv mit dem SDK für Ihre Engine-Version herunter.
- Entpacken Sie das Archiv.
- Verschieben Sie den SDK-Ordner in das Verzeichnis
plugins
im Stammverzeichnis Ihres Unreal Engine-Projekts.
- So laden Sie das SDK von GitHub herunter und installieren es:
- Navigieren Sie zu
Settings > Project Settings > Plugins > Xsolla Settings > General . - Geben Sie im Feld
Project ID die Projekt-ID an. Diese wird im Kundenportal neben dem Namen Ihres Projekts angezeigt.
Katalog aufseiten des Anwendungs-Clients anzeigen
In dieser Anleitung wird die SDK-Methode GetVirtualItems
verwendet, um eine Liste der virtuellen Gegenstände abzurufen. Sie können Informationen über Katalogartikel auch mit anderen SDK-Methoden abrufen.
Wie Sie eine Katalogseite Schritt für Schritt erstellen, erfahren Sie unter Artikelkatalog anzeigen.
Klasse für Katalogartikel erstellen
- Navigieren Sie im
Content Browser zum VerzeichnisContent . - Rufen Sie das Kontextmenü auf, und wählen Sie
Blueprint Class aus.
- Wählen Sie im Abschnitt
All Classes die OptionObject aus, und klicken Sie aufSelect .
- Vergeben Sie
StoreItemData als Klassennamen. - Öffnen Sie den Blueprint der erstellten Klasse.
- Klicken Sie im
My Blueprint -Fenster aufAdd New , und wählen SieVariable aus. - Gehen Sie im
Details -Fenster wie folgt vor:
- Wählen Sie im Feld
Variable Type die OptionStoreItem aus. - Aktivieren Sie die Kontrollkästchen
Instance Editable undExpose on Spawn .
- Wählen Sie im Feld
- Speichern und schließen den Blueprint
StoreItemData .
Katalogartikel-Widget erstellen
- Navigieren Sie im
Content Browser zum VerzeichnisContent . Rufen Sie das Kontextmenü auf, und wählen SieUser Interface > Widget Blueprint aus. - Vergeben Sie
StoreItem als Blueprint-Namen. - Öffnen Sie den erstellten Blueprint.
- Rufen Sie im
Hierarchy -Fenster das Kontextmenü für das ElementCanvasPanel auf. Wählen SieReplace With > Overlay aus.
- Platzieren Sie die UI-Primitives aus dem
Palette -Fenster wie unten abgebildet. Für das Bild, den Titel und die Beschreibung eines Artikels müssen Sie das KontrollkästchenIs Variable imDetails -Fenster markieren.
- Öffnen Sie die
Graph -Anzeige. - Klicken Sie auf
Class settings . - Navigieren Sie im
Details -Fenster zuInterfaces > Implemented Interfaces . - Klicken Sie auf
Add , und wählen SieUserObjectListEntry aus. Dabei handelt es sich um eine standardmäßige UE-Benutzeroberfläche, die es dem UI-Primitive gestattet, ein für das Listenelement normales Verhalten zu implementieren.
- Fügen Sie die Logik für das Ereignis
OnListItemObjectSet
hinzu:- Rufen Sie im
My Blueprint -Fenster das Kontextmenü für den AbschnittInterfaces auf, und wählen SieImplement event aus.
- Rufen Sie im
- Fügen Sie die Knoten wie unten abgebildet hinzu:
- Speichern und schließen den Blueprint
StoreItem .
Widget für Katalogseite erstellen
- Navigieren Sie im
Content Browser zum VerzeichnisContent , und wählen Sie im KontextmenüUser Interface > Widget Blueprint aus. - Vergeben Sie
WBP_Store als Namen für den Blueprint. - Öffnen Sie den erstellten Blueprint.
- Fügen Sie im Artikelanzeigebereich das Element
List View hinzu, und vergeben SieStoreListView als Namen.
- Wählen Sie im
Details -Fenster im FeldEntry Widget Class die zuvor für den Artikel erstellte Klasse (StoreItem
) aus. - Wechseln Sie zur
Graph -Ansicht. - Binden Sie den SDK-Methodenaufruf
GetVirtualItems
an denEventConstruct
-Knoten, wie in der folgenden Abbildung gezeigt.
StoreItemData
erstellt, um das Objekt-Array korrekt zu übermitteln.- Klicken Sie im
My Blueprint -Fenster aufAdd New , und wählen SieVariable aus. - Gehen Sie im
Details -Fenster wie folgt vor:- Wählen Sie im Feld
Variable Type die OptionString aus. - Aktivieren Sie die Kontrollkästchen
Instance Editable undExpose on Spawn . - Vergeben Sie
PlayFabId als Namen.
- Wählen Sie im Feld
- Speichern und schließen Sie das
WBP_Store -Widget. - Für Sie eine Logik für die Verzeichnisanzeige hinzu. Nachfolgend sehen Sie ein Beispiel für die Implementierung der Verzeichnisanzeige nach erfolgreicher Benutzerauthentifizierung.
Artikelverkauf einrichten
Um eine Bestellung mit Nutzer- und Artikeldaten bei Xsolla anzulegen, müssen Sie das Projekt um eine Cloud-Funktion ergänzen, die den API-Aufruf Zahlungstoken für den Kauf erstellen verwendet. Dieser Aufruf gibt einen Zahlungstoken zurück. Dieser ist erforderlich, um das Zahlungsportal zu öffnen und einen Kauf zu tätigen.
Einschränkungen:
- Sie müssen entweder das Land des Nutzers oder die dessen IP-Adresse übermitteln, wenn Sie den Zahlungstoken anfordern.
- Wenn Sie keine Währung im Token angeben, bestimmt das Land die Währung.
- Wenn Sie die Währung im Token angeben, zahlt der Nutzer in dieser Währung.
Das PlayFab-Projekt sollte erstellt und das PlayFab-SDK bereits in Ihr Unity-Projekt integriert sein.
PlayFab CloudScripts unterstützt Funktionen mit HTTP-Triggern nur indirekt, daher wird Azure Functions genutzt, um den Empfang von Webhooks zu implementieren.
Sie müssen ein Azure-Konto erstellen und Ihre Entwicklungsumgebung vorbereiten, um Azure Functions nutzen zu können. Diese Anleitung beschreibt die Schritte in einer Entwicklungsumgebung mit den folgenden Einstellungen:
- Visual Studio Code ist installiert.
- Die Erweiterung für die Arbeit mit Azure Functions ist installiert.
Cloud-Skript Ihrem Projekt hinzufügen
- Öffnen Sie Visual Studio Code, und navigieren Sie zur Registerkarte
Azure . - Klicken Sie unter
Workspace auf das +-Symbol, und wählen SieCreate Function aus.
- Wählen Sie das neue Projektverzeichnis aus. Es erscheint ein Menü zum Erstellen eines neuen Projekts mit einer Auswahl an Einstellungen.
- Legen Sie die neuen Projekteinstellungen fest:
- Wählen Sie eine Sprache für Ihr Funktionsprojekt aus –
JavaScript . - Wählen Sie ein JavaScript-Programmiermodell aus –
model V4 . - Wählen Sie eine Vorlage für die erste Funktion Ihres Projekts aus –
HTTP trigger . - Vergeben Sie einen Funktionsnamen –
getXsollaPaymentToken
. - Wählen Sie aus, wie Ihr Projekt geöffnet werden soll –
Open in current window .
- Wählen Sie eine Sprache für Ihr Funktionsprojekt aus –
- Daraufhin generiert Visual Studio Code ein JS-Projekt und öffnet die generierte Datei
getXsollaPaymentToken.js
.
- Modifizieren Sie die Datei
getXsollaPaymentToken.js
:
- js
const { app } = require('@azure/functions');
const projectId = ""; //your xsolla project id from publisher account
const apiKey = ""; your api key from publisher account
app.http('getXsollaPaymentToken', {
methods: ['POST'],
authLevel: 'anonymous',
handler: async (request, context) => {
var body = await request.json();
const userId = body.uid;
const email = body.email;
const sku = body.sku;
const returnUrl = body.returnUrl;
if (!userId) {
return {status: 400, body: 'Request body is missing' };
}
const payload = {
user: {
id: {value: userId},
name: {
value: email
},
email: {
value: email
},
country: {
value: 'US',
allow_modify: false
}
},
purchase: {
items: [
{
sku: sku,
quantity: 1
}
]
},
sandbox: true,
settings: {
language: 'en',
currency: 'USD',
return_url: returnUrl,
ui: {
theme: '63295aab2e47fab76f7708e3'
}
}
}
let url = "https://store.xsolla.com/api/v2/project/" + projectId.toString() + "/admin/payment/token";
return fetch(
url,
{
method: "POST",
headers: {
'Content-Type': 'application/json',
Authorization: 'Basic ' + btoa(`${projectId}:${apiKey}`)
},
body: JSON.stringify(payload)
},
)
.then(xsollaRes => {
// Handle the response data
if (xsollaRes.ok) {
return xsollaRes.json();
} else {
return { status: 400, body: `HTTP request failed with error: ${xsollaRes.statusText}` };
}
})
.then(data => {
return { status: 200, body: JSON.stringify(data) };
})
.catch(error => {
return { status: 501, body: `Error = ${error}` };
});
}
});
- Geben Sie in dem Skript die Werte für die Konstanten an:
PROJECT_ID
– Projekt-ID, diese wird im Kundenportal neben dem Projektnamen angezeigt.
API_KEY
– 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
Nachdem Sie das Cloud-Skript hinzugefügt haben, können Sie den Aufruf der Funktion getXsollaPaymentToken
lokal testen.
Cloud-Skript bereitstellen
- Navigieren Sie in Visual Studio Code zu
Azure > Resources , und klicken Sie auf das +-Symbol. - Wählen Sie
Create Function App in Azure als Ressource aus. Es erscheint ein Menü zum Erstellen einer neuen Anwendung mit einer Auswahl an Einstellungen. - Legen Sie die Anwendungseinstellungen fest:
- Benennen Sie die neue Funktions-App –
XsollaFunctions
. - Wählen Sie einen Laufzeit-Stack aus –
.NET 8 Isolated . - Wählen Sie einen Ort für neue Ressourcen aus (Sie können eine beliebige Option auswählen).
- Benennen Sie die neue Funktions-App –
- Warten Sie, bis die Ressourcengruppe erstellt ist.
- Wählen Sie in der Liste der Ressourcen die Option
XsollaFunctions
aus, öffnen Sie das Kontextmenü, und wählen SieDeply to Function App aus.
Nachdem Sie das Cloud-Skript hinzugefügt haben, können Sie den Aufruf der Funktion getXsollaPaymentToken
remote testen.
Cloud-Skript testen
Rufen Sie die Funktion getXsollaPaymentToken
mit Postman oder einem anderen Tool auf, um das Cloud-Skript (lokal oder remote) zu testen. Gehen Sie dazu wie folgt vor:
- Navigieren Sie in Visual Studio Code zu
Azure > Workspace > Local Project > Functions , und klicken Sie aufStart debugging to update this list . - Öffnen Sie das Kontextmenü für die Funktion
, und wählen Sie
Copy Function Url aus. Erfolgt der Test lokal, sieht die URL wie folgt aus –http://localhost:7071/api/getXsollaPaymentToken
. Erfolgt der Test remote, sieht die URL wie folgt aus –https://xsollafunctions.azurewebsites.net/api/GetXsollaPaymentToken
.
- Verwenden Sie die kopierte URL, um die Funktion mit den angegebenen Parametern aufzurufen. So rufen Sie eine Funktion aus Postman auf:
- Erstellen Sie eine neue
GET
-Anfrage. - Geben Sie die in Schritt 2 kopierte URL an.
- Wechseln Sie zur Registerkarte
Body , und geben Sie die Anfrageparameter an.
- Erstellen Sie eine neue
Anfragerumpf (Beispiel):
- json
{
"FunctionArgument": {
"uid": "1D384D9EF12EAB8B",
"sku": "booster_max_1",
"returnUrl": "https://login.xsolla.com/api/blank"
}
}
uid
) angeben. Als Artikel-SKU (sku
) müssen Sie die SKU des virtuellen Gegenstands angeben, den Sie zuvor im Kundenportal hinzugefügt haben.- Klicken Sie auf
Send . Die Antwort sollte ein JSON mit den folgenden Parametern enthalten:token
– Zahlungstoken. Ist zum Öffnen des Zahlungsportals erforderlich.order_id
– ID der angelegten Bestellung. Ist zum Tracken des Bestellstatus erforderlich.
Antwortrumpf (Beispiel):
- json
{"token":"xsnpCF8tS4ox7quoibgTgPFVFxG9gTvS_lc_en_bg_2C2640_tb_6E7BF7","order_id":90288613}
Funktion für den Abruf eines Zahlungstokens in PlayFab registrieren
- Öffnen Sie Ihr Projekt in PlayFab.
- Klicken Sie in der Seitenleiste auf
Automation . - Klicken Sie unter
Register New Cloud Script Function aufRegister Function . - Benennen Sie die Funktion –
GetXsollaPaymentToken
. - Fügen Sie die Funktions-URL ein, die Sie in Visual Code Studio kopiert haben (siehe Schritte 1–2 unter Cloud-Skript testen).
Bestellung anlegen und Zahlungsportal im Unreal Engine-Projekt öffnen
- Öffnen Sie Ihr Unreal Engine-Projekt.
- Öffnen Sie das
WBP_Store -Widget. - Wählen Sie im
Hierarchy -Fenster die OptionStoreListView aus. - Klicken Sie im
Details -Fenster auf das +-Symbol neben dem EreignisOn Clicked .
- Wechseln Sie zur
Graph -Ansicht. - Fügen Sie eine Logik hinzu, gemäß der das
PlayfabJsonObject
-Objekt erstellt wird, und übermitteln Sie die Daten an dieses Objekt, um eine Bestellung amOnItemClicked
-Knoten anzulegen, wie unten abgebildet:
- Fügen Sie der Methode
ExecuteFunction
einen Aufruf hinzu. Übermitteln Sie beim dem Aufruf die ParameterfunctionName = getXsollaPaymentToken
undFunctionParameter = PlayfabJsonObject
.
Bestellstatus-Tracking einrichten
Der Bestellstatus muss getrackt werden, um sicherzustellen, dass die Zahlung erfolgreich war, und um dem Nutzer die entsprechenden Artikel zu gewähren.
Bestellstatus clientseitig abrufen
Tracken Sie den Bestellstatus mithilfe der SDK-Methode CheckPendingOrder
im Anwendungs-Client. Übermitteln Sie der Methode die folgenden Parameter:
AuthToken
– BenutzerauthentifizierungstokenOrderId
– Bestell-ID, erhalten beim Kauf über den Warenkorb, beim One-Click-Kauf oder beim Kauf gegen virtuelle WährungSuccessCallback
– Rückruf für den Fall, dass sich der Bestellstatus in “done” ändertErrorCallback
– Rückruf für den Fall, dass der Xsolla-Server einen Fehler meldet
Ausführliche Informationen dazu, wie die Methoden funktionieren, finden Sie im Abschnitt Bestellstatus tracken.
Bestellstatus serverseitig abrufen
Mit dem SDK können Sie den Bestellstatus aufseiten Ihres Anwendungs-Clients tracken. Wir empfehlen jedoch, einen Handler für den Zahlung-Webhook einzurichten, um Bestellinfos im Backend Ihrer Anwendung zu empfangen. Dadurch können sie zusätzlich prüfen, ob Käufe abgeschlossen sind.
Eine vollständige Liste der Webhooks und allgemeine Informationen zu deren Nutzungsmöglichkeiten finden Sie in der Webhooks-Dokumentation.
So konfigurieren Sie Webhooks bei Xsolla:
- Öffnen Sie Ihr Projekt im Kundenportal.
- Klicken Sie in der Seitenleiste auf Projekteinstellungen, und navigieren Sie zur Registerkarte Webhooks.
- Geben Sie im Feld Webhook-Server die URL ein, an die Xsolla die Webhooks senden soll.
Webhooks können Sie auch über eine beliebige spezialisierte Website (z. B. webhook.site) oder Plattform (z. B. ngrok) testen.
Zu Testzwecken können Sie auch ein Cloud-Skript hinzufügen, das eine erfolgreiche Webhook-Verarbeitung simuliert. Der Skriptcode ist auf GitHub verfügbar.
Für ein echtes Projekt müssen Sie eine Kaufvalidierungslogik hinzufügen.
- Kopieren und speichern Sie den Wert aus dem Feld Geheimer Schlüssel. Dieser Schlüssel wird standardmäßig generiert und dient dazu, Webhooks zu signieren. Wenn Sie ihn ändern möchten, klicken Sie auf das Aktualisieren-Symbol.
- Klicken Sie auf Webhooks aktivieren.
Haben Sie einen Tippfehler oder einen anderen Textfehler gefunden? Wählen Sie den Text aus und drücken Sie Strg+Eingabe.