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:

  %%{init: {'themeVariables': { 'noteBkgColor': 'transparent', 'noteBorderColor': 'transparent', 'noteTextColor': '#495C6B' }}}%%
sequenceDiagram
    participant Player
    participant StoreController
    participant SDK
    Player->>StoreController: Starts the game.
    activate StoreController
    activate StoreController
    note right of StoreController: Calls StartAuthorization custom method.
    deactivate StoreController
    StoreController->>SDK: Initiates authorization via Xsolla Login Widget,<br>calls XsollaAuth.AuthWithXsollaWidget SDK method.
    activate SDK
    SDK->>Player: Opens Xsolla Login Widget in a browser.
    deactivate SDK
    activate Player
    Player->>SDK: Enters login credentials.
    deactivate Player
    activate SDK
    activate SDK
    note right of SDK: Processes authentication results.
    deactivate SDK
    SDK->>StoreController: Calls OnAuthSuccess custom method.
    deactivate SDK
    StoreController->>SDK: Requests the item catalog,<br>calls XsollaCatalog.GetItems SDK method.
    activate SDK
    SDK->>StoreController: Calls OnCatalogReceived custom method.
    deactivate SDK
    activate StoreController
    note right of StoreController: Builds store UI, calls BuildStoreUI custom method.
    deactivate StoreController
    StoreController->>Player: Displays item catalog.
    deactivate StoreController
    activate Player
    Player->>StoreController: Clicks the item purchase button.
    deactivate Player
    activate StoreController
    activate StoreController
    note right of StoreController: Initiates the purchase process, calls StartPurchase custom method.
    deactivate StoreController
    StoreController->>SDK: Calls XsollaCatalog.Purchase SDK method.
    activate SDK
    SDK->>Player: Opens the payment UI in a browser.
    deactivate SDK
    activate Player
    Player->>SDK: Completes the payment.
    activate SDK
    deactivate Player
    activate SDK
    note right of SDK: Processes the payment.
    deactivate SDK
    SDK->>Player: Closes payment UI.
    activate Player
    SDK->>StoreController: Calls OnPurchaseCompleted  custom method<br>when order transitions to the 'done' status.
    deactivate SDK
    StoreController->>Player: Displays a success message in the log.
    deactivate StoreController
    deactivate Player

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:

 1using UnityEngine;
 2using UnityEngine.UI;
 3
 4namespace Xsolla.Example
 5{
 6    public class VirtualItemWidget : MonoBehaviour
 7    {
 8       public Image IconImage;
 9       public Text NameText;
10       public Text DescriptionText;
11       public Text PriceText;
12       public Button BuyButton;
13    }
14}

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:

 1using System.Linq;
 2using UnityEngine;
 3using Xsolla.Auth;
 4using Xsolla.Catalog;
 5using Xsolla.Core;
 6namespace Xsolla.Example
 7{
 8	public class StoreController : MonoBehaviour
 9	{
10		[SerializeField] private VirtualItemWidget WidgetPrefab;
11		[SerializeField] private Transform WidgetsContainer;
12		private void Start()
13		{
14			StartAuthorization();
15		}
16		private void StartAuthorization()
17		{
18			Debug.Log("Start the authorization process with the Xsolla Login Widget");
19			XsollaAuth.AuthWithXsollaWidget(OnAuthSuccess, OnError, null);
20		}
21		private void OnAuthSuccess()
22		{
23			Debug.Log("Authorization successful");
24			Debug.Log("Get the catalog of virtual items");
25			XsollaCatalog.GetItems(OnCatalogReceived, OnError);
26		}
27		private void OnCatalogReceived(StoreItems items)
28		{
29			Debug.Log("Catalog received successfully");
30			BuildStoreUI(items.items);
31		}
32		private void BuildStoreUI(StoreItem[] items)
33		{
34			// Create a widget for each item in the catalog
35			foreach (var item in items)
36			{
37				// Check if the item has a price for real money. If not, skip the item (e.g., it is a virtual currency)
38				if (item.price == null)
39					continue;
40				// Instantiate a widget prefab
41				var widget = Instantiate(WidgetPrefab, WidgetsContainer, false);
42				// Fill the widget with data
43				widget.NameText.text = item.name;
44				widget.DescriptionText.text = item.description;
45				widget.PriceText.text = $"{item.price.amount} {item.price.currency}";
46				// Loading the item image and assigning it to the UI element
47				ImageLoader.LoadSprite(item.image_url, sprite => widget.IconImage.sprite = sprite);
48				// Add a click listener to the Buy button
49				widget.BuyButton.onClick.AddListener(() => StartPurchase(item.sku));
50			}
51		}
52		private void StartPurchase(string sku)
53		{
54			Debug.Log($"Start the purchase process for the item: {sku}");
55			XsollaCatalog.Purchase(sku, OnPurchaseCompleted, OnError);
56		}
57		private void OnPurchaseCompleted(OrderStatus status)
58		{
59			Debug.Log("Purchase completed");
60		}
61		private void OnError(Error error)
62		{
63			Debug.LogError($"Error message: {error.errorMessage}");
64		}
65	}
66}

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 Testbankkarten verwenden. Nach dem erfolgreichen Kauf wird im Protokoll die Meldung Purchase completed angezeigt.

Nützliche Links