Как использовать Pay Station совместно с аутентификацией PlayFab
Если вы уже реализовали аутентификацию пользователей в приложении с использованием PlayFab, вы можете формировать платежный токен на стороне PlayFab, а затем передавать его в клиентскую часть приложения для открытия платежного интерфейса.
При таком способе интеграции вам потребуется самостоятельно реализовать логику определения страны пользователя и валюты для оплаты покупки.
Сценарий интеграции:
- Зарегистрируйтесь в Личном кабинете и создайте новый проект. ID созданного проекта потребуется вам на дальнейших шагах.
- Настройте каталог товаров:
- Создайте каталог товаров на стороне Xsolla. Вы можете добавить товары вручную или импортировать их из Google Play или PlayFab.
- Реализуйте получение каталога с помощью методов SDK и его отображение на клиенте приложения.
- Настройте покупку товара:
- Реализуйте создание заказа с данными о пользователе и товаре c помощью облачного скрипта PlayFab.
- Реализуйте открытие платежного интерфейса на клиентской части приложения с помощью SDK.
Чтобы завершить интеграцию и начать принимать реальные платежи, вам требуется подписать Лицензионный договор с Xsolla.
Вы можете подписать лицензионный договор на любом этапе интеграции, но обратите внимание, что процесс рассмотрения заявки занимает до 3 рабочих дней.
Создание проекта
Регистрация в Личном кабинете
Личный кабинет — основной инструмент для настройки возможностей Xsolla, а также для работы с аналитикой и транзакциями.
Указанные на этапе регистрации данные о компании и вашем приложении будут использоваться для формирования рекомендаций с подходящими для вас решениями и создания черновика договора с Xsolla. Вы сможете изменить данные позже, но указание при регистрации верных данных ускорит процесс согласования договора.
Чтобы зарегистрироваться, перейдите в Личный кабинет и создайте аккаунт.
Пароль от Личного кабинета должен содержать не менее:
- 8 символов;
- одной цифры;
- одной прописной буквы латинского алфавита;
- одной строчной буквы латинского алфавита.
Для обеспечения безопасности пароля рекомендуется:
- менять пароль не реже одного раза в 90 дней;
- использовать новый пароль, который не совпадает с последними 4 паролями вашей учетной записи;
- использовать уникальный пароль, который не совпадает с паролями в других сервисах;
- не хранить пароль в легкодоступных местах;
- использовать менеджеры паролей для хранения пароля.
Личный кабинет использует двухфакторную аутентификацию и отправляет код подтверждения при каждой попытке аутентификации.
Создание проекта в Личном кабинете
Если у вас есть несколько приложений, мы рекомендуем создавать отдельный проект для каждого приложения. На основе данных, указанных при создании проекта, Xsolla сформирует рекомендации по подходящим для вас решениям.
Чтобы создать новый проект:
- Откройте Личный кабинет.
- В боковом меню нажмите Создать проект.
- Введите название проекта на английском языке (обязательно).
- Выберите одну или несколько платформ релиза вашей игры (обязательно).
- Укажите ссылку на игру. Если у вашей игры нет сайта, укажите ссылку на источник, который содержит информацию об игре (обязательно).
- Выберите игровой движок.
- Выберите способ монетизации, который вы используете или собираетесь использовать.
- Укажите, вышла ли уже ваша игра. Если игра не вышла, укажите предполагаемую дату релиза.
- Нажмите Создать проект. Вы увидите страницу с рекомендованными для вас продуктами Xsolla.
В процессе интеграции вам потребуется ID проекта. Вы можете найти его в Личном кабинете рядом с названием проекта.
Настройка каталога товаров
Создание предметов в Личном кабинете
Вам потребуется создать каталог товаров на стороне Xsolla. Вы можете добавить товары вручную или импортировать их из Google Play или PlayFab. При импорте из Google Play можно импортировать не более 100 предметов за раз.
В рамках этой инструкции приведены шаги по базовой настройке виртуального предмета. Позже вы сможете дополнить свой каталог другими товарами (виртуальными валютами, бандлами, игровыми ключами), создать группы товаров, настроить акционные кампании, региональные цены и т. д.
Чтобы добавить в каталог виртуальный предмет с базовыми настройками:
- Откройте проект в Личном кабинете.
- Нажмите Store в боковом меню.
- В панели Виртуальные предметы нажмите Подключить.
- В раскрывающемся меню выберите Создать предмет.
- Задайте базовые настройки предмета в следующих полях:
- Изображение (опционально).
- Артикул (уникальный ID предмета).
- Название предмета.
- Описание (опционально).
- Задайте цену предмета:
- Установите переключатель Цены в реальной валюте в положение Вкл.
- В поле Цена в реальной валюте измените валюту (опционально) и укажите цену предмета.
- Если вы изменили валюту в поле Цена в реальной валюте, укажите эту же валюту в поле Валюта по умолчанию.
- Измените статус предмета на Доступен.
- Нажмите Создать предмет.
Установка и настройка SDK
- Скачайте Epic Games Launcher.
- Создайте новый проект Unreal Engine.
- Загрузите и установите SDK одним из способов:
- Чтобы загрузить и установить SDK через Unreal Engine Marketplace:
- Откройте страницу SDK на Unreal Engine Marketplace.
- Нажмите
Open in Launcher .
- Чтобы загрузить и установить SDK через Unreal Engine Marketplace:
- Перейдите в Epic Games Launcher.
- Нажмите
Install to Engine . - Откройте проект Unreal Engine в Unreal Editor.
- Перейдите в раздел
Settings > Plugins > Installed > Xsolla SDK , установите флажокEnabled и нажмите кнопкуRestart Now , чтобы сохранить настройки и перезапустить Unreal Editor.
- Нажмите
- Чтобы загрузить и установить SDK через GitHub:
- Скачайте архив с SDK для вашей версии движка.
- Распакуйте архив.
- Переместите папку с SDK в директорию
plugins
в корне вашего проекта Unreal Engine.
- Чтобы загрузить и установить SDK через GitHub:
- Перейдите в раздел
Settings > Project Settings > Plugins > Xsolla Settings > General . - В поле
Project ID укажите ID проекта, который можно найти в Личном кабинете рядом с названием проекта.
Отображение каталога в клиентской части приложения
Для получения списка виртуальных предметов в настоящей инструкции используется метод SDK GetVirtualItems
. Вы также можете получать информацию о товарах из каталога с помощью других методов.
Пошаговая обучающая инструкция для создания страницы каталога приведена в разделе Отображение каталога товаров.
Создание класса предмета каталога
- В
Content Browser перейдите в директориюContent . - Вызовите контекстное меню и выберите пункт
Blueprint Class .
- В разделе
All Classes выберитеObject и нажмитеSelect .
- Укажите в качестве названия класса
StoreItemData . - Откройте блупринт созданного класса.
- В панели
My Blueprint нажмитеAdd New и выберите пунктVariable . - В панели
Details :
- В поле
Variable Type выберитеStoreItem . - Установите флажки
Instance Editable иExpose on Spawn .
- В поле
- Сохраните и закройте блупринт
StoreItemData .
Создание виджета для предмета каталога
- В
Content Browser перейдите в директориюContent и в контекстном меню выберите пунктUser Interface > Widget Blueprint . - Укажите в качестве названия блупринта
StoreItem . - Откройте созданный блупринт.
- В панели
Hierarchy вызовите контекстное меню для элементаCanvasPanel . Выберите пунктReplace With > Overlay .
- Разместите UI-примитивы из панели
Palette , как показано на рисунке. Для изображения, названия и описания предмета установите флажокIs Variable на панелиDetails .
- Перейдите к представлению
Graph . - Нажмите
Class settings . - В панели
Details перейдите в разделInterfaces > Implemented Interfaces . - Нажмите
Add и выберитеUserObjectListEntry . Это стандартный интерфейс Unreal Engine, позволяющий UI-примитиву реализовать свойственное для элемента списка поведение.
- Добавьте логику события
OnListItemObjectSet
:- В панели
My Blueprint вызовите контекстное меню для разделаInterfaces и выберите пунктImplement event .
- В панели
- Добавьте ноды, как показано на рисунке ниже:
- Сохраните и закройте блупринт
StoreItem .
Создание виджета для страницы каталога
- В
Content Browser перейдите в директориюContent и в контекстном меню выберите пунктUser Interface > Widget Blueprint . - Укажите в качестве названия блупринта
WBP_Store . - Откройте созданный блупринт.
- В область отображения предметов добавьте элемент
List View и назовите егоStoreListView .
- В панели
Details в полеEntry Widget Class выберите созданный ранее класс для предмета (StoreItem
). - Перейдите к представлению
Graph . - К ноде
EventConstruct
привяжите вызов метода SDKGetVirtualItems
, как показано на рисунке ниже.
StoreItemData
.- В панели
My Blueprint нажмитеAdd New и выберите пунктVariable . - В панели
Details :- В поле
Variable Type выберитеString . - Установите флажки
Instance Editable иExpose on Spawn . - Укажите в качестве названия
PlayFabId .
- В поле
- Сохраните и закройте виджет
WBP_Store . - Добавьте логику отображения каталога. Ниже приведен пример реализации отображения каталога после успешной аутентификации пользователя.
Настройка покупки товара
Чтобы на стороне Xsolla сформировать заказ с данными о пользователе и товаре, добавьте в проект облачную функцию, вызывающую метод API Создание платежного токена для покупки. Этот метод вернет платежный токен, который потребуется для открытия платежного интерфейса и совершения оплаты.
Ограничения:
- Вам необходимо передать в запросе платежного токена либо страну, либо IP-адрес пользователя.
- Если вы не передали валюту при запросе платежного токена, она будет определяться согласно стране пользователя.
- Если вы передали валюту при запросе платежного токена, пользователь будет оплачивать заказ в этой валюте.
Предварительно у вас должен быть создан и настроен проект PlayFab, в проект Unity должен быть интегрирован PlayFab SDK.
Сами по себе облачные скрипты PlayFab не поддерживают функции с триггерами HTTP, поэтому для реализации получения вебхуков используются функции Azure.
Чтобы начать работать с функциями Azure, создайте аккаунт Azure и подготовьте вашу среду разработки. В рамках этой инструкции описаны шаги в среде разработке со следующими настройками:
- Установлен Visual Studio Code.
- Установлено расширение для работы с функциями Azure.
Добавление облачного скрипта в проект
- Откройте Visual Studio Code и перейдите на вкладку
Azure . - В разделе
Workspace нажмите на значок + и выберитеCreate Function .
- Укажите новую директорию для проекта. Появится меню создания нового проекта с выбором настроек.
- Задайте настройки нового проекта:
- Выберите язык для вашей функции —
JavaScript . - Выберите модель программирования JavaScript —
model V4 . - Выберите шаблон для первой функции вашего проекта —
HTTP trigger . - Укажите имя функции —
getXsollaPaymentToken
. - Выберите, как вы хотите открыть свой проект —
Open in current window .
- Выберите язык для вашей функции —
- В результате Visual Studio Code сгенерирует JS-проект и откроет созданный файл
getXsollaPaymentToken.js
.
- Измените файл
getXsollaPaymentToken.js
:
- 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}` };
});
}
});
- В скрипте укажите значения констант:
PROJECT_ID
— ID проекта, который можно найти в Личном кабинете рядом с названием проекта.
API_KEY
— ключ API. Он отображается в Личном кабинете только при создании и должен храниться на вашей стороне. Создать ключ можно в следующих разделах:- Настройки компании > Ключи API;
- Настройки проекта > Ключи API.
После добавления облачного скрипта вы можете протестировать вызов функции getXsollaPaymentToken
локально.
Деплой облачного скрипта
- В Visual Studio Code и перейдите в разделе
Azure > Resources и нажмите на значок +. - В качестве ресурса выберите
Create Function App in Azure . Появится меню создания нового приложения с выбором настроек. - Задайте настройки приложения:
- Укажите название приложения —
XsollaFunctions
. - Укажите стек среды выполнения —
.NET 8 Isolated . - Укажите место для новых ресурсов (можно выбрать любой вариант).
- Укажите название приложения —
- Дождитесь окончания создания группы ресурсов.
- В списке ресурсов выберите функцию
XsollaFunctions
, вызовите контекстное меню и выберитеDeply to Function App .
После деплоя облачного скрипта вы можете протестировать вызов функции getXsollaPaymentToken
удаленно.
Тестирование облачного скрипта
Чтобы протестировать работу облачного скрипта (локально или удаленно), вызовите функцию getXsollaPaymentToken
с помощью Postman или другого инструмента. Для этого:
- В Visual Studio Code перейдите в разделе
Azure > Workspace > Local Project > Functions и нажмитеStart debugging to update this list . - Вызовите контекстное меню для функции
и выберите
Copy Function Url . При локальном тестировании URL-адрес будет иметь видhttp://localhost:7071/api/getXsollaPaymentToken
. При удаленном —https://xsollafunctions.azurewebsites.net/api/GetXsollaPaymentToken
.
- Используйте скопированные URL-адрес, чтобы вызвать функцию с указанными параметрами. Чтобы вызвать функцию из Postman:
- Создайте новый
GET
-запрос. - Укажите URL-адрес, скопированный на шаге 2.
- Перейдите на вкладку
Body и укажите параметры запроса.
- Создайте новый
Пример тела запроса:
- json
{
"FunctionArgument": {
"uid": "1D384D9EF12EAB8B",
"sku": "booster_max_1",
"returnUrl": "https://login.xsolla.com/api/blank"
}
}
uid
) вы можете указать любое значение. В качестве артикула товара (sku
) укажите артикул виртуального предмета, который вы ранее добавили в Личном кабинете.- Нажмите
Send . В ответе вы должны получить JSON со следующими параметрами:token
— платежный токен. Требуется для открытия платежного интерфейса.order_id
— ID созданного заказа. Требуется для отслеживания статуса заказа.
Пример тела ответа:
- json
{"token":"xsnpCF8tS4ox7quoibgTgPFVFxG9gTvS_lc_en_bg_2C2640_tb_6E7BF7","order_id":90288613}
Регистрация функции получения платежного токена в PlayFab
- Откройте ваш проект в PlayFab.
- В боковом меню нажмите
Automation . - В области
Register New Cloud Script Function нажмитеRegister Function . - Укажите название функции —
GetXsollaPaymentToken
. - Укажите URL-адрес функции, скопированный в Visual Code Studio (см. шаги 1-2 раздела Тестирование облачного скрипта).
Создание заказа и открытие платежного интерфейса в проекте Unreal Engine
- Откройте ваш проект Unreal Engine.
- Откройте виджет
WBP_Store . - В панели
Hierarchy выберитеStoreListView . - В панели
Details нажмите значок + рядом с событиемOn Clicked .
- Перейдите к представлению
Graph . - К ноде
OnItemClicked
добавьте логику создания объектаPlayfabJsonObject
и передачи в него данных для создания заказа, как показано на рисунке ниже:
- Добавьте вызов метода
ExecuteFunction
. Передайте в него параметрыfunctionName = getXsollaPaymentToken
иFunctionParameter = PlayfabJsonObject
.
Отслеживание статуса заказа
Отслеживание статуса заказа требуется, чтобы убедиться, что оплата прошла успешно, и начислить товары пользователю.
Получение статуса заказа на клиентской части
Чтобы отслеживать изменения статуса заказа, используйте в клиентской части приложения метод SDK CheckPendingOrder
. Передайте в метод следующие параметры:
AuthToken
— авторизационный токен пользователя;OrderId
— ID заказа, полученный в результате покупки через корзину, покупки в один клик или покупки за виртуальную валюту;SuccessCallback
— функция, которая вызывается в случае перехода заказа в статусdone
;ErrorCallback
— функция, которая вызывается в случае, если сервер Xsolla возвращает ошибку.
Подробные сведения о работе метода приведены в разделе Отслеживание статуса заказа.
Получение статуса заказа на серверной части
SDK позволяет отслеживать статус заказа на клиентской части вашего приложения. Однако мы рекомендуем настроить обработку вебхука Успешный платеж и получать информацию о заказе на серверной части вашего приложения. Это позволит реализовать дополнительную валидацию совершенных покупок.
Полный список вебхуков и общая информация о работе с ними приведены в документации по вебхукам.
Чтобы настроить вебхуки на стороне Xsolla:
- Откройте проект в Личном кабинете.
- Нажмите Настройки проекта в боковом меню и перейдите в раздел Вебхуки.
- В поле Сервер для вебхуков укажите URL-адрес, на который Xsolla будет отправлять вебхуки.
Для тестирования вебхуков вы также можете выбрать любой специализированный сайт, например webhook.site, или платформу, например ngrok.
В целях тестирования, вы также можете добавить облачный скрипт, который будет имитировать успешную обработку вебхука. Код скрипта доступен на GitHub.
Для реального проекта вам потребуется добавить логику валидации покупки.
- Скопируйте и сохраните значение из поля Секретный ключ. Этот ключ генерируется по умолчанию и используется для подписи вебхуков. Если вы хотите изменить его, нажмите значок обновления.
- Нажмите Получать вебхуки.
Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.