Cómo usar Pay Station en combinación con la autenticación de Firebase

Si ya ha implementado la autenticación de usuario en su aplicación usando Firebase, puede generar un token de pago en el lado de Firebase y, luego, transmitirlo al lado del cliente de la aplicación para abrir la interfaz de pago.

Al usar esta opción de integración, debe implementar de forma independiente la lógica para determinar el país y la moneda del usuario para abonar la compra.

Flujo de integración:

1. Crear un proyecto.

1. Regístrese en Cuenta del editor y cree un nuevo proyecto. Necesitará el ID del proyecto creado para pasos posteriores.

2. Establecer un catálogo:
   • Cree un catálogo de artículos en el lado de Xsolla. Puede agregar artículos manualmente o importarlos desde Google Play o PlayFab.
   • Implemente la obtención y visualización del catálogo en el lado del cliente de la aplicación usando la biblioteca de Store.

3. Establecer la compra de un artículo:
   • Cree un pedido con los datos del usuario y del artículo en el lado del cliente de la aplicación usando la función de nube de Firebase.
   • Implemente la apertura de la interfaz de pago en el lado del cliente de su aplicación mediante la biblioteca de Payments.

4. Establecer un seguimiento del estado del pedido.

Utilice la aplicación web de muestra como ejemplo para implementar el uso combinado de la autenticación de Firebase y Pay Station. El código fuente de la aplicación web de muestra está disponible en GitHub.

Crear proyecto

Registrarse en Cuenta del editor

Cuenta del editor es la herramienta fundamental para configurar las funciones de Xsolla, así como para operar con los análisis y las transacciones.

Los datos sobre la empresa y su aplicación indicados durante el registro se usarán para crear un borrador de acuerdo de licencia con Xsolla y para generar recomendaciones sobre las soluciones que se adaptan a sus necesidades. Puede modificar los datos después, pero si facilita los datos correctos al registrarse, se acelerará el proceso de firma del acuerdo de licencia.

Para registrarse, acceda a Cuenta del editor y cree una cuenta.

Crear proyecto en Cuenta del editor

Si tiene varias aplicaciones, recomendamos crear un proyecto independiente para cada una de ellas. A partir de los datos especificados durante la creación del proyecto, Xsolla genera recomendaciones sobre soluciones que se adaptan a sus necesidades.

Para crear un nuevo proyecto:

1. Abra Cuenta del editor.
2. En el menú lateral, haga clic en Create project.

3. Introduzca el nombre de su proyecto en inglés (obligatorio).

4. Seleccione una o varias plataformas de lanzamiento de su juego (obligatorio).
5. Agregue un enlace a su juego. Si su juego aún no tiene sitio web, agregue un enlace al código fuente que incluya información sobre el juego (obligatorio).
6. Seleccione el motor del juego.
7. Seleccione las opciones de monetización que utiliza o prevé utilizar.
8. Especifique si el juego ya se ha lanzado. Si el juego aún no se ha lanzado, especifique la fecha de lanzamiento prevista.
9. Haga clic en Create project. Podrá ver una página con los productos de Xsolla que le recomendamos.

Durante el proceso de integración, debe proporcionar el ID del proyecto que se encuentra en su Cuenta del editor junto al nombre del proyecto.

Establecer catálogo

Crear artículos en Cuenta del editor

Para agregar un artículo virtual con la configuración básica al catálogo:

1. Abra su proyecto en Cuenta del editor.
2. Haga clic en Store en el menú lateral.
3. En el panel Virtual items, haga clic en Connect.
4. En el menú desplegable, seleccione Create item.

5. Establezca la configuración básica del artículo en los siguientes campos:
   • Image (opcional)
   • SKU (ID único del artículo)
   • Item name
   • Description (opcional)

6. Especificar el precio del artículo:
   1. Establezca el conmutador Price in real currency en On.
   2. En el campo Default currency, cambie la moneda (opcional) y especifique el precio del artículo.
   3. Si cambió la moneda en el campo Default currency, seleccione la misma moneda en el campo Price in real currency.

7. Cambie el estado del artículo a Available.

8. Haga clic en Create item.

Visualizar el catálogo en el lado del cliente de la aplicación

1. Agregue la biblioteca de Store a su proyecto. Para ello, abra build.gradle y agregue la siguiente línea a la sección de dependencias:

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

2. En el lado del cliente de la aplicación, agregue una interfaz de usuario para visualizar el catálogo de productos.
3. Implemente la solicitud de un catálogo de artículos a los servidores de Xsolla.

Ejemplo (clase StoreActivity de la aplicación web de muestra):

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

En el bloque de inicialización XStore.init() del script, especifique el ID del proyecto que puede encontrar en su Cuenta del editor junto al nombre del proyecto.

Establecer la compra de artículos

Crear pedido mediante la función de nube

Para crear un pedido con los datos del usuario y del artículo en el lado de Xsolla, agregue al proyecto una función de nube que use la llamada API Crear token de pago para la compra. Esta llamada devolverá un token de pago, el cual es necesario para abrir la interfaz de pago y hacer una compra.

Limitaciones:

