SDK enterprise-уровня для Unreal Engine / Как использовать Pay Station совместно с аутентификацией PlayFab
  На главную

SDK enterprise-уровня для Unreal Engine

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

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

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

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

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

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

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

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

Внимание

Чтобы завершить интеграцию и начать принимать реальные платежи, вам требуется подписать Лицензионный договор с Xsolla.

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

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

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

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

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

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

Примечание

Пароль от Личного кабинета должен содержать не менее:

  • 8 символов;
  • одной цифры;
  • одной прописной буквы латинского алфавита;
  • одной строчной буквы латинского алфавита.

Для обеспечения безопасности пароля рекомендуется:

  • менять пароль не реже одного раза в 90 дней;
  • использовать новый пароль, который не совпадает с последними 4 паролями вашей учетной записи;
  • использовать уникальный пароль, который не совпадает с паролями в других сервисах;
  • не хранить пароль в легкодоступных местах;
  • использовать менеджеры паролей для хранения пароля.

Личный кабинет использует двухфакторную аутентификацию и отправляет код подтверждения при каждой попытке аутентификации.

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

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

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

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

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

Примечание
После создания проекта вы можете добавить дополнительные языки и названия проекта на этих языках в разделе Настройки проекта.

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

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

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

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

Внимание

Вам потребуется создать каталог товаров на стороне Xsolla. Вы можете добавить товары вручную или импортировать их из Google Play или PlayFab. При импорте из Google Play можно импортировать не более 100 предметов за раз.

В рамках этой инструкции приведены шаги по базовой настройке виртуального предмета. Позже вы сможете дополнить свой каталог другими товарами (виртуальными валютами, бандлами, игровыми ключами), создать группы товаров, настроить акционные кампании, региональные цены и т. д.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

Для получения списка виртуальных предметов в настоящей инструкции используется метод SDK GetVirtualItems. Вы также можете получать информацию о товарах из каталога с помощью других методов.

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

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

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

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

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

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

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

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

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

Примечание
В Unreal Engine 4.27 CanvasPanel является корневым компонентом по умолчанию для каждого вновь создаваемого виджета. В Unreal Engine 5 корневой компонент по умолчанию не добавляется, поэтому вам потребуется создать Overlay в качестве корневого компонента.

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

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

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

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

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

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

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

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

Примечание
Массив предметов, который возвращает Xsolla, представляет собой массив структур Unreal Engine. Но элементы List View могут получать только массивы объектов класса UObject. Для корректной передачи массива объектов в примере создается вспомогательный массив объектов класса StoreItemData.

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

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

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

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

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

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

Примечание

Предварительно у вас должен быть создан и настроен проект PlayFab, в проект Unity должен быть интегрирован PlayFab SDK.

Сами по себе облачные скрипты PlayFab не поддерживают функции с триггерами HTTP, поэтому для реализации получения вебхуков используются функции Azure.

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

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

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

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

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

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

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

Copy
Full screen
Small screen
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. В скрипте укажите значения констант:

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

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

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

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

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

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

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

  1. В списке ресурсов выберите функцию 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.

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

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

Copy
Full screen
Small screen
{

 "FunctionArgument": {

   "uid": "1D384D9EF12EAB8B",

   "sku": "booster_max_1",

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

 }

}
Примечание
В качестве  ID пользователя (uid) вы можете указать любое значение. В качестве артикула товара (sku) укажите артикул виртуального предмета, который вы ранее добавили в Личном кабинете.

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

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

Copy
Full screen
Small screen
{"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.

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

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

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

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

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

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

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

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

Внимание

SDK позволяет отслеживать статус заказа на клиентской части вашего приложения. Однако мы рекомендуем настроить обработку вебхука Успешный платеж и получать информацию о заказе на серверной части вашего приложения. Это позволит реализовать дополнительную валидацию совершенных покупок.

Полный список вебхуков и общая информация о работе с ними приведены в документации по вебхукам.

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

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

Примечание

Для тестирования вебхуков вы также можете выбрать любой специализированный сайт, например webhook.site, или платформу, например ngrok.

В целях тестирования, вы также можете добавить облачный скрипт, который будет имитировать успешную обработку вебхука. Код скрипта доступен на GitHub.

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

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

Была ли статья полезна?
Спасибо!
Что может сделать страницу еще лучше? Сообщение
Жаль, что так произошло
Расскажите, почему статья не была полезна. Сообщение
Спасибо за обратную связь!
Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.
Последнее обновление: 3 октября 2024

Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.

Сообщите о проблеме
Мы постоянно улучшаем качество нашей документации. Ваш отзыв поможет нам в этом.
Укажите email-адрес, чтобы мы могли связаться с вами
Спасибо за обратную связь!