Как использовать Pay Station совместно с аутентификацией PlayFab

Если вы уже реализовали аутентификацию пользователей в приложении с использованием PlayFab, вы можете формировать платежный токен на стороне PlayFab, а затем передавать его в клиентскую часть приложения для открытия платежного интерфейса.

При таком способе интеграции вам потребуется самостоятельно реализовать логику определения страны пользователя и валюты для оплаты покупки.

Сценарий интеграции:

1. Создайте проект.

1. Зарегистрируйтесь в Личном кабинете и создайте новый проект. ID созданного проекта потребуется вам на дальнейших шагах.

2. Настройте каталог товаров:
   • Создайте каталог товаров на стороне Xsolla. Вы можете добавить товары вручную или импортировать их из Google Play или PlayFab.
   • Реализуйте получение каталога с помощью методов SDK и его отображение на клиенте приложения.

3. Настройте покупку товара:
   • Реализуйте создание заказа с данными о пользователе и товаре c помощью облачного скрипта PlayFab.
   • Реализуйте открытие платежного интерфейса на клиентской части приложения с помощью SDK.

4. Настройте отслеживание статуса заказа.

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

Регистрация в Личном кабинете

Личный кабинет — основной инструмент для настройки возможностей Xsolla, а также для работы с аналитикой и транзакциями.

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

Чтобы зарегистрироваться, перейдите в Личный кабинет и создайте аккаунт.

Создание проекта в Личном кабинете

Если у вас есть несколько приложений, мы рекомендуем создавать отдельный проект для каждого приложения. На основе данных, указанных при создании проекта, Xsolla сформирует рекомендации по подходящим для вас решениям.

Чтобы создать новый проект:

1. Откройте Личный кабинет.
2. В боковом меню нажмите Создать проект.

3. Введите название проекта на английском языке (обязательно).

4. Выберите одну или несколько платформ релиза вашей игры (обязательно).
5. Укажите ссылку на игру. Если у вашей игры нет сайта, укажите ссылку на источник, который содержит информацию об игре (обязательно).
6. Выберите игровой движок.
7. Выберите способ монетизации, который вы используете или собираетесь использовать.
8. Укажите, вышла ли уже ваша игра. Если игра не вышла, укажите предполагаемую дату релиза.
9. Нажмите Создать проект. Вы увидите страницу с рекомендованными для вас продуктами Xsolla.

В процессе интеграции вам потребуется ID проекта. Вы можете найти его в Личном кабинете рядом с названием проекта.

Настройка каталога товаров

Создание предметов в Личном кабинете

Чтобы добавить в каталог виртуальный предмет с базовыми настройками:

1. Откройте проект в Личном кабинете.
2. Нажмите Store в боковом меню.
3. В панели Виртуальные предметы нажмите Подключить.
4. В раскрывающемся меню выберите Создать предмет.

5. Задайте базовые настройки предмета в следующих полях:
   • Изображение (опционально).
   • Артикул (уникальный ID предмета).
   • Название предмета.
   • Описание (опционально).

6. Задайте цену предмета:
   1. Установите переключатель Цены в реальной валюте в положение Вкл.
   2. В поле Цена в реальной валюте измените валюту (опционально) и укажите цену предмета.
   3. Если вы изменили валюту в поле Цена в реальной валюте, укажите эту же валюту в поле Валюта по умолчанию.

7. Измените статус предмета на Доступен.

8. Нажмите Создать предмет.

Установка и настройка SDK

1. Скачайте Epic Games Launcher.
2. Создайте новый проект Unreal Engine.

3. Загрузите и установите SDK одним из способов:
   1. Чтобы загрузить и установить SDK через Unreal Engine Marketplace:
      1. Откройте страницу SDK на Unreal Engine Marketplace.
      2. Нажмите Open in Launcher.

1. 1. 3. Перейдите в Epic Games Launcher.

1. 1. 4. Нажмите Install to Engine.
      5. Откройте проект Unreal Engine в Unreal Editor.
      6. Перейдите в раздел Settings > Plugins > Installed > Xsolla SDK, установите флажок Enabled и нажмите кнопку Restart Now, чтобы сохранить настройки и перезапустить Unreal Editor.

1. 2. Чтобы загрузить и установить SDK через GitHub:
      1. Скачайте архив с SDK для вашей версии движка.
      2. Распакуйте архив.
      3. Переместите папку с SDK в директорию plugins в корне вашего проекта Unreal Engine.

4. Перейдите в раздел Settings > Project Settings > Plugins > Xsolla Settings > General.
5. В поле Project ID укажите ID проекта, который можно найти в Личном кабинете рядом с названием проекта.

Отображение каталога в клиентской части приложения

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

1. В Content Browser перейдите в директорию Content.
2. Вызовите контекстное меню и выберите пункт Blueprint Class.

3. В разделе All Classes выберите Object и нажмите Select.

4. Укажите в качестве названия класса StoreItemData.
5. Откройте блупринт созданного класса.
6. В панели My Blueprint нажмите Add New и выберите пункт Variable.
7. В панели Details:

