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

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

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

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

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

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

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

Диаграмма взаимодействия вашего приложения (скрипт StoreController) с SDK:

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

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

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

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

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

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

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

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

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

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. Откройте созданный файл в редакторе и добавьте в него следующий код:

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

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

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

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.

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