Comment intégrer Pay Station avec l’authentification Firebase

Après avoir implémenté l’authentification utilisateur via Firebase dans votre application, générez un jeton de paiement côté Firebase, puis passez-le au client de l’application pour ouvrir l’interface de paiement.

Cette option d’intégration implique l’implémentation indépendante de la logique pour déterminer le pays de l’utilisateur et la devise de paiement.

Flux d’intégration :

1. Créez un projet.

1. Inscrivez un Compte éditeur et créez un nouveau projet. L'ID du projet créé sera nécessaire aux étapes suivantes.

2. Configurez un catalogue :
   • Créez un catalogue des objets côté Xsolla. Ajoutez des objets manuellement ou importez-les depuis Google Play ou PlayFab.
   • En utilisant la bibliothèque Store, implémentez la récupération et l'affichage du catalogue côté client de l'application.

3. Configurez l'achat d'un objet :
   • À l'aide de Cloud Functions Firebase, créez une commande avec les données utilisateur et les données de l'objet côté client de l'application.
   • Implémentez l'ouverture de l'interface de paiement côté client de l'application en utilisant la bibliothèque Payments.

4. Implémentez le suivi de l'état de la commande.

Utilisez le modèle de l’application Web comme référence pour implémenter l’intégration de l’authentification Firebase avec Pay Station. Le code source du modèle se trouve sur GitHub.

Créer un projet

S'inscrire au Compte éditeur

Le Compte éditeur est l’outil principal pour configurer les fonctionnalités Xsolla, ainsi que pour gérer les analyses et les transactions.

Les informations relatives à votre entreprise et à votre application fournies lors de l’inscription seront utilisées pour créer un projet de contrat de licence avec Xsolla et pour générer des recommandations sur les solutions adaptées à vos besoins. Bien que vous puissiez modifier ces informations ultérieurement, les fournir correctement lors de l’inscription accélérera le processus de signature du contrat de licence.

Pour vous inscrire, accédez au Compte éditeur et créez un compte.

Créer un projet dans le Compte éditeur

Si vous gérez plusieurs applications, nous vous recommandons de créer un projet distinct pour chacune d’entre elles. En fonction des informations fournies lors de la création du projet, Xsolla génère des recommandations adaptées à vos besoins.

Pour créer un nouveau projet :

1. Ouvrez votre Compte éditeur.
2. Dans le menu latéral, cliquez sur Create project.

3. Entrez le nom de votre projet en anglais (obligatoire).

4. Sélectionnez un ou plusieurs plateformes de sortie pour votre jeu (obligatoire).
5. Ajoutez un lien vers votre jeu. Si votre jeu n'a pas encore de site Web, ajoutez un lien vers une ressource contenant des informations sur le jeu (obligatoire).
6. Choisissez le moteur de jeu.
7. Sélectionnez les options de monétisation que vous utilisez ou prévoyez d'utiliser.
8. Spécifiez si le jeu est déjà publié. Si le jeu n'a pas encore été publié, indiquez la date de sortie prévue.
9. Cliquez sur Create project.

Au cours du processus d’intégration, vous devez fournir l’ID de projet. Il se trouve dans le Compte éditeur à côté du nom du projet.

Configurer le catalogue

Créer des objets dans le Compte éditeur

Pour ajouter un objet virtuel avec des paramètres de base au catalogue :

1. Ouvrez le projet dans le Compte éditeur.
2. Dans le menu latéral, cliquez sur Store.
3. Dans le volet Virtual Items, cliquez sur Connect.
4. Dans le menu déroulant, sélectionnez Create item.

