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

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

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

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

1. Создайте проект.

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

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

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

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

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

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

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

Личный кабинет — основной инструмент для настройки возможностей 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. Добавьте в проект библиотеку Store. Для этого откройте файл build.gradle и добавьте следующую строку в раздел зависимостей:

implementation("com.xsolla.android:store:latest.release")

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

Пример (класс StoreActivity тестового веб-приложения):

package com.xsolla.androidsample

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.widget.Toast
import androidx.recyclerview.widget.LinearLayoutManager
import androidx.recyclerview.widget.RecyclerView
import com.xsolla.android.store.XStore
import com.xsolla.android.store.callbacks.GetVirtualItemsCallback
import com.xsolla.android.store.entity.response.items.VirtualItemsResponse
import com.xsolla.androidsample.adapter.BuyItemAdapter

class StoreActivity : AppCompatActivity() {

    private lateinit var itemsView: RecyclerView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_store)

        XStore.init(<projectId>)

        initUI()
        loadVirtualItems()
    }

    private fun initUI() {
        itemsView = findViewById(R.id.buy_recycler_view)
        itemsView.layoutManager = LinearLayoutManager(this)
    }

    private fun loadVirtualItems() {
        val parentActivity = this
        XStore.getVirtualItems(object : GetVirtualItemsCallback {
            override fun onSuccess(response: VirtualItemsResponse) {
                itemsView.adapter = BuyItemAdapter(parentActivity, response.items.filter { item -> item.virtualPrices.isEmpty() && !item.isFree })
            }

            override fun onError(throwable: Throwable?, errorMessage: String?) {
                showNotificationMessage(errorMessage ?: throwable?.javaClass?.name ?: "Error")
            }
        })
    }

    private fun showNotificationMessage(message: String) {
        Toast.makeText(
            baseContext,
            message,
            Toast.LENGTH_SHORT,
        ).show()
    }
}

В скрипте в блоке инициализации XStore.init() укажите ID проекта, который можно найти в Личном кабинете рядом с названием проекта.

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

Создание заказа с помощью облачной функции

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

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

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

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

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

npm install -g firebase-tools

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

firebase init functions

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

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

// 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 проекта, который можно найти в Личном кабинете рядом с названием проекта.

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

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

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).

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

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.

Реализация открытия платежного интерфейса

1. Добавьте в проект библиотеку Payments. Для этого откройте файл build.gradle и добавьте следующую строку в раздел зависимостей:

implementation("com.xsolla.android:payments:latest.release")

2. Откройте файл AndroidManifest.xml и добавьте разрешение для доступа к интернету:

<uses-permission android:name="android.permission.INTERNET" />

3. Добавьте логику формирования заказа (вызов метода XStore.getXsollaPaymentToken облачной функции) и открытия платежного интерфейса с полученным платежным токеном (класс XPayments.createIntentBuilder()).

1. Для вызова метода 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.

Пример (класс BuyItemAdapter тестового веб-приложения):

package com.xsolla.androidsample.adapter

import android.R.attr.duration
import android.os.Handler
import android.os.Looper
import android.view.LayoutInflater
import android.view.ViewGroup
import android.widget.Toast
import androidx.recyclerview.widget.RecyclerView
import com.bumptech.glide.Glide
import com.xsolla.android.payments.XPayments
import com.xsolla.android.payments.data.AccessToken
import com.xsolla.android.store.entity.response.items.VirtualItemsResponse
import com.xsolla.androidsample.R
import com.xsolla.androidsample.StoreActivity
import org.json.JSONObject
import java.io.BufferedReader
import java.io.BufferedWriter
import java.io.OutputStream
import java.io.OutputStreamWriter
import java.net.HttpURLConnection
import java.net.URL


class BuyItemAdapter(private val parentActivity: StoreActivity, private val items: List<VirtualItemsResponse.Item>) :
    RecyclerView.Adapter<BuyItemViewHolder>() {
    override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): BuyItemViewHolder {
        return BuyItemViewHolder( LayoutInflater.from(parent.context)
            .inflate(R.layout.buy_item_sample, parent, false))
    }

    override fun onBindViewHolder(holder: BuyItemViewHolder, position: Int) {
        val item = items[position]
        Glide.with(holder.view).load(item.imageUrl).into(holder.itemImage)
        holder.itemName.text = item.name
        holder.itemDescription.text = item.description
        var priceText: String
        if(item.virtualPrices.isNotEmpty()) {
            priceText = item.virtualPrices[0].getAmountRaw() + " " + item.virtualPrices[0].name
        } else {
            priceText = item.price?.getAmountRaw() + " " + item.price?.currency.toString()
        }

        holder.itemPrice.text = priceText

        holder.itemButton.setOnClickListener {
            Thread {
                purchase(item.sku!!)
            }.start()
        }
    }

    private fun purchase(sku: String) {

        val uid = parentActivity.intent.getStringExtra("uid")
        val email = parentActivity.intent.getStringExtra("email")

        val jsonBody = JSONObject()
        jsonBody.put("data", JSONObject().apply {
            put("uid", uid)
            put("email", email)
            put("sku", sku)
            put("returnUrl", "app://xpayment." + parentActivity.packageName)
        })

        val connection = URL(https://localhost:5001/{firebase-project-id}/us-central1/getXsollaPaymentToken).openConnection() as HttpURLConnection
        connection.requestMethod = "POST"
        connection.setRequestProperty("Content-Type", "application/json")
        connection.doOutput = true

        val outputStream: OutputStream = connection.outputStream
        val writer = BufferedWriter(OutputStreamWriter(outputStream))
        writer.write(jsonBody.toString())
        writer.flush()
        writer.close()

        val responseCode = connection.responseCode

        if (responseCode == HttpURLConnection.HTTP_OK) {
            val response = connection.inputStream.bufferedReader().use(BufferedReader::readText)
            connection.disconnect()

            val jsonObject = JSONObject(response)
            val token = jsonObject.getString("token")
            val orderId = jsonObject.getString("order_id")

            val intent = XPayments.createIntentBuilder(parentActivity)
                .accessToken(AccessToken(token))
                .isSandbox(true)
                .build()
            parentActivity.startActivityForResult(intent, 1)
        } else {
            Handler(Looper.getMainLooper()).post {
                showNotificationMessage("HTTP request failed with error: $responseCode")
            }
        }
    }

    override fun getItemCount() = items.size

    private fun showNotificationMessage(message: String) {
        Toast.makeText(
            parentActivity,
            message,
            Toast.LENGTH_SHORT,
        ).show()
    }
}

4. Добавьте метод onActivityResult() для обработки результата платежа.

Пример (класс StoreActivity тестового веб-приложения):

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
        super.onActivityResult(requestCode, resultCode, data)
        if (requestCode == 1) {
            val (status, _) = XPayments.Result.fromResultIntent(data)
            when (status) {
                XPayments.Status.COMPLETED -> showNotificationMessage("Payment completed")
                XPayments.Status.CANCELLED -> showNotificationMessage("Payment canceled")
                XPayments.Status.UNKNOWN -> showNotificationMessage("Payment error")
            }
        }
    }

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

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

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

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

• listener — объект слушателя типа OrderStatusListener;
• orderId — ID заказа, полученный в результате покупки через корзину, покупки в один клик или покупки за виртуальную валюту.

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

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

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

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

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