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

SDK enterprise-уровня для Unity

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

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

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

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

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

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

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

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

Внимание

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

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

В качестве примера реализации совместного использования аутентификации Firebase и Pay Station используйте тестовое приложение. Исходный код тестового приложения доступен на GitHub.

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

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

Личный кабинет — основной инструмент для настройки возможностей 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 Создание платежного токена для покупки. Этот метод вернет платежный токен, который потребуется для открытия платежного интерфейса и совершения оплаты.

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

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

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

Добавление облачной функции в проект Firebase

  1. Установите Firebase CLI (Command-Line Interface — командная строка), для этого выполните CLI-команду:

Copy
Full screen
Small screen
    npm install -g firebase-tools
    

    1. Чтобы связать ваш проект с проектом Firebase, инициализируйте проект Firebase, для этого выполните CLI-команду:

    Copy
    Full screen
    Small screen
      firebase init functions
      

      1. Следуйте указаниям установщика, чтобы задать настройки:
        1. Выберите существующую кодовую базу.
        2. Укажите JavaScript в качестве языка создания облачных функций.
        3. Установите зависимости.

      1. Откройте файл functions/index.js и измените его:

      Copy
      Full screen
      Small screen
      // The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
      const functions = require('firebase-functions/v1');
      
      const projectId = <projectId>;
      const apiKey = <apiKey>;
      
      exports.getXsollaPaymentToken = functions.https.onRequest((req, res) => {
      
        const requestBody = req.body;
          if (!requestBody) {
            res.status(400).send('Request body is missing');
            return;
          }
      
        const userId = requestBody.data.uid;
        const email = requestBody.data.email;
        const sku = requestBody.data.sku;
        const returnUrl = requestBody.data.returnUrl;
      
        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/v3/project/" + projectId.toString() + "/admin/payment/token";
      
        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 {
            throw new Error(`HTTP request failed with status ${xsollaRes.status} and statusText: ${xsollaRes.statusText}`)
          }
        })
        .then(data => {
          res.send(JSON.stringify(data));
        })
        .catch(error => {
          res.send("Error = " + error);
        });
      });
      
      exports.webhookFakeResponse = functions.https.onRequest((request, response) => {
        response.status(200).send()
      })
      

      1. В скрипте укажите значения для переменных:
        • projectId — ID проекта, который можно найти в Личном кабинете рядом с названием проекта.

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

      1. Чтобы протестировать работу облачной функции с помощью эмулятора, используйте CLI-команду:

      Copy
      Full screen
      Small screen
        firebase emulators:start
        

        1. После запуска облачной функции  вы можете вызывать в клиентской части вашего приложения следующие методы:
          • getXsollaPaymentToken — возвращает платежный токен для открытия платежного интерфейса.
          • webhookFakeResponse — отправляет 200 HTTP-код в ответ на вебхук Успешный платеж. Метод не содержит логику валидации покупки и используется только для тестирования. Полный список вебхуков и общая информация о работе с ними приведена в документации по вебхукам.

        1. Локально методы доступны для вызова по URL-адресам https://localhost:5001/{firebase-project-id}/us-central1/getXsollaPaymentToken и https://localhost:5001/{firebase-project-id}/us-central1/webhookFakeResponse, где {firebase-project-id} — ID проекта Firebase (консоль Firebase > Project Settings > Project ID).

        1. Чтобы запустить облачную функцию в боевой среде, используйте CLI-команду:

        Copy
        Full screen
        Small screen
          firebase deploy --only functions
          

          1. После запуска в боевой среде методы станут доступны для вызова по URL-адресам https://us-central1-{firebase-project-id}.cloudfunctions.net/getXsollaPaymentToken и https://us-central1-{firebase-project-id}.cloudfunctions.net/webhookFakeResponse, где {firebase-project-id} — ID проекта Firebase (консоль Firebase > Project Settings > Project ID). Подробная информация о запуске функции в боевой среде приведена в документации Firebase.

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

          1. Откройте ваш проект Unity.
          2. Внесите изменения в скрипт контроллера страницы:
            1. Добавьте метод вызова облачной функции MakeCloudFunctionRequest. Для вызова метода getXsollaPaymentToken укажите один из следующих URL-адресов, где {firebase-project-id} — ID проекта Firebase (консоль Firebase > Project Settings > Project ID):

              • для локального доступа — https://localhost:5001/{firebase-project-id}/us-central1/getXsollaPaymentToken;
              • для доступа в боевой среде — https://us-central1-{firebase-project-id}.cloudfunctions.net/getXsollaPaymentToken.

          Copy
          Full screen
          Small screen
          IEnumerator MakeCloudFunctionRequest(string sku)
             {
                 string url = "https://localhost:5001/{firebase-project-id}/us-central1/getXsollaPaymentToken";
          
                 using (UnityWebRequest webRequest = UnityWebRequest.Get(url))
                 {
                     var userData = new UserData()
                     {
                         data = new UserData.Data() {
                             uid = user.UserId,
                             email = user.Email,
                             sku = sku,
                             returnUrl = "app://xpayment.com.xsolla.unitysample"
                         }
                     };
          
                     byte[] data = System.Text.Encoding.UTF8.GetBytes(JsonUtility.ToJson(userData, true));
                     UploadHandlerRaw upHandler = new UploadHandlerRaw(data);
                     upHandler.contentType = "application/json";
                     webRequest.uploadHandler = upHandler;
                     webRequest.method = "POST";
                     yield return webRequest.SendWebRequest();
          
                     if (webRequest.result != UnityWebRequest.Result.Success)
                     {
                         Debug.LogError("Error: " + webRequest.error);
                     }
                     else
                     {
                         var paymentToken = "";
                         XsollaWebBrowser.OpenPurchaseUI(
                                 paymentToken,
                                 false);
                         Debug.Log("Response: " + webRequest.downloadHandler.text);
                     }
                 }
             }
          

            1. Добавьте вызов облачной функции при нажатии кнопки покупки товара:

          Copy
          Full screen
          Small screen
          private void OnItemsRequestSuccess(StoreItems storeItems)
              {
                  foreach (var storeItem in storeItems.items)
                  {
                      var widgetGo = Instantiate(WidgetPrefab, WidgetsContainer, false);
                      var widget = widgetGo.GetComponent<StoreItemWidget>();
          
                      widget.BuyButton.onClick.AddListener(() =>
                      {
                          StartCoroutine(MakeCloudFunctionRequest(storeItem.sku));
                      });
          
                      widget.NameText.text = storeItem.name;
                      widget.DescriptionText.text = storeItem.description;
          
                      if (storeItem.price != null)
                      {
                          var realMoneyPrice = storeItem.price;
                          widget.PriceText.text = $"{realMoneyPrice.amount} {realMoneyPrice.currency}";
                      }
          
                      ImageLoader.LoadSprite(storeItem.image_url, sprite => widget.IconImage.sprite = sprite);
                  }
              }
          

          Вы можете использовать тестовый проект в качестве примера реализации. Исходный код проекта Unity доступен на GitHub.

          Пример скрипта контроллера страницы:

          Copy
          Full screen
          Small screen
          using Firebase.Extensions;
          using System;
          using System.Collections;
          using UnityEngine;
          using UnityEngine.Networking;
          using UnityEngine.UI;
          using Xsolla.Catalog;
          using Xsolla.Core;
          
          [Serializable]
          public class UserData
          {
              public Data data;
          
              [Serializable]
              public class Data
              {
                  public string uid;
                  public string email;
                  public string sku;
                  public string returnUrl;
              }
          }
          
          public class FirebaseExamplePage : MonoBehaviour
          {
              public GameObject LoginContainer;
              public GameObject StoreItemsContainer;
          
              public InputField EmailInputField;
              public InputField PasswordInputField;
              public Button LoginButton;
              public Button RegisterButton;
          
              public Transform WidgetsContainer;
              public GameObject WidgetPrefab;
          
              protected Firebase.Auth.FirebaseAuth auth;
              Firebase.Auth.FirebaseUser user = null;
          
              Firebase.DependencyStatus dependencyStatus = Firebase.DependencyStatus.UnavailableOther;
          
              public virtual void Start()
              {
                  Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWithOnMainThread(task => {
                      dependencyStatus = task.Result;
                      if (dependencyStatus == Firebase.DependencyStatus.Available)
                      {
                          InitializeFirebase();
                      }
                      else
                      {
                          Debug.LogError(
                            "Could not resolve all Firebase dependencies: " + dependencyStatus);
                      }
                  });
              }
          
              protected void InitializeFirebase()
              {
                  StoreItemsContainer.SetActive(false);
          
                  Debug.Log("Setting up Firebase Auth");
                  auth = Firebase.Auth.FirebaseAuth.DefaultInstance;
                  auth.StateChanged += AuthStateChanged;
                  RegisterButton.onClick.AddListener(() =>
                  {
                      auth.CreateUserWithEmailAndPasswordAsync(EmailInputField.text, PasswordInputField.text).ContinueWith(task =>
                      {
                          if (task.IsCanceled)
                          {
                              Debug.LogError("CreateUserWithEmailAndPasswordAsync was canceled.");
                              return;
                          }
                          if (task.IsFaulted)
                          {
                              Debug.LogError("CreateUserWithEmailAndPasswordAsync encountered an error: " + task.Exception);
                              return;
                          }
          
                          Firebase.Auth.AuthResult result = task.Result;
                          Debug.LogFormat("Firebase user created successfully: {0} ({1})",
                              result.User.DisplayName, result.User.UserId);
                      });
                  });
          
                  LoginButton.onClick.AddListener(() =>
                  {
                      auth.SignInWithEmailAndPasswordAsync(EmailInputField.text, PasswordInputField.text).ContinueWith(task =>
                      {
                          if (task.IsCanceled)
                          {
                              Debug.LogError("SignInWithEmailAndPasswordAsync was canceled.");
                              return;
                          }
                          if (task.IsFaulted)
                          {
                              Debug.LogError("SignInWithEmailAndPasswordAsync encountered an error: " + task.Exception);
                              return;
                          }
          
                          Firebase.Auth.AuthResult result = task.Result;
                          Debug.LogFormat("Firebase user logged in successfully: {0} ({1})",
                              result.User.DisplayName, result.User.UserId);
                      });
                  });
              }
          
              void AuthStateChanged(object sender, System.EventArgs eventArgs)
              {
                  Firebase.Auth.FirebaseAuth senderAuth = sender as Firebase.Auth.FirebaseAuth;
                  if (senderAuth == auth && senderAuth.CurrentUser != user)
                  {
                      bool signedIn = user != senderAuth.CurrentUser && senderAuth.CurrentUser != null;
                      if (!signedIn && user != null)
                      {
                          Debug.Log("Signed out " + user.UserId);
                      }
                      user = senderAuth.CurrentUser;
                      if (signedIn)
                      {
                          Debug.Log("AuthStateChanged Signed in " + user.UserId);
                          LoadCatalog();
                      }
                  }
              }
          
              void OnDestroy()
              {
                  if (auth != null)
                  {
                      auth.SignOut();
                      auth.StateChanged -= AuthStateChanged;
                      auth = null;
                  }
              }
              private void LoadCatalog()
              {
                  LoginContainer.SetActive(false);
                  StoreItemsContainer.SetActive(true);
                  XsollaCatalog.GetCatalog(OnItemsRequestSuccess, OnError);
              }
          
              private void OnItemsRequestSuccess(StoreItems storeItems)
              {
          
                  foreach (var storeItem in storeItems.items)
                  {
                      var widgetGo = Instantiate(WidgetPrefab, WidgetsContainer, false);
                      var widget = widgetGo.GetComponent<StoreItemWidget>();
          
                      if(widget != null)
                      {
                          widget.NameText.text = storeItem.name;
                          widget.DescriptionText.text = storeItem.description;
          
                          widget.BuyButton.onClick.AddListener(() =>
                          {
                              StartCoroutine(MakeCloudFunctionRequest(storeItem.sku));
                          });
          
                          if (storeItem.price != null)
                          {
                              var realMoneyPrice = storeItem.price;
                              widget.PriceText.text = $"{realMoneyPrice.amount} {realMoneyPrice.currency}";
                          }
          
                          ImageLoader.LoadSprite(storeItem.image_url, sprite => widget.IconImage.sprite = sprite);
                      }
                  }
              }
              IEnumerator MakeCloudFunctionRequest(string sku)
              {
                  string url = "https://localhost:5001/{firebase-project-id}/us-central1/getXsollaPaymentToken";
          
                  using (UnityWebRequest webRequest = UnityWebRequest.Get(url))
                  {
                      var userData = new UserData()
                      {
                          data = new UserData.Data() {
                              uid = user.UserId,
                              email = user.Email,
                              sku = sku,
                              returnUrl = "app://xpayment.com.xsolla.unitysample"
                          }
                      };
          
                      byte[] data = System.Text.Encoding.UTF8.GetBytes(JsonUtility.ToJson(userData, true));
                      UploadHandlerRaw upHandler = new UploadHandlerRaw(data);
                      upHandler.contentType = "application/json";
                      webRequest.uploadHandler = upHandler;
                      webRequest.method = "POST";
                      yield return webRequest.SendWebRequest();
          
                      if (webRequest.result != UnityWebRequest.Result.Success)
                      {
                          Debug.LogError("Error: " + webRequest.error);
                      }
                      else
                      {
                          string responseJson = webRequest.downloadHandler.text;
                          var responseData = JsonUtility.FromJson<OrderData>(responseJson);
          
                          var paymentToken = responseData.token;
                          int orderId = responseData.order_id;
          
                          XsollaWebBrowser.OpenPurchaseUI(
                                  paymentToken,
                                  false);
                          Debug.Log("Response: " + webRequest.downloadHandler.text);
                      }
                  }
              }
          
              private void OnError(Error error)
              {
                  Debug.LogError($"Error: {error.errorMessage}");
              }
          }
          

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

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

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

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

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

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

          Внимание

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

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

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

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

          Примечание

          Для тестирования вы можете указать https://us-central1-{firebase-project-id}.cloudfunctions.net/webhookFakeResponse, где  {firebase-project-id} — ID проекта Firebase (консоль Firebase > Project Settings > Project ID). В этом случае Firebase будет имитировать успешную обработку вебхука. Для реального проекта вам потребуется добавить логику валидации покупки.

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

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

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

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

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