1. 1. В поле Variable Type выберите StoreItem.
   2. Установите флажки Instance Editable и Expose on Spawn.

8. Сохраните и закройте блупринт StoreItemData.

Создание виджета для предмета каталога

1. В Content Browserперейдите в директорию Content и в контекстном меню выберите пункт User Interface > Widget Blueprint.
2. Укажите в качестве названия блупринта StoreItem.
3. Откройте созданный блупринт.
4. В панели Hierarchy вызовите контекстное меню для элемента CanvasPanel. Выберите пункт Replace With > Overlay.

5. Разместите UI-примитивы из панели Palette, как показано на рисунке. Для изображения, названия и описания предмета установите флажок Is Variable на панели Details.

6. Перейдите к представлению Graph.
7. Нажмите Class settings.
8. В панели Details перейдите в раздел Interfaces > Implemented Interfaces.
9. Нажмите Add и выберите UserObjectListEntry. Это стандартный интерфейс Unreal Engine, позволяющий UI-примитиву реализовать свойственное для элемента списка поведение.

10. Добавьте логику события OnListItemObjectSet:
    1. В панели My Blueprint вызовите контекстное меню для раздела Interfaces и выберите пункт Implement event.

1. 2. Добавьте ноды, как показано на рисунке ниже:

11. Сохраните и закройте блупринт StoreItem.

Создание виджета для страницы каталога

1. В Content Browser перейдите в директорию Content и в контекстном меню выберите пункт User Interface > Widget Blueprint.
2. Укажите в качестве названия блупринта WBP_Store.
3. Откройте созданный блупринт.
4. В область отображения предметов добавьте элемент List View и назовите его StoreListView.

5. В панели Details в поле Entry Widget Class выберите созданный ранее класс для предмета (StoreItem).
6. Перейдите к представлению Graph.
7. К ноде EventConstruct привяжите вызов метода SDK GetVirtualItems, как показано на рисунке ниже.

8. В панели My Blueprint нажмите Add New и выберите пункт Variable.
9. В панели Details:
   1. В поле Variable Type выберите String.
   2. Установите флажки Instance Editable и Expose on Spawn.
   3. Укажите в качестве названия PlayFabId.

10. Сохраните и закройте виджет WBP_Store.
11. Добавьте логику отображения каталога. Ниже приведен пример реализации отображения каталога после успешной аутентификации пользователя.

Настройка покупки товара

Чтобы на стороне Xsolla сформировать заказ с данными о пользователе и товаре, добавьте в проект облачную функцию, вызывающую метод API Create payment token for purchase. Этот метод вернет платежный токен, который потребуется для открытия платежного интерфейса и совершения оплаты.

Ограничения:

• Вам необходимо передать в запросе платежного токена либо страну, либо IP-адрес пользователя.
• Если вы не передали валюту при запросе платежного токена, она будет определяться согласно стране пользователя.
• Если вы передали валюту при запросе платежного токена, пользователь будет оплачивать заказ в этой валюте.

Добавление облачного скрипта в проект

1. Откройте Visual Studio Code и перейдите на вкладку Azure.
2. В разделе Workspace нажмите на значок + и выберите Create Function.

3. Укажите новую директорию для проекта. Появится меню создания нового проекта с выбором настроек.

4. Задайте настройки нового проекта:
   1. Выберите язык для вашей функции — JavaScript.
   2. Выберите модель программирования JavaScript — model V4.
   3. Выберите шаблон для первой функции вашего проекта — HTTP trigger.
   4. Укажите имя функции — getXsollaPaymentToken.
   5. Выберите, как вы хотите открыть свой проект — Open in current window.

1. В результате Visual Studio Code сгенерирует JS-проект и откроет созданный файл getXsollaPaymentToken.js.

5. Измените файл getXsollaPaymentToken.js:

const { app } = require('@azure/functions');

const projectId = ""; //your xsolla project id from publisher account
const apiKey = ""; your api key from publisher account

app.http('getXsollaPaymentToken', {
    methods: ['POST'],
    authLevel: 'anonymous',
    handler: async (request, context) => {

      var body = await request.json();

      const userId = body.uid;
      const email = body.email;
      const sku = body.sku;
      const returnUrl = body.returnUrl;

        if (!userId) {
          return {status: 400, body: 'Request body is missing' };
        }

        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/v2/project/" + projectId.toString() + "/admin/payment/token";

        return 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 {
                    return { status: 400, body: `HTTP request failed with error: ${xsollaRes.statusText}` };
                }
            })
            .then(data => {
                return { status: 200, body: JSON.stringify(data) };
            })
            .catch(error => {
                return { status: 501, body: `Error = ${error}` };
            });
        }
});

1. В скрипте укажите значения констант:

1. • PROJECT_ID — ID проекта, который можно найти в Личном кабинете рядом с названием проекта.