5. Configurez les paramètres de base de l'objet dans les champs suivants :
   • Image (facultatif) ;
   • SKU (ID unique de l'objet) ;
   • Item name ;
   • Description (facultatif).

6. Spécifiez le prix de l'objet :
   1. Réglez la bascule Price in real currency sur On.
   2. Dans le champ Default currency, modifiez la devise (facultatif) et spécifiez le prix de l'objet.
   3. Si vous avez changé la devise dans le champ Default currency, sélectionnez la même devise dans le champ Price in real currency.

7. Changez le statut de l'objet en Available.

8. Cliquez sur Create item.

Afficher le catalogue côté client de l'application

1. Ajoutez la bibliothèque Store à votre projet. Pour ce faire, ouvrez le fichier build.gradle et ajoutez la ligne suivante à la section des dépendances :

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

2. Côté client de l'application, ajoutez une interface pour afficher le catalogue des objets.
3. Implémentez la demande du catalogue des objets depuis les serveurs Xsolla.

Exemple (classe StoreActivity du modèle de l’application Web) :

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

Dans le bloc d’initialisation XStore.init() du script, spécifiez l’ID du projet, qui se trouve dans le Compte éditeur à côté du nom du projet.

Configurer l'achat d'objets

Créer une commande à l'aide d'une Cloud Function

Pour créer une commande avec les données utilisateur et les données de l’objet côté Xsolla, ajoutez une Cloud Function au projet qui utilise l’appel API Créer un jeton de paiement pour un achat. Cet appel renverra un jeton de paiement, nécessaire pour ouvrir l’interface de paiement et effectuer un achat.

Limites :

• Lors de la demande du jeton de paiement, vous devez passer soit le pays de l’utilisateur, soit l’adresse IP.
• Si vous ne passer pas la devise dans le jeton, elle se détermine en fonction du pays.
• Si vous passez la devise dans le jeton, l’utilisateur paie dans cette devise.

Pour ajouter une Cloud Fonction à un projet :

1. Installez l'interface CLI (Command-Line Interface) de Firebase. Pour ce faire, exécutez la commande CLI :

npm install -g firebase-tools

2. Pour lier votre projet au projet Firebase, initialisez le projet Firebase en exécutant la commande CLI :

firebase init functions

1. Suivez les instructions de l'installateur pour configurer les paramètres :
   1. Sélectionnez une base de code existante ;
   2. Spécifiez JavaScript comme langage pour créer des Cloud Functions.
   3. Installez les dépendances.

3. Ouvrez le fichier functions/index.js et modifiez-le :

// 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. Dans le script, spécifiez les valeurs pour les variables :
   • projectId — l'ID du projet, qui se trouve dans le Compte éditeur à côté du nom du projet.

1. • apiKey – Clé API. Elle ne s'affiche dans le Compte éditeur qu'une seule fois lors de sa création, vous devez donc la conserver de votre côté. Vous pouvez créer une nouvelle clé dans les sections suivantes :
     • Company settings > API keys ;
     • Project settings > API keys.

4. Pour tester la Cloud Function avec l'émulateur, exécutez la commande CLI :

firebase emulators:start

1. Après avoir exécuté la Cloud Function, vous pouvez appeler les méthodes suivantes côté client de l'application :
   • getXsollaPaymentToken — renvoie le jeton de paiement pour ouvrir l'interface de paiement ;
   • webhookFakeResponse — envoie le code HTTP 200 en réponse au webhook Paiement. La méthode ne contient pas de logique de validation d'achat : utilisez-la uniquement à des fins de test. Pour accéder à la liste complète des webhooks et obtenir des informations générales sur leur utilisation, consultez la documentation sur les webhooks.

1. Pour appeler les méthodes localement, utilisez les URL suivantes : https://localhost:5001/{firebase-project-id}/us-central1/getXsollaPaymentToken et https://localhost:5001/{firebase-project-id}/us-central1/webhookFakeResponse, où {firebase-project-id} est l'ID du projet Firebase (Firebase console > Project Settings > Project ID).

5. Pour déployer la Cloud Function en production, exécutez la commande CLI :

firebase deploy --only functions

1. Une fois le déploiement en production effectué, vous pouvez appeler les méthodes via les URL https://us-central1-{firebase-project-id}.cloudfunctions.net/getXsollaPaymentToken et https://us-central1-{firebase-project-id}.cloudfunctions.net/webhookFakeResponse, où {firebase-project-id} est l'ID du projet Firebase (Firebase console > Project Settings > Project ID). Pour plus de détails sur l'exécution de cette fonctionnalité en production, consultez la documentation Firebase.

Configurer le lancement de l'interface de paiement

1. Ajoutez la bibliothèque Payments à votre projet. Pour ce faire, ouvrez le fichier build.gradle et ajoutez la ligne suivante à la section des dépendances :

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

2. Ouvrez le fichier AndroidManifest.xml et ajoutez l'autorisation d'accès à Internet :

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

3. Ajoutez la logique pour créer une commande (en appelant la méthode XStore.getXsollaPaymentToken de la Cloud Function) et pour ouvrir l'interface de paiement avec le jeton de paiement reçu (classe XPayments.createIntentBuilder()).

1. Pour appeler la méthode getXsollaPaymentToken, fournissez l'une des URLs suivantes, où {firebase-project-id} est l'ID du projet Firebase (Firebase console > Project Settings > Project ID) :
   • pour un accès local — https://localhost:5001/{firebase-project-id}/us-central1/getXsollaPaymentToken ;
   • pour un accès en production — https://us-central1-{firebase-project-id}.cloudfunctions.net/getXsollaPaymentToken.

Exemple (classe BuyItemAdapter du modèle de l’application Web) :

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. Ajoutez la méthode onActivityResult() pour traiter le résultat du paiement.

Exemple (classe StoreActivity du modèle de l’application Web) :

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

Configurer le suivi de l'état de la commande

Le suivi de l’état de la commande est requis pour s’assurer de la réussite du paiement et pour octroyer les objets à l’utilisateur.

Obtenir l'état de la commande côté client

Pour vous abonner aux changements d’état de la commande côté client de l’application, appelez la méthode XStore.getOrderStatus et passez à celle-ci les paramètres suivants :

• listener — un objet écouteur de type OrderStatusListener ;
• orderId — l'ID de commande reçu lors de l'achat via le panier, l'achat en un clic ou l'achat avec de la monnaie virtuelle.

Pour des informations détaillées sur le fonctionnement de la méthode, consultez la section Track order status.

Obtenir l'état de la commande côté serveur

Pour configurer les webhooks côté Xsolla :

1. Ouvrez le projet dans le Compte éditeur.
2. Dans le menu latéral, cliquez sur Project settings et accédez à la section Webhooks.
3. Dans le champ Webhook server, entrez l’URL vers laquelle Xsolla enverra les webhooks.

4. Copiez et enregistrez la valeur du champ Secret key. Cette clé générée par défaut s'utilise pour signer les webhooks. Si vous souhaitez la modifier, cliquez sur l'icône de mise à jour.
5. Cliquez sur Enable webhooks.