SDK aufseiten der Anwendung integrieren

Allgemeine Informationen

1. Gestalten Sie eine Benutzeroberfläche für das Anmeldesystem, den Ingame-Shop und sonstige Seiten Ihrer Anwendung.
2. Implementieren Sie mithilfe von SDK-Methoden in Ihrer Anwendung eine Logik für die Benutzerauthentifizierung, die Shop-Anzeige, den Kaufvorgang und mehr.

Schnellstart

Nachfolgend ist schrittweise erläutert, wie sich das Szenario eines Ingame-Kaufs am einfachsten implementieren lässt.

Interaktionsablauf:

1. Der Nutzer startet das Spiel.
2. Die Anwendung startet das Xsolla-Login-Web-Widget.
3. Der Nutzer meldet sich beim Spiel an und wechselt in den Artikelkatalog.
4. Die Anwendung fordert den Artikelkatalog von Xsolla an.
5. Nachdem die Artikeldaten erfolgreich empfangen wurden, zeigt die Anwendung den Artikelkatalog an.
6. Der Nutzer klickt bei dem gewünschten Artikel auf die Kaufen-Schaltfläche.
7. Die Anwendung initiiert den Kaufvorgang und zeigt das Zahlungsportal im Browser an.
8. Der Nutzer zahlt.
9. Die Anwendung schließt das Zahlungsportal und übermittelt die Zahlungsdaten an Xsolla.
10. Die Anwendung schreibt die Ergebnisse der Zahlungsabwicklung in das Protokoll.

Sequenzdiagramm für die Interaktion zwischen Ihrer Anwendung (Skript StoreController) und dem SDK:

Szenariobeschränkungen:

• Das fertige Xsolla-Login-Web-Widget wird für die Benutzerautorisierung verwendet. Xsolla stellt standardmäßige Widget-Vorlagen bereit. Deren Optik und Inhalte sind durch die für Ihr Projekt gewählte Anmeldemethode und die Widget-Anpassungseinstellungen im Kundenportal bestimmt.

• In diesem Szenario werden Artikel nur gegen echte Währung verkauft, ohne Verwendung eines Warenkorbs, d. h., der Nutzer kann nur einen Artikel kaufen.

Artikel-Widget-Skript erstellen

Erstellen Sie ein neues Skript namens VirtualItemWidget:

1. Öffnen Sie Ihr Projekt im Unity-Editor.
2. Navigieren Sie im Hauptmenü zu Assets > Create > C# Script.
3. Vergeben Sie der neuen Datei im Ordner Assets den Namen VirtualItemWidget.
4. Öffnen Sie die erstellte Datei im Editor, und fügen Sie den folgenden Code ein:

using UnityEngine;
using UnityEngine.UI;

namespace Xsolla.Example
{
    public class VirtualItemWidget : MonoBehaviour
    {
       public Image IconImage;
       public Text NameText;
       public Text DescriptionText;
       public Text PriceText;
       public Button BuyButton;
    }
}

5. Speichern Sie die Änderungen.

Prefab für Artikel-Widget erstellen

Gestalten Sie die Benutzeroberfläche (UI) für die Anzeige eines Artikels im Shop:

1. Erstellen Sie ein Canvas-Objekt für die Anzeige von UI-Elementen. Navigieren Sie dazu im Hauptmenü zu GameObject > UI > Canvas. Daraufhin werden die folgenden Objekte in der Szene erstellt:
   • Das Objekt Canvas mitsamt den Komponenten Canvas, Canvas Scaler und Graphic Raycaster.
   • Das Objekt EventSystem, sofern ein solches Objekt in der Szene noch nicht existiert.
2. Erstellen Sie das untergeordnete Objekt VirtualItemWidget:
   1. Wählen Sie im Hierarchy-Fenster das Canvas-Objekt aus.
   2. Navigieren Sie im Hauptmenü zu GameObject > UI > Image. Daraufhin wird ein neues Spielobjekt erstellt, hierbei handelt es sich um ein untergeordnetes Objekt von Canvas.
   3. Benennen Sie das erstellte Objekt in VirtualItemWidget um.