1. • API_KEY — ключ API. Он отображается в Личном кабинете только при создании и должен храниться на вашей стороне. Создать ключ можно в следующих разделах:
     • Настройки компании > Ключи API;
     • Настройки проекта > Ключи API.

После добавления облачного скрипта вы можете протестировать вызов функции getXsollaPaymentToken локально.

Деплой облачного скрипта

1. В Visual Studio Code и перейдите в разделе Azure > Resources и нажмите на значок +.
2. В качестве ресурса выберите Create Function App in Azure. Появится меню создания нового приложения с выбором настроек.
3. Задайте настройки приложения:

1. 1. Укажите название приложения — XsollaFunctions.
   2. Укажите стек среды выполнения — .NET 8 Isolated.
   3. Укажите место для новых ресурсов (можно выбрать любой вариант).

1. Дождитесь окончания создания группы ресурсов.

4. В списке ресурсов выберите функцию XsollaFunctions, вызовите контекстное меню и выберите Deply to Function App.

После деплоя облачного скрипта вы можете протестировать вызов функции getXsollaPaymentToken удаленно.

Тестирование облачного скрипта

Чтобы протестировать работу облачного скрипта (локально или удаленно), вызовите функцию getXsollaPaymentToken с помощью Postman или другого инструмента. Для этого:

1. В Visual Studio Code перейдите в разделе Azure > Workspace > Local Project > Functions и нажмите Start debugging to update this list.
2. Вызовите контекстное меню для функции и выберитеCopy Function Url. При локальном тестировании URL-адрес будет иметь вид http://localhost:7071/api/getXsollaPaymentToken. При удаленном — https://xsollafunctions.azurewebsites.net/api/GetXsollaPaymentToken.

3. Используйте скопированные URL-адрес, чтобы вызвать функцию с указанными параметрами. Чтобы вызвать функцию из Postman:
   1. Создайте новый GET-запрос.
   2. Укажите URL-адрес, скопированный на шаге 2.
   3. Перейдите на вкладку Body и укажите параметры запроса.

Пример тела запроса:

{

 "FunctionArgument": {

   "uid": "1D384D9EF12EAB8B",

   "sku": "booster_max_1",

   "returnUrl": "https://login.xsolla.com/api/blank"

 }

}

4. Нажмите Send. В ответе вы должны получить JSON со следующими параметрами:
   • token — платежный токен. Требуется для открытия платежного интерфейса.
   • order_id — ID созданного заказа. Требуется для отслеживания статуса заказа.

Пример тела ответа:

{"token":"xsnpCF8tS4ox7quoibgTgPFVFxG9gTvS_lc_en_bg_2C2640_tb_6E7BF7","order_id":90288613}

Регистрация функции получения платежного токена в PlayFab

1. Откройте ваш проект в PlayFab.
2. В боковом меню нажмите Automation.
3. В области Register New Cloud Script Function нажмите Register Function.
4. Укажите название функции — GetXsollaPaymentToken.
5. Укажите URL-адрес функции, скопированный в Visual Code Studio (см. шаги 1-2 раздела Тестирование облачного скрипта).

Создание заказа и открытие платежного интерфейса в проекте Unreal Engine

1. Откройте ваш проект Unreal Engine.
2. Откройте виджет WBP_Store.
3. В панели Hierarchy выберите StoreListView.
4. В панели Details нажмите значок + рядом с событием On Clicked.

5. Перейдите к представлению Graph.
6. К ноде OnItemClicked добавьте логику создания объекта PlayfabJsonObject и передачи в него данных для создания заказа, как показано на рисунке ниже:

7. Добавьте вызов метода ExecuteFunction. Передайте в него параметры functionName = getXsollaPaymentToken и FunctionParameter = PlayfabJsonObject.

Отслеживание статуса заказа

Отслеживание статуса заказа требуется, чтобы убедиться, что оплата прошла успешно, и начислить товары пользователю.

Получение статуса заказа на клиентской части

Чтобы отслеживать изменения статуса заказа, используйте в клиентской части приложения метод SDK CheckPendingOrder. Передайте в метод следующие параметры:

• AuthToken — авторизационный токен пользователя;
• OrderId — ID заказа, полученный в результате покупки через корзину, покупки в один клик или покупки за виртуальную валюту;
• SuccessCallback — функция, которая вызывается в случае перехода заказа в статус done;
• ErrorCallback — функция, которая вызывается в случае, если сервер Xsolla возвращает ошибку.

Подробные сведения о работе метода приведены в разделе Отслеживание статуса заказа.

Получение статуса заказа на серверной части

Чтобы настроить вебхуки на стороне Xsolla:

1. Откройте проект в Личном кабинете.
2. Нажмите Настройки проекта в боковом меню и перейдите в раздел Вебхуки.
3. В поле Сервер для вебхуков укажите URL-адрес, на который Xsolla будет отправлять вебхуки.

4. Скопируйте и сохраните значение из поля Секретный ключ. Этот ключ генерируется по умолчанию и используется для подписи вебхуков. Если вы хотите изменить его, нажмите значок обновления.
5. Нажмите Получать вебхуки.