So nutzen Sie Pay Station in Kombination mit der Firebase-Authentifizierung
Wenn Sie in Ihrer Anwendung bereits eine auf Firebase beruhende Benutzerauthentifizierung implementiert haben, können Sie bei Firebase 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 der
Store -Bibliothek, dass der Artikelkatalog aufseiten des Anwendungs-Clients abgerufen und angezeigt wird.
- Artikelverkauf einrichten:
- Legen Sie mithilfe der Funktionen der Firebase-Cloud eine Bestellung mit Nutzer- und Artikeldaten aufseiten des Anwendung-Clients an.
- Implementieren Sie mithilfe der
Payments -Bibliothek, 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.
Auf GitHub finden Sie den Quellcode einer Browseranwendung als Beispiel. Damit können Sie den kombinierten Einsatz der Firebase-Authentifizierung und Pay Station probeweise implementieren.
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.
Katalog aufseiten des Anwendungs-Clients anzeigen
- Fügen Sie Ihrem Projekt die
Store -Bibliothek hinzu. Öffnen Sie dazubuild.gradle
, und fügen Sie folgende Zeilen im Abschnitt Abhängigkeiten hinzu:
implementation("com.xsolla.android:store:latest.release")
- Erstellen Sie aufseiten des Anwendungs-Clients eine Benutzeroberfläche, auf der der Produktkatalog angezeigt werden kann.
- Implementieren Sie, dass der Artikelkatalog von Xsolla-Servern abgerufen wird.
XStore.getVirtualItems
eine Liste virtueller Gegenstände abgerufen. Sie können Informationen über Katalogartikel auch mit anderen Methoden der Beispiel (Klasse
- kotlin
package com.xsolla.androidsample
import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.widget.Toast
import androidx.recyclerview.widget.LinearLayoutManager
import androidx.recyclerview.widget.RecyclerView
import com.xsolla.android.store.XStore
import com.xsolla.android.store.callbacks.GetVirtualItemsCallback
import com.xsolla.android.store.entity.response.items.VirtualItemsResponse
import com.xsolla.androidsample.adapter.BuyItemAdapter
class StoreActivity : AppCompatActivity() {
private lateinit var itemsView: RecyclerView
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_store)
XStore.init(<projectId>)
initUI()
loadVirtualItems()
}
private fun initUI() {
itemsView = findViewById(R.id.buy_recycler_view)
itemsView.layoutManager = LinearLayoutManager(this)
}
private fun loadVirtualItems() {
val parentActivity = this
XStore.getVirtualItems(object : GetVirtualItemsCallback {
override fun onSuccess(response: VirtualItemsResponse) {
itemsView.adapter = BuyItemAdapter(parentActivity, response.items.filter { item -> item.virtualPrices.isEmpty() && !item.isFree })
}
override fun onError(throwable: Throwable?, errorMessage: String?) {
showNotificationMessage(errorMessage ?: throwable?.javaClass?.name ?: "Error")
}
})
}
private fun showNotificationMessage(message: String) {
Toast.makeText(
baseContext,
message,
Toast.LENGTH_SHORT,
).show()
}
}
Geben Sie in XStore.init()
, dem Initialisierungsblock des Skripts, die Projekt-ID an, diese wird im Kundenportal neben dem Projektnamen angezeigt.
Artikelverkauf einrichten
Bestellung mithilfe der Cloud-Funktion anlegen
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.
So erweitern Sie ein Projekt um eine Cloud-Funktion:
- Installieren Sie das Firebase-CLI (Command-Line Interface). Führen Sie dazu den folgenden CLI-Befehl aus:
npm install -g firebase-tools
- Um Ihr Projekt mit dem Firebase-Projekt zu verknüpfen, müssen Sie das Firebase-Projekt mit dem folgenden CLI-Befehl initialisieren:
firebase init functions
- Folgen Sie den Installationsanweisungen, um die Einstellungen zu konfigurieren:
- Wählen Sie eine vorhandene Codebasis.
- Wählen Sie JavaScript als Sprache für die Erstellung von Cloud-Funktionen.
- Installieren Sie Abhängigkeiten.
- Öffnen Sie
functions/index.js
, und modifizieren Sie die Datei:
- javascript
// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const functions = require('firebase-functions/v1');
const projectId = <projectId>;
const apiKey = <apiKey>;
exports.getXsollaPaymentToken = functions.https.onRequest((req, res) => {
const requestBody = req.body;
if (!requestBody) {
res.status(400).send('Request body is missing');
return;
}
const userId = requestBody.data.uid;
const email = requestBody.data.email;
const sku = requestBody.data.sku;
const returnUrl = requestBody.data.returnUrl;
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/v3/project/" + projectId.toString() + "/admin/payment/token";
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 {
throw new Error(`HTTP request failed with status ${xsollaRes.status} and statusText: ${xsollaRes.statusText}`)
}
})
.then(data => {
res.send(JSON.stringify(data));
})
.catch(error => {
res.send("Error = " + error);
});
});
exports.webhookFakeResponse = functions.https.onRequest((request, response) => {
response.status(200).send()
})
- Geben Sie in dem Skript die Werte für die folgenden Variablen an:
projectId
– Projekt-ID, diese wird im Kundenportal neben dem Projektnamen angezeigt.
apiKey
– 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
- Führen Sie den folgenden CLI-Befehl aus, um die Cloud-Funktion mit dem Emulator zu testen:
firebase emulators:start
- Nachdem Sie die Cloud-Funktion ausgeführt haben, können Sie die folgenden Methoden aufseiten des Anwendungs-Clients aufrufen:
getXsollaPaymentToken
– gibt den Zahlungstoken für das Öffnen des Zahlungsportals zurück.webhookFakeResponse
– sendet den HTTP-Statuscode200
als Antwort auf den Zahlung-Webhook. Die Methode enthält keine Kaufvalidierungslogik und dient daher nur zu Testzwecken. Eine vollständige Liste der Webhooks und allgemeine Informationen zu deren Nutzungsmöglichkeiten finden Sie in der Webhooks-Dokumentation.
- Über die beiden URLs
https://localhost:5001/{firebase-project-id}/us-central1/getXsollaPaymentToken
undhttps://localhost:5001/{firebase-project-id}/us-central1/webhookFakeResponse
können Sie Methoden lokal aufrufen, wobei{firebase-project-id}
die Firebase-Projekt-ID ist (Firebase Console > Projekteinstellungen > Projekt-ID).
- Führen Sie den folgenden CLI-Befehl aus, um die Cloud-Funktion produktivzusetzen:
firebase deploy --only functions
- Einmal produktivgesetzt, können Sie die Methoden über die beiden URLs
https://us-central1-{firebase-project-id}.cloudfunctions.net/getXsollaPaymentToken
undhttps://us-central1-{firebase-project-id}.cloudfunctions.net/webhookFakeResponse
aufrufen, wobei{firebase-project-id}
die Firebase-Projekt-ID (Firebase Console > Projekteinstellungen > Projekt-ID). Wie Sie die Funktion in der Produktionsumgebung ausführen, erfahren Sie in der Firebase-Dokumentation.
Zahlungsportal-Start einrichten
- Fügen Sie Ihrem Projekt die
Payments -Bibliothek hinzu. Öffnen Sie dazubuild.gradle
, und fügen Sie folgende Zeilen im Abschnitt Abhängigkeiten hinzu:
implementation("com.xsolla.android:payments:latest.release")
- Öffnen Sie
AndroidManifest.xml
, und ergänzen Sie eine Berechtigung für den Internetzugang:
- xml
<uses-permission android:name="android.permission.INTERNET" />
- Fügen Sie die Logik hinzu, gemäß der eine Bestellung angelegt (Aufruf der Cloud-Funktionsmethode
XStore.getXsollaPaymentToken
) und das Zahlungsportal mit dem erhaltenen Zahlungstoken geöffnet wird (Klasse:XPayments.createIntentBuilder()
).
- Beim Aufruf der Methode
getXsollaPaymentToken
müssen Sie eine der folgenden URLs angeben, wobei{firebase-project-id}
die Firebase-Projekt-ID ist (Firebase Console > Projekteinstellungen > Projekt-ID):- beim lokalen Zugriff –
https://localhost:5001/{firebase-project-id}/us-central1/getXsollaPaymentToken
- beim Zugriff in der Produktionsumgebung –
https://us-central1-{firebase-project-id}.cloudfunctions.net/getXsollaPaymentToken
- beim lokalen Zugriff –
Beispiel (Klasse
- kotlin
package com.xsolla.androidsample.adapter
import android.R.attr.duration
import android.os.Handler
import android.os.Looper
import android.view.LayoutInflater
import android.view.ViewGroup
import android.widget.Toast
import androidx.recyclerview.widget.RecyclerView
import com.bumptech.glide.Glide
import com.xsolla.android.payments.XPayments
import com.xsolla.android.payments.data.AccessToken
import com.xsolla.android.store.entity.response.items.VirtualItemsResponse
import com.xsolla.androidsample.R
import com.xsolla.androidsample.StoreActivity
import org.json.JSONObject
import java.io.BufferedReader
import java.io.BufferedWriter
import java.io.OutputStream
import java.io.OutputStreamWriter
import java.net.HttpURLConnection
import java.net.URL
class BuyItemAdapter(private val parentActivity: StoreActivity, private val items: List<VirtualItemsResponse.Item>) :
RecyclerView.Adapter<BuyItemViewHolder>() {
override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): BuyItemViewHolder {
return BuyItemViewHolder( LayoutInflater.from(parent.context)
.inflate(R.layout.buy_item_sample, parent, false))
}
override fun onBindViewHolder(holder: BuyItemViewHolder, position: Int) {
val item = items[position]
Glide.with(holder.view).load(item.imageUrl).into(holder.itemImage)
holder.itemName.text = item.name
holder.itemDescription.text = item.description
var priceText: String
if(item.virtualPrices.isNotEmpty()) {
priceText = item.virtualPrices[0].getAmountRaw() + " " + item.virtualPrices[0].name
} else {
priceText = item.price?.getAmountRaw() + " " + item.price?.currency.toString()
}
holder.itemPrice.text = priceText
holder.itemButton.setOnClickListener {
Thread {
purchase(item.sku!!)
}.start()
}
}
private fun purchase(sku: String) {
val uid = parentActivity.intent.getStringExtra("uid")
val email = parentActivity.intent.getStringExtra("email")
val jsonBody = JSONObject()
jsonBody.put("data", JSONObject().apply {
put("uid", uid)
put("email", email)
put("sku", sku)
put("returnUrl", "app://xpayment." + parentActivity.packageName)
})
val connection = URL(https://localhost:5001/{firebase-project-id}/us-central1/getXsollaPaymentToken).openConnection() as HttpURLConnection
connection.requestMethod = "POST"
connection.setRequestProperty("Content-Type", "application/json")
connection.doOutput = true
val outputStream: OutputStream = connection.outputStream
val writer = BufferedWriter(OutputStreamWriter(outputStream))
writer.write(jsonBody.toString())
writer.flush()
writer.close()
val responseCode = connection.responseCode
if (responseCode == HttpURLConnection.HTTP_OK) {
val response = connection.inputStream.bufferedReader().use(BufferedReader::readText)
connection.disconnect()
val jsonObject = JSONObject(response)
val token = jsonObject.getString("token")
val orderId = jsonObject.getString("order_id")
val intent = XPayments.createIntentBuilder(parentActivity)
.accessToken(AccessToken(token))
.isSandbox(true)
.build()
parentActivity.startActivityForResult(intent, 1)
} else {
Handler(Looper.getMainLooper()).post {
showNotificationMessage("HTTP request failed with error: $responseCode")
}
}
}
override fun getItemCount() = items.size
private fun showNotificationMessage(message: String) {
Toast.makeText(
parentActivity,
message,
Toast.LENGTH_SHORT,
).show()
}
}
- Fügen Sie die Methode
onActivityResult()
hinzu, um das Zahlungsergebnis zu verarbeiten.
Beispiel (Klasse
- kotlin
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
if (requestCode == 1) {
val (status, _) = XPayments.Result.fromResultIntent(data)
when (status) {
XPayments.Status.COMPLETED -> showNotificationMessage("Payment completed")
XPayments.Status.CANCELLED -> showNotificationMessage("Payment canceled")
XPayments.Status.UNKNOWN -> showNotificationMessage("Payment error")
}
}
}
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
Rufen Sie die Methode XStore.getOrderStatus
auf, und übermitteln Sie die folgenden Parameter, um Bestellstatusänderungen aufseiten des Anwendungs-Clients zu abonnieren:
listener
– Listener-Objekt vom TypOrderStatusListener
.orderId
– Bestell-ID, die beim Kauf über die Warenkorbfunktion, beim One-Click-Kauf oder beim Kauf gegen virtuelle Währung empfangen wurde.
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.
Für Testzwecke können Sie https://us-central1-{firebase-project-id}.cloudfunctions.net/webhookFakeResponse
angeben, wobei {firebase-project-id}
die Firebase-Projekt-ID ist (Firebase Console > Projekteinstellungen > Projekt-ID). In diesem Fall simuliert Firebase die erfolgreiche Verarbeitung eines Webhooks. Für ein echtes Projekt müssen Sie eine Kaufvalidierungslogik hinzufügen.
Webhooks können Sie auch über eine beliebige spezialisierte Website (z. B. webhook.site) oder Plattform (z. B. ngrok) testen.
- 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.