3. Fügen Sie UI-Objekte für die Anzeige von Artikelinformationen hinzu:
   1. Erstellen Sie ein Objekt für die Anzeige des Widget-Symbols:
      1. Wählen Sie im Hierarchy-Fenster das VirtualItemWidget-Objekt aus.
      2. Navigieren Sie im Hauptmenü zu GameObject > UI > Image.
      3. Benennen Sie das erstellte Objekt in IconImage um.
   2. Erstellen Sie ein Objekt für die Anzeige des Artikelnamens:
      1. Wählen Sie im Hierarchy-Fenster das VirtualItemWidget-Objekt aus.
      2. Navigieren Sie im Hauptmenü zu GameObject > UI > Legacy > Text.
      3. Benennen Sie das erstellte Objekt in NameText um.
   3. Erstellen Sie ein Objekt für die Anzeige der Artikelbeschreibung:
      1. Wählen Sie im Hierarchy-Fenster das VirtualItemWidget-Objekt aus.
      2. Navigieren Sie im Hauptmenü zu GameObject > UI > Legacy > Text.
      3. Benennen Sie das erstellte Objekt in DescriptionText um.
   4. Erstellen Sie ein Objekt für die Schaltfläche, über die der Artikel gekauft werden kann.
      1. Wählen Sie im Hierarchy-Fenster das VirtualItemWidget-Objekt aus.
      2. Navigieren Sie im Hauptmenü zu GameObject > UI > Legacy > Button. Daraufhin wird ein Schaltflächen-Objekt mitsamt dem untergeordneten Objekt Text erstellt.
      3. Benennen Sie das erstellte Objekt in BuyButton um.
      4. Benennen Sie das Objekt Text in PriceText um.
4. Fügen Sie das Artikel-Widget-Skript dem Objekt VirtualItemWidget als Komponente hinzu:
   1. Wählen Sie im Hierarchy-Fenster das VirtualItemWidget-Objekt aus.
   2. Klicken Sie im Inspector-Fenster auf Add Component, und wählen Sie das Skript VirtualItemWidget aus.
5. Weisen Sie den entsprechenden Skript-Slots die UI-Elemente zu:
   1. Wählen Sie im Hierarchy-Fenster das VirtualItemWidget-Objekt aus.
   2. Ziehen Sie die untergeordneten UI-Objekte per Drag-and-drop aus dem Hierarchy-Fenster ins Inspector-Fenster, und legen Sie die Elemente auf den entsprechenden Slots der Komponente VirtualItemWidget ab.
6. Konvertieren Sie das erstellte VirtualItemWidget-Objekt in ein Prefab:
   1. Wählen Sie im Hierarchy-Fenster das VirtualItemWidget-Objekt aus.
   2. Ziehen Sie das Objekt per Drag-and-drop in das Project-Fenster im Ordner Assets. Daraufhin erscheint ein neues Objekt im Ordner Assets, und das Objekt in der Szene ändert seine Farbe in Blau.

Prefab für das Artikel-Widget (Beispiel):

Shop-Skript erstellen

Erstellen Sie ein neues Skript namens StoreController:

1. Öffnen Sie Ihr Projekt im Unity-Editor.
2. Navigieren Sie im Hauptmenü zu Assets > Create > C# Script.
3. Vergeben Sie der neuen Datei im Ordner Assets den Namen StoreController.
4. Öffnen Sie die erstellte Datei im Editor, und fügen Sie den folgenden Code ein:

