Интеграция SDK на стороне приложения

Основная информация

1. Разработайте интерфейс для системы входа, внутриигрового магазина и других страниц вашего приложения.
2. Реализуйте в вашем приложении логику аутентификации пользователей, отображения товаров в магазине, покупки и т. д. с помощью методов SDK.

Быстрый старт

Ниже приведены инструкции по наиболее простой реализации продажи товаров внутри игры.

Сценарий взаимодействия:

1. Пользователь запускает игру.
2. Приложение запускает веб-виджет Xsolla Login.
3. Пользователь авторизуется в игре и переходит в каталог товаров.
4. Приложение отправляет запрос к Xsolla для получения каталога товаров.
5. После успешного получения информации о товарах приложение отображает каталог товаров.
6. Пользователь нажимает кнопку покупки товара.
7. Приложение инициирует процесс покупки и отображает в браузере платежный интерфейс.
8. Пользователь совершает оплату.
9. Приложение закрывает платежный интерфейс и передает в Xsolla информацию о платеже.
10. Приложение выводит в лог сообщение о результатах обработки платежа.

Диаграмма взаимодействия вашего приложения (скрипт StoreController) с 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

Особенности сценария:

• Для авторизации пользователя используется готовый веб-виджет Xsolla Login. Xsolla предоставляет стандартные шаблоны для виджета авторизации. Их внешний вид и наполнение определяются способом авторизации, выбранным для проекта, и настройками кастомизации виджета в Личном кабинете.

• В сценарии реализована продажа товаров за реальную валюту без использования корзины, т. е. пользователь сможет купить только один товар.

Создание скрипта виджета предмета

Создайте новый скрипт с названием VirtualItemWidget, для этого:

1. Откройте ваш проект в редакторе Unity.
2. В главном меню выберите пункт Assets > Create > C# Script.
3. Укажите для нового файла в папке Assets название — VirtualItemWidget.
4. Откройте созданный файл в редакторе и добавьте в него следующий код:

 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. Сохраните изменения.

Создание префаба виджета товара

Создайте интерфейс для отображения товара в магазине:

1. Создайте объект Canvas для отображения UI-элементов. Для этого в главном меню выберите пункт GameObject > UI > Canvas. В результате на сцене будут созданы:
   • Объект Canvas с компонентами Canvas, Canvas Scaler и Graphic Raycaster.
   • Объект EventSystem, если такого объекта еще не существует на сцене.
2. Создайте дочерний объект VirtualItemWidget:
   1. В панели Hierarchy выберите объект Canvas.
   2. В главном меню выберите пункт GameObject > UI > Image. В результате будет создан новый игровой объект, этот объект будет дочерним по отношение к объекту Canvas.
   3. Переименуйте созданный объект в VirtualItemWidget.
3. Добавьте UI-объекты для отображения информации о товаре:
   1. Создайте объект для отображения иконки виджета:
      1. В панели Hierarchy выберите объект VirtualItemWidget.
      2. В главном меню выберите пункт GameObject > UI > Image.
      3. Переименуйте созданный объект в IconImage.
   2. Создайте объект для отображения названия товара:
      1. В панели Hierarchy выберите объект VirtualItemWidget.
      2. В главном меню выберите пункт GameObject > UI > Legacy > Text.
      3. Переименуйте созданный объект в NameText.
   3. Создайте объект для отображения описания товара:
      1. В панели Hierarchy выберите объект VirtualItemWidget.
      2. В главном меню выберите пункт GameObject > UI > Legacy > Text.
      3. Переименуйте созданный объект в DescriptionText.
   4. Создайте объект кнопки для покупки товара:
      1. В панели Hierarchy выберите объект VirtualItemWidget.
      2. В главном меню выберите пункт GameObject > UI > Legacy > Button. В результате будет создан объект кнопки с дочерним объектом Text.
      3. Переименуйте созданный объект в BuyButton.
      4. Переименуйте объект Text в PriceText.
4. Добавьте к объекту VirtualItemWidget скрипт виджета товара в качестве компонента:
   1. В панели Hierarchy выберите объект VirtualItemWidget.
   2. В панели Inspector нажмите Add Component и выберите скрипт VirtualItemWidget.
5. Назначьте UI-элементы в необходимые слоты скрипта:
   1. В панели Hierarchy выберите объект VirtualItemWidget.
   2. Перетащите дочерние UI-объекты из панели Hierarchy в соответствующие им слоты компонента VirtualItemWidget в панели Inspector.
6. Преобразуйте созданный объект VirtualItemWidget в префаб:
   1. В панели Hierarchy выберите объект VirtualItemWidget.
   2. Перетащите объект в панель Project в папку Assets. В результате в папке Assets появится новый объект, а объект на сцене сменит цвет на синий.

Пример префаба виджета товара:

Создание скрипта магазина

Создайте новый скрипт с названием StoreController, для этого:

1. Откройте ваш проект в редакторе Unity.
2. В главном меню выберите пункт Assets > Create > C# Script.
3. Укажите для нового файла в папке Assets название — StoreController.
4. Откройте созданный файл в редакторе и добавьте в него следующий код:

 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. Сохраните изменения.

Создание объекта магазина

Создайте интерфейс для отображения списка товаров в магазине:

1. Добавьте компонент, который будет располагать виджеты отдельных товаров в виде сетки, управлять расположением и размером вложенных объектов. Для этого:
   1. В панели Hierarchy выберите объект Canvas.
   2. В панели Inspector нажмите Add Component и выберите скрипт Grid Layout Group.
   3. В панели Inspector при необходимости измените настройки компонента: задайте размер ячеек, интервалы и т. д.

2. Добавьте к объекту Canvas скрипт магазина в качестве компонента:
   1. В панели Hierarchy выберите объект Canvas.
   2. В панели Inspector нажмите Add Component и выберите скрипт StoreController.
3. Назначьте элементы в необходимые слоты скрипта StoreController:
   1. В панели Hierarchy выберите объект Canvas.
   2. Перетащите объект Canvas из панели Hierarchy в слот WidgetsContainer в панели Inspector.
   3. Перетащите объект VirtualItemWidget из панели Hierarchy в слот WidgetPrefab в панели Inspector.

Пример объекта магазина:

Тестирование запуска магазина

Запустите магазин в редакторе Unity и проверьте его работу:

1. Для объекта Canvas удалите все дочерние объекты.
2. Нажмите Play. В результате при старте приложения откроется окно браузера с виджетом Xsolla Login.

3. Авторизуйтесь в приложении. После успешной авторизации пользователя приложение отправляет запрос к Xsolla для получения каталога товаров. После успешного получения информации о товарах приложение создаст необходимые виджеты. В результате отобразится список товаров магазина.

4. Нажмите кнопку покупки в виджете любого товара. Приложение инициирует процесс покупки, в браузере откроется платежный интерфейс.

5. Завершите процесс покупки. Используйте для оплаты тестовые банковские карты.  После успешной покупки в логах появится сообщение Purchase completed.

Полезные ссылки