Como usar o Pay Station em combinação com a autenticação Firebase

Se você já implementou a autenticação de usuários no seu aplicativo usando o Firebase, você pode gerar um token de pagamento no lado do Firebase e então passá-lo ao lado do cliente no aplicativo para abrir a interface de pagamento.

Usando essa opção de integração, você deve implementar a lógica para determinar o país e moeda do usuário a ser usado para pagar pela compra de forma independente.

Fluxo de integração:

1. Crie um projeto.

1. Cadastre sua Conta de Distribuidor e crie um novo projeto. Você precisará do ID do projeto criado nas próximas etapas.

2. Configure um catálogo:
   • Crie um catálogo de itens no lado Xsolla. Você pode adicionar itens manualmente ou importá-los do Google Play PlayFab.
   • Implemente a obtenção e exibição do catálogo no lado do cliente do aplicativo usando a biblioteca Store.

3. Configure a compra de um item:
   • Crie um pedido com os dados do usuário e do item no lado do cliente no aplicativo usando a função Firebase cloud.
   • Implemente a abertura da interface de pagamento no lado do cliente no seu aplicativo usando a biblioteca Payments.

4. Configure o rastreamento do status do pedido.

Use o aplicativo web de amostra como exemplo para implementar o uso combinado da autenticação Firebase e o Pay Station. O código fonte do aplicativo web de amostra está disponível no GitHub.

Criar projeto

Cadastre sua Conta de Distribuidor

A Conta de Distribuidor é a ferramenta principal para configurar recursos da Xsolla, bem como trabalhar com análises e transações.

Os dados sobre a empresa e o seu aplicativo especificados durante o cadastro serão usados para criar um rascunho de contrato de licenciamento com a Xsolla e para gerar recomendações sobre soluções que sejam mais adequadas a você. Você pode alterar os dados mais tarde, mas o fornecimento dos dados corretos durante o cadastro acelera o processo de assinatura do contrato de licenciamento.

Para se cadastrar, vá para Conta de Distribuidor e crie um conta.

Crie um projeto na Conta de Distribuidor

Caso tenha múltiplos aplicativos, recomendamos criar um projeto separado para cada aplicativo. Com base nos dados especificados durante a criação do projeto, a Xsolla gera recomendações sobre as soluções mais adequadas a você.

Para criar um novo projeto:

1. Abra a Conta de Distribuidor.
2. No menu lateral, clique em Create project.

3. Insira o nome do seu projeto em inglês (obrigatório).

4. Escolha uma ou várias plataformas de lançamento do seu jogo (obrigatório).
5. Adicione um link para o seu jogo. Se o seu jogo ainda não tiver um site, adicione um link para a fonte que inclui informações sobre o jogo (obrigatório).
6. Escolha a engine do jogo.
7. Escolha suas opções de monetização ou o plano utilizado.
8. Especifique se o jogo já foi lançado. Se o jogo não tiver sido lançado, especifique a data de lançamento planejada.
9. Clique em Create project. Você verá uma página com os produtos Xsolla recomendados para você.

Durante o processo de integração, você precisa fornecer o ID do projeto, que pode ser encontrado na Conta de Distribuidor ao lado do nome do seu projeto.

Configure o catálogo

Crie itens a Conta de Distribuidor

Para adicionar itens virtuais com configurações básicas ao catálogo:

1. Abra seu projeto na Conta de Distribuidor.
2. Clique em Store no menu lateral.
3. No painel Virtual Items, clique em Connect.
4. Na lista suspensa, selecione Create item.

5. Defina as configurações básicas do item nos seguintes campos:
   • Image (opcional)
   • SKU (ID único do item)
   • Item name
   • Description (opcional)

6. Especifique o preço do item:
   1. Defina a opção Price in real currency como On.
   2. No campo Default currency, altere a moeda (opcional) e especifique o preço do item.
   3. Se você alterou a moeda no campo Default currency, selecione a mesma moeda no campo Price in real currency.

7. Altere o status do item para Available.

8. Clique em Create item.

Exibição do catálogo no lado do cliente no aplicativo

1. Adicione a biblioteca Store ao seu projeto. Para fazer isso, abra build.gradle e adicione a seguinte linha à seção de dependências:

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

2. No lado do cliente no aplicativo, adicione a interface para exibir o catálogo de produtos.
3. Implemente a solicitação de catálogos de itens pelos servidores Xsolla.

Exemplo (classe StoreActivity do aplicativo web de amostra):

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()
    }
}

No bloco de inicialização XStore.init() do script, especifique o ID do projeto que você pode encontrar na Conta de Distribuidor próximo ao nome do projeto.

Configure a compra de itens

Crie um pedido usando a função cloud

Para criar um pedido com dados de usuário e item no lado Xsolla, adicione uma função cloud ao projeto que utiliza a chamada de API Criar token de pagamento para compra. Essa chamada retornará um token de pagamento, que é necessário para abrir a interface de pagamento e fazer uma compra.

Limitações:

