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

SDK для Unity

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

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

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

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

Примечание

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

  1. Задайте настройки нового проекта:
    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.

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

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

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

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

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

      Copy
      Full screen
      Small screen
      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
          }
      }
      

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

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

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

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

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

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

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

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

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

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

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

      Внимание

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

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

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

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

      Примечание

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

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

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

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

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

      В другой раз

      Спасибо за обратную связь!
      Последнее обновление: 5 апреля 2024

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

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