using System.Linq;
using UnityEngine;
using Xsolla.Auth;
using Xsolla.Catalog;
using Xsolla.Core;
namespace Xsolla.Example
{
	public class StoreController : MonoBehaviour
	{
		[SerializeField] private VirtualItemWidget WidgetPrefab;
		[SerializeField] private Transform WidgetsContainer;
		private void Start()
		{
			StartAuthorization();
		}
		private void StartAuthorization()
		{
			Debug.Log("Start the authorization process with the Xsolla Login Widget");
			XsollaAuth.AuthWithXsollaWidget(OnAuthSuccess, OnError, null);
		}
		private void OnAuthSuccess()
		{
			Debug.Log("Authorization successful");
			Debug.Log("Get the catalog of virtual items");
			XsollaCatalog.GetItems(OnCatalogReceived, OnError);
		}
		private void OnCatalogReceived(StoreItems items)
		{
			Debug.Log("Catalog received successfully");
			BuildStoreUI(items.items);
		}
		private void BuildStoreUI(StoreItem[] items)
		{
			// Create a widget for each item in the catalog
			foreach (var item in items)
			{
				// Check if the item has a price for real money. If not, skip the item (e.g., it is a virtual currency)
				if (item.price == null)
					continue;
				// Instantiate a widget prefab
				var widget = Instantiate(WidgetPrefab, WidgetsContainer, false);
				// Fill the widget with data
				widget.NameText.text = item.name;
				widget.DescriptionText.text = item.description;
				widget.PriceText.text = $"{item.price.amount} {item.price.currency}";
				// Loading the item image and assigning it to the UI element
				ImageLoader.LoadSprite(item.image_url, sprite => widget.IconImage.sprite = sprite);
				// Add a click listener to the Buy button
				widget.BuyButton.onClick.AddListener(() => StartPurchase(item.sku));
			}
		}
		private void StartPurchase(string sku)
		{
			Debug.Log($"Start the purchase process for the item: {sku}");
			XsollaCatalog.Purchase(sku, OnPurchaseCompleted, OnError);
		}
		private void OnPurchaseCompleted(OrderStatus status)
		{
			Debug.Log("Purchase completed");
		}
		private void OnError(Error error)
		{
			Debug.LogError($"Error message: {error.errorMessage}");
		}
	}
}

5. Speichern Sie die Änderungen.

Shop-Objekt erstellen

Erstellen Sie die Benutzeroberfläche für die Anzeige einer Artikelliste im Shop:

1. Fügen Sie eine Komponente hinzu, die die Widgets einzelner Artikel in einem Raster anordnet und die Position und Größe verschachtelter Objekte steuert. Gehen Sie dazu wie folgt vor:
   1. Wählen Sie im Hierarchy-Fenster das Canvas-Objekt aus.
   2. Klicken Sie im Inspector-Fenster auf Add Component, und wählen Sie das Skript Grid Layout Group aus.
   3. Ändern Sie im Inspector-Fenster bei Bedarf die Komponenteneinstellungen: Legen Sie die Zellengröße, den Abstand usw. fest.

2. Fügen Sie das Shop-Skript dem Objekt Canvas als Komponente hinzu:
   1. Wählen Sie im Hierarchy-Fenster das Canvas-Objekt aus.
   2. Klicken Sie im Inspector-Fenster auf Add Component, und wählen Sie das Skript StoreController aus.
3. Weisen Sie den entsprechenden Slots des Skripts StoreController die Elemente zu:
   1. Wählen Sie im Hierarchy-Fenster das Canvas-Objekt aus.
   2. Ziehen Sie das Canvas-Objekt per Drag-and-drop aus dem Hierarchy-Fenster auf den Slot WidgetsContainer im Inspector-Fenster.
   3. Ziehen Sie das VirtualItemWidget-Objekt per Drag-and-drop aus dem Hierarchy-Fenster auf den Slot WidgetPrefab im Inspector-Fenster.

Shop-Objekt (Beispiel):

Shop starten und testen

Starten Sie den Shop im Unity-Editor, und prüfen Sie die Funktionalität:

1. Löschen Sie alle untergeordneten Objekte des Canvas-Objekts.
2. Klicken Sie auf Play. Daraufhin öffnet sich beim Start der Anwendung das Xsolla-Login-Widget in einem Browserfenster.

3. Melden Sie sich bei der Anwendung an. Nach erfolgreicher Benutzerautorisierung fordert die Anwendung den Artikelkatalog von Xsolla an. Nach erfolgreichem Erhalt der Artikeldaten erstellt die Anwendung die erforderlichen Widgets. Anschließend wird eine Liste der Shop-Artikel angezeigt.

4. Klicken Sie auf die Kaufen-Schaltfläche in einem der Artikel-Widgets. Die Anwendung initiiert den Kaufvorgang und zeigt das Zahlungsportal im Browser an.

5. Schließen Sie den Bezahlvorgang ab. Zum Bezahlen können Sie Testkarten verwenden. Nach dem erfolgreichen Kauf wird im Protokoll die Meldung Purchase completed angezeigt.

Nützliche Links