• você precisa passar o país do usuário ou o endereço IP do usuário ao solicitar o token de pagamento.
• Se você não passar a moeda no token, ela é determinada pelo país.
• Se você passar a moeda no token, o usuário paga nessa concorrência.

Para adicionar uma função cloud a um projeto:

1. Para instalar o Firebase CLI (Command-Line Interface). Para fazer isso, execute o comando CLI:

npm install -g firebase-tools

2. Para vincular seu projeto ao projeto Firebase, inicialize o projeto Firebase executando o comando CLI:

firebase init functions

1. Siga as instruções do instalador para definir as configurações:
   1. Selecione um código de base existente.
   2. Especifique o JavaScript como idioma para criar funções cloud.
   3. Instale as dependências.

3. Abra functions/index.js e modifique-a:

// 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. No script, especifique os valores das variáveis:
   • projectId — ID do projeto que você pode encontrar na sua Conta de Distribuidor próximo ao nome do projeto.

1. • apiKey — Chave API. É mostrada na Conta de Distribuidor apenas uma vez, durante a criação, e deve ser armazenada por você. Você pode criar uma nova chave na seguinte seção:
     • Company settings > API keys
     • Project settings > API keys

4. Para testar a função cloud com o emulador, execute o comando CLI:

firebase emulators:start

1. Depois de executar a função cloud, você poderá chamar os seguintes métodos no lado do cliente do seu aplicativo:
   • getXsollaPaymentToken — retorna o token de pagamento por abrir a interface de pagamento.
   • webhookFakeResponse — envia o código HTTP 200 em resposta ao webook Payment. Esse método não contém uma lógica de validação de compra: use-o apenas para testes. Para uma lista completa de webhooks e informações gerais sobre como trabalhar com eles, consulte a documentação de webhooks.

1. Para chamar métodos localmente, use os URLs https://localhost:5001/{firebase-project-id}/us-central1/getXsollaPaymentToken e https://localhost:5001/{firebase-project-id}/us-central1/webhookFakeResponse, onde {firebase-project-id} é o ID do projeto Firebase (Firebase console > Project Settings > Project ID).

5. Para aplicar a função cloud na produção, execute o comando CLI:

firebase deploy --only functions

1. Uma vez aplicada na produção, você poderá chamar métodos pelos URLs https://us-central1-{firebase-project-id}.cloudfunctions.net/getXsollaPaymentToken e https://us-central1-{firebase-project-id}.cloudfunctions.net/webhookFakeResponse, onde {firebase-project-id} é o ID do projeto Firebase (Firebase console > Project Settings > Project ID). Para detalhes sobre como executar o recurso em produção, consulte a documentação Firebase.

Configure o lançamento da interface de pagamento

1. Adicione a biblioteca Payments ao seu projeto. Para fazer isso, abra build.gradle e adicione a seguinte linha à seção de dependências:

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

2. Abra AndroidManifest.xml e adicione a permissão de acesso à internet:

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

3. Adicione a lógica para criar um pedido (chamada do método XStore.getXsollaPaymentToken da função cloud) e abrir a interface de pagamento com o token de pagamento recebido (classe XPayments.createIntentBuilder()).

1. Para chamar o método getXsollaPaymentToken, forneça um dos seguintes URLs, onde {firebase-project-id} é o ID do projeto Firebase (Firebase console > Project Settings > Project ID):
   • para acesso local — https://localhost:5001/{firebase-project-id}/us-central1/getXsollaPaymentToken
   • para acesso na produção — https://us-central1-{firebase-project-id}.cloudfunctions.net/getXsollaPaymentToken

Exemplo (classe BuyItemAdapter do aplicativo web de amostra):

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. Adicione o método onActivityResult() para processar o resultado de pagamento.

Exemplo (classe StoreActivity do aplicativo web de amostra):

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")
            }
        }
    }

Configure o rastreamento de status de pedidos

É necessário rastrear o status do pedido para garantir que o pagamento foi bem-sucedido e para conceder itens ao usuário.

Obter status do pedido no lado do cliente

Para se inscrever nas alterações do status do pedido no lado do cliente no seu aplicativo, chame o método XStore.getOrderStatus e passe os seguintes parâmetros ao método:

• listener — um objeto ouvinte do tipo OrderStatusListener.
• orderId — o ID do pedido recebido na compra via carrinho de compras, compra de um clique ou compra de moedas virtuais.

Para informações detalhadas sobre como o método funciona, consulte a seção Rastreamento de status do pedido.

Obter status do pedido no lado do servidor

Para configurar webhooks no lado Xsolla:

1. Abra seu projeto na Conta de Distribuidor.
2. Clique em Project settings no menu lateral e vá para a seção Webhooks.
3. No campo Webhook server, insira o URL ao qual a Xsolla enviará os webhooks.

4. Copie e salve o valor do campo Secret key. Essa chave é gerada por padrão e é usada para assinar webhooks. Se quiser alterá-la, clique no ícone de atualização.
5. Clique em Enable webhooks.