• Necesita transmitir el país del usuario o la dirección IP del usuario cuando se solicite el token de pago.
• Si no transmite la moneda en el token, esta se determinaré en función del país.
• Si transmite la moneda en el token, el usuario paga con esta moneda.

Para agregar una función de nube a un proyecto:

1. Instale la CLI (interfaz de línea de comandos) de Firebase. Para hacerlo, ejecute el comando CLI:

npm install -g firebase-tools

2. Para vincular su proyecto al proyecto de Firebase, inicialice el proyecto de Firebase ejecutando el comando CLI:

firebase init functions

1. Siga las instrucciones del instalador para configurar los ajustes:
   1. Seleccione un código base existente.
   2. Defina JavaScript como el lenguaje empleado para crear funciones de nube.
   3. Instale las dependencias.

3. Abra el functions/index.js y modifíquelo:

// 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. En el script, especifique los valores para las variables:
   • projectId: ID del proyecto que puede encontrar en su Cuenta del editor junto al nombre del proyecto.

1. • apiKey: clave de API. se muestra en la Cuenta del editor solo una vez cuando se crea, y debe almacenarse en su lado. Puede crear una nueva clave en la siguiente sección:
     • Company settings > API keys
     • Project settings > API keys

4. Para probar la función de nube con el emulador, ejecute el comando CLI:

firebase emulators:start

1. Después de ejecutar la función de nube, puede hacer una llamada a los siguientes métodos en el lado del cliente de su aplicación:
   • getXsollaPaymentToken: devuelve el token de pago para abrir la interfaz de pago.
   • webhookFakeResponse: envía el código HTTP 200 en respuesta al webhook Payment. El método no contiene una lógica de validación de compra: úselo solo para las pruebas. Para obtener la lista completa de webhooks e información general sobre cómo operar con ellos, consulte la documentación de webhooks.

1. Para llamar a los métodos de forma local, use las URL https://localhost:5001/{firebase-project-id}/us-central1/getXsollaPaymentToken y https://localhost:5001/{firebase-project-id}/us-central1/webhookFakeResponse, en los cuales {firebase-project-id} es el ID del proyecto de Firebase (Firebase console > Project Settings > Project ID).

5. Para implementar la función de nube en producción, ejecute el comando CLI:

firebase deploy --only functions

1. Cuando se haya implementado en producción, puede llamar a los métodos a través de las URL https://us-central1-{firebase-project-id}.cloudfunctions.net/getXsollaPaymentToken y https://us-central1-{firebase-project-id}.cloudfunctions.net/webhookFakeResponse, el los cuales {firebase-project-id} es el ID del proyecto de Firebase (Firebase console > Project Settings > Project ID). Para obtener más detalles sobre cómo ejecutar la función en producción, consulte la documentación de Firebase.

Establecer el lanzamiento de la interfaz de pago

1. Agregue la biblioteca de Payments a su proyecto. Para ello, abra build.gradle y agregue la siguiente línea a la sección de dependencias:

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

2. Abra AndroidManifest.xml y agregue el permiso para el acceso a Internet:

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

3. Agregue la lógica para la creación de un pedido (llamando al método XStore.getXsollaPaymentToken de la función de nube) y para abrir la interfaz de pago con el token de pago recibido (clase XPayments.createIntentBuilder()).

1. Para llamar al método getXsollaPaymentToken, facilite una de las siguientes URL, en las cuales {firebase-project-id} es el ID del proyecto de Firebase (Firebase console > Project Settings > Project ID):
   • para acceso local, https://localhost:5001/{firebase-project-id}/us-central1/getXsollaPaymentToken
   • para acceso en la producción, https://us-central1-{firebase-project-id}.cloudfunctions.net/getXsollaPaymentToken

Ejemplo (clase BuyItemAdapter de la aplicación web de muestra):

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. Agregue el método onActivityResult() para procesar el resultado del pago.

Ejemplo (clase StoreActivity de la aplicación web de muestra):

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

Establecer seguimiento del estado del pedido

Se requiere hacer el seguimiento del estado del pedido para garantizar que el pago se realizó correctamente y para conceder artículos al usuario.

Obtener el estado del pedido en el lado del cliente

Para suscribirse a los cambios de estado del pedido en el lado del cliente de su aplicación, haga una llamada al método XStore.getOrderStatus y transmita los siguientes parámetros al método:

• listener: un objeto agente de escucha del tipo OrderStatusListener.
• orderId: el ID del pedido recibido de la compra mediante la cesta de la compra; compra con un solo clic o compra a cambio de moneda virtual.

Para obtener información detallada sobre cómo funciona este método, consulte la sección Hacer seguimiento del estado del pedido.

Obtener el estado del pedido en el lado del servidor

Para configurar los webhooks en el lado de Xsolla:

1. Abra su proyecto en Cuenta del editor.
2. Haga clic en Project settings en el menú lateral y vaya a la sección Webhooks.
3. En el campo Webhook URL, ingrese la URL a la que Xsolla enviará los webhooks.

4. Copie y guarde el valor del campo Secret key. Esta clave se genera por defecto y se usa para firmar webhooks. Si desea cambiarla, haga clic en el icono de actualización.
5. Haga clic en Enable webhooks.