Как использовать 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. Нажмите Создать предмет.

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

1. Скачайте SDK с CDN или GitHub.
2. Распакуйте архив.
3. В главном меню редактора Unity выберите пункт Assets > Import Package > Custom Package и укажите скачанный SDK.
4. В главном меню выберите пункт Window > Xsolla > Edit Settings.
5. В панели Inspector в поле Project ID укажите ID проекта, который можно найти в Личном кабинете рядом с названием проекта.

6. В клиентской части приложения добавьте UI для отображения каталога товаров.
7. Реализуйте запрос каталога товаров с серверов Xsolla.

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

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

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

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

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

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

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

4. Задайте настройки нового проекта:
   1. Выберите язык для вашей функции — C#.
   2. Выберите среду выполнения .NET — .NET 8.0 Isolated (LTS).
   3. Выберите шаблон для первой функции вашего проекта — HTTP trigger.
   4. Укажите имя функции — GetXsollaPaymentToken.
   5. Укажите пространство имен — My.Functions.
   6. Уровень авторизации — Anonymous.
   7. Выберите, как вы хотите открыть свой проект — Open in current window.

1. В результате Visual Studio Code сгенерирует C#-проект и откроет созданный файл GetXsollaPaymentToken.cs.

5. Измените файл GetXsollaPaymentToken.cs:

using System.Text;
using System.Net.Http.Headers;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;

namespace My.Function
{
    public class GetXsollaPaymentToken
    {
        private readonly ILogger<GetXsollaPaymentToken> _logger;

        private const int PROJECT_ID = ""; // Your Xsolla project ID
        private const string API_KEY = ""; // Your Xsolla API key

        public GetXsollaPaymentToken(ILogger<GetXsollaPaymentToken> logger)
        {
            _logger = logger;
        }

        [Function("GetXsollaPaymentToken")]
        public async Task<IActionResult> Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req)
        {
            _logger.LogInformation("GetXsollaPaymentToken function processed a request.");

            // Reading the request body
            string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
            _logger.LogInformation("Request body: " + requestBody);

            // Deserializing request body JSON
            dynamic data = JsonConvert.DeserializeObject(requestBody);

            // Extracting necessary data from JSON
            string uid = data.FunctionArgument.uid;
            string sku = data.FunctionArgument.sku;
            string returnUrl = data.FunctionArgument.returnUrl;

            // Creating payload for Xsolla API
            var payload = new
            {
                user = new
                {
                    id = new { value = uid },
                    country = new { value = "US", allow_modify = false }
                },
                purchase = new
                {
                    items = new[]
                    {
                        new { sku = sku, quantity = 1 }
                    }
                },
                sandbox = true,
                settings = new
                {
                    language = "en",
                    currency = "USD",
                    return_url = returnUrl,
                    ui = new { theme = "63295aab2e47fab76f7708e3" }
                }
            };

            // Constructing Xsolla API URL
            string url = $"https://store.xsolla.com/api/v3/project/{PROJECT_ID}/admin/payment/token";

            // Sending request to Xsolla API
            using (HttpClient client = new HttpClient())
            {
                // Adding authorization header
                string headerValue = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{PROJECT_ID}:{API_KEY}"));
                client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", headerValue);

                // Serializing payload to JSON
                var jsonPayload = JsonConvert.SerializeObject(payload);
                var content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");

                // Making POST request to Xsolla API
                var xsollaRes = await client.PostAsync(url, content);

                // Checking response from Xsolla API
                if (xsollaRes.IsSuccessStatusCode)
                {
                    // Reading successful response content
                    string responseContent = await xsollaRes.Content.ReadAsStringAsync();
                    return new OkObjectResult(responseContent);
                }
                else
                {
                    // Returning status code in case of failure
                    return new StatusCodeResult((int)xsollaRes.StatusCode);
                }
            }
        }
    }
}

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 раздела Тестирование облачного скрипта).

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

1. Откройте ваш проект Unity.
2. Создайте скрипт XsollaPlayfabSample.cs со следующим содержимым:

using System;
using PlayFab;
using PlayFab.ClientModels;
using PlayFab.CloudScriptModels;
using UnityEngine;
using Xsolla.Core;

public class XsollaPlayfabSample : MonoBehaviour
{
    private void Start()
    {
        // Logging in anonymously
        LoginAnonymous(
            // Callback function invoked after successful login
            userId => {
                // Requesting Xsolla payment token
                GetXsollaPaymentToken(
                    userId, // PlayFab user ID received after login
                    "booster_max_1", // SKU of the product
                    orderData => {
                        // Creating Xsolla token and opening purchase UI
                        XsollaToken.Create(orderData.token);
                        XsollaWebBrowser.OpenPurchaseUI(orderData.token);

                        // Adding order for tracking
                        OrderTrackingService.AddOrderForTracking(
                            orderData.order_id,
                            true,
                            () => Debug.Log("Payment completed"),
                            onError => Debug.LogError(onError.errorMessage));
                    });
            });
    }

    private static void LoginAnonymous(Action<string> onSuccess)
    {
        // Logging in with custom ID
        PlayFabClientAPI.LoginWithCustomID(
            new LoginWithCustomIDRequest {
                CustomId = SystemInfo.deviceUniqueIdentifier, // Unique ID generated based on the device
                CreateAccount = true
            },
            result => {
                // Logging the result
                Debug.Log("Logged with playfab id: " + result.PlayFabId);

                // Invoking onSuccess callback with PlayFab ID
                onSuccess?.Invoke(result.PlayFabId);
            },
            error => { Debug.LogError(error.GenerateErrorReport()); }); // Handling login error
    }

    private static void GetXsollaPaymentToken(string userId, string sku, Action<OrderData> onSuccess)
    {
        // Creating request data for Xsolla payment token
        var tokenRequestData = new PaymentTokenRequestData {
            uid = userId, // User ID
            sku = sku, // Product SKU
            returnUrl = $"app://xpayment.{Application.identifier}" // Return URL
        };

        // Executing a function in the PlayFab cloud to get payment token
        PlayFabCloudScriptAPI.ExecuteFunction(
            new ExecuteFunctionRequest {
                FunctionName = "GetXsollaPaymentToken", // Name of Azure function
                FunctionParameter = tokenRequestData, // Data passed to the function
                GeneratePlayStreamEvent = false // Setting true if call should show up in PlayStream
            },
            result => {
                // Logging the result
                Debug.Log($"GetXsollaPaymentToken result: {result.FunctionResult}");

                // Parsing JSON result to OrderData object
                OrderData orderData = JsonUtility.FromJson<OrderData>(result.FunctionResult.ToString());

                // Invoking onSuccess callback with order data
                onSuccess?.Invoke(orderData);
            },
            error => Debug.LogError($"Error: {error.GenerateErrorReport()}")); // Handling error
    }

    // Class for payment token request data
    public class PaymentTokenRequestData
    {
        public string uid; // User ID
        public string sku; // Product SKU
        public string returnUrl; // Return URL
    }
}

3. Создайте новую сцену.
4. Создайте пустой игровой объект. Для этого в главном меню выберите пункт GameObject > Create Empty.

5. Добавьте скрипт к игровому объекту:
   1. Выберите объект в панели Hierarchy.
   2. В панели Inspector нажмите Add Component и выберите скрипт XsollaPlayfabSample.

6. Вызовите контекстное меню в панели Hierarchy и выберите UI > EventSystem.

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

Исходный код проекта Unity доступен на GitHub.

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

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

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

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

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

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

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

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

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