SDK pour Unity destinés aux entreprises / Comment intégrer Pay Station avec l'authentification PlayFab
  Retour à la documentation

SDK pour Unity destinés aux entreprises

Comment intégrer Pay Station avec l’authentification PlayFab

Après avoir implémenté l’authentification utilisateur via PlayFab dans votre application, générez un jeton de paiement côté PlayFab, 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.

  1. 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 le SDK, implémentez la récupération et l'affichage du catalogue côté client de l'application.

  1. Configurez l'achat d'un objet :
    • À l'aide d'un script cloud PlayFab, 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 le SDK.

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

Avis

Pour compléter l’intégration et commencer à accepter les paiements réels, vous devez signer un contrat de licence avec Xsolla.

Vous pouvez signer le contrat de licence à n’importe quelle étape de l’intégration, mais gardez à l’esprit que le processus d’examen peut prendre jusqu’à trois jours ouvrables.

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.

Note

Le mot de passe du Compte éditeur peut comprendre des lettres latines, des chiffres et des caractères spéciaux et doit contenir au moins :

  • 8 caractères ;
  • un chiffre ;
  • une lettre majuscule ;
  • une lettre minuscule.

Pour garantir la sécurité du mot de passe, nous recommandons de :

  • changer de mot de passe au moins tous les 90 jours ;
  • créer un nouveau mot de passe différent aux 4 derniers mots de passe utilisés pour votre compte ;
  • créer un mot de passe unique différent des mots de passe utilisés ailleurs ;
  • ne pas conserver votre mot de passe dans un endroit où il est facilement accessible ;
  • utiliser des gestionnaires de mots de passe pour stocker votre mot de passe.

Le Compte éditeur utilise une authentification à deux facteurs, qui consiste à envoyer un code de confirmation à chaque tentative d’authentification.

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.

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

Note
Après avoir créé le projet, vous pouvez ajouter des langues supplémentaires et des noms de projets localisés dans la section Project settings.

  1. Sélectionnez un ou plusieurs plateformes de sortie pour votre jeu (obligatoire).
  2. 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).
  3. Choisissez le moteur de jeu.
  4. Sélectionnez les options de monétisation que vous utilisez ou prévoyez d'utiliser.
  5. 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.
  6. Cliquez sur Create project.
Une page avec les produits Xsolla recommandés pour vous s'affiche.

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

Avis

Pour ce faire, créez un catalogue côté Xsolla. Ajoutez des objets manuellement ou importez-les depuis Google Play ou PlayFab. Notez que vous pouvez importer un maximum de 100 objets à la fois depuis Google Play.

Ces instructions décrivent les étapes de la configuration de base d’un objet virtuel. Par la suite, vous pourrez ajouter d’autres objets au catalogue (monnaie virtuelle, lots, clés de jeu), créer des groupes d’objets, configurer des campagnes promotionnelles, des prix régionaux, etc.

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.

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

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

Note
Pour le bon fonctionnement des appels d’obtention du catalogue, assurez-vous que la devise par défaut figure sur liste des devises dans lesquelles les prix sont spécifiés pour tous les objets.

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

  1. Cliquez sur Create item.

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

  1. Téléchargez le SDK depuis CDN ou GitHub.
  2. Décompressez le package.
  3. Dans le menu principal, accédez à Assets > Import Package > Custom Package et sélectionnez le SDK téléchargé.
  4. Dans le menu principal, allez à Window > Xsolla > Edit Settings.
  5. Accédez au panneau Inspector. Dans le champ Project ID, spécifiez l'ID du projet, qui se trouve dans le Compte éditeur à côté du nom de votre projet.

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

Note

Pour obtenir une liste d’objets virtuels, utilisez la méthode SDK GetCatalog. Vous pouvez également utiliser d’autres méthodes SDK pour récupérer les informations sur les objets du catalogue.

Pour un tutoriel étape par étape sur la création d’une page de catalogue, consultez Affichage du catalogue des objets.

Configurer l'achat d'objets

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

Note

Assurez-vous de créer le projet PlayFab et d’intégrer préalablement le SDK PlayFab dans votre projet Unity.

Les scripts cloud PlayFab ne prennent pas directement en charge les fonctions avec des déclencheurs HTTP. Azure Functions est donc utilisée pour implémenter la réception des webhooks.

Pour commencer avec les fonctions Azure, créez un compte Azure et préparez votre environnement de développement. Cette instruction décrit les étapes dans l’environnement de développement avec les paramètres suivants :

Ajouter un script cloud à votre projet

  1. Ouvrez Visual Studio Code et accédez à l'onglet Azure.
  2. Dans la section Workspace, cliquez sur l'icône + et sélectionnez Create Function.

  1. Sélectionnez le répertoire du nouveau projet. Un menu permettant de créer un nouveau projet s'affiche avec une sélection de paramètres.

  1. Spécifiez les nouveaux paramètres du projet :
    1. Sélectionnez un langage pour votre projet de fonction — C# ;
    2. Sélectionnez une version de .NET — .NET 8.0 Isolated (LTS) ;
    3. Sélectionnez un modèle pour la première fonction de votre projet — HTTP trigger ;
    4. Entrez un nom de fonction — GetXsollaPaymentToken ;
    5. Entrez un espace de noms — My.Functions ;
    6. Sélectionnez le niveau d'autorisation — Anonymous ;
    7. Sélectionnez comment vous souhaitez ouvrir votre projet — Open in current window.

  1. En conséquence, Visual Studio Code générera un projet C# et ouvrira le fichier GetXsollaPaymentToken.cs généré.

  1. Modifiez le fichier GetXsollaPaymentToken.cs :

Copy
Full screen
Small screen
using System.Text;
using System.Net.Http.Headers;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;

namespace My.Function
{
    public class GetXsollaPaymentToken
    {
        private readonly ILogger<GetXsollaPaymentToken> _logger;

        private const int PROJECT_ID = ""; // Your Xsolla project ID
        private const string API_KEY = ""; // Your Xsolla API key

        public GetXsollaPaymentToken(ILogger<GetXsollaPaymentToken> logger)
        {
            _logger = logger;
        }

        [Function("GetXsollaPaymentToken")]
        public async Task<IActionResult> Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req)
        {
            _logger.LogInformation("GetXsollaPaymentToken function processed a request.");

            // Reading the request body
            string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
            _logger.LogInformation("Request body: " + requestBody);

            // Deserializing request body JSON
            dynamic data = JsonConvert.DeserializeObject(requestBody);

            // Extracting necessary data from JSON
            string uid = data.FunctionArgument.uid;
            string sku = data.FunctionArgument.sku;
            string returnUrl = data.FunctionArgument.returnUrl;

            // Creating payload for Xsolla API
            var payload = new
            {
                user = new
                {
                    id = new { value = uid },
                    country = new { value = "US", allow_modify = false }
                },
                purchase = new
                {
                    items = new[]
                    {
                        new { sku = sku, quantity = 1 }
                    }
                },
                sandbox = true,
                settings = new
                {
                    language = "en",
                    currency = "USD",
                    return_url = returnUrl,
                    ui = new { theme = "63295aab2e47fab76f7708e3" }
                }
            };

            // Constructing Xsolla API URL
            string url = $"https://store.xsolla.com/api/v3/project/{PROJECT_ID}/admin/payment/token";

            // Sending request to Xsolla API
            using (HttpClient client = new HttpClient())
            {
                // Adding authorization header
                string headerValue = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{PROJECT_ID}:{API_KEY}"));
                client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", headerValue);

                // Serializing payload to JSON
                var jsonPayload = JsonConvert.SerializeObject(payload);
                var content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");

                // Making POST request to Xsolla API
                var xsollaRes = await client.PostAsync(url, content);

                // Checking response from Xsolla API
                if (xsollaRes.IsSuccessStatusCode)
                {
                    // Reading successful response content
                    string responseContent = await xsollaRes.Content.ReadAsStringAsync();
                    return new OkObjectResult(responseContent);
                }
                else
                {
                    // Returning status code in case of failure
                    return new StatusCodeResult((int)xsollaRes.StatusCode);
                }
            }
        }
    }
}

  1. Dans le script, spécifiez les valeurs des constantes :

    • PROJECT_ID — l'ID du projet, qui se trouve dans le Compte éditeur à côté du nom du projet.

    • API_KEY – 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.

Après avoir ajouté le script cloud, vous pouvez tester l’appel de la fonction GetXsollaPaymentToken localement.

Déployer un script cloud

  1. Dans Visual Studio Code, accédez à la section Azure > Resources et cliquez sur l'icône +.
  2. Sélectionnez Create Function App in Azure en tant que ressource. Un menu pour la création d'une nouvelle application s'affiche avec une sélection de paramètres.
  3. Définissez les paramètres de l'application :

    1. Entrez le nom de la nouvelle application de fonction — XsollaFunctions ;
    2. Sélectionnez une pile d'exécution — .NET 8 Isolated ;
    3. Sélectionnez un emplacement pour les nouvelles ressources (vous pouvez choisir n'importe quelle option).

  1. Attendez que le groupe de ressources soit créé.

  1. Dans la liste des ressources, sélectionnez XsollaFunctions, appelez le menu contextuel et choisissez Deply to Function App.

Après avoir ajouté le script cloud, vous pouvez tester l’appel de la fonction GetXsollaPaymentToken à distance.

Tester un script cloud

Pour tester le script cloud (en local ou à distance), appelez la fonction GetXsollaPaymentToken à l’aide de Postman ou d’un autre outil. Pour ce faire :

  1. Dans Visual Studio Code, accédez à la section Azure > Workspace > Local Project > Functions et cliquez sur Start debugging to update this list.
  2. Appelez le menu contextuel pour la fonction et sélectionnez Copy Function Url. Lors des tests en local, l'URL ressemblera à ceci — http://localhost:7071/api/getXsollaPaymentToken. Lors des tests à distance — https://xsollafunctions.azurewebsites.net/api/GetXsollaPaymentToken.

  1. Utilisez l'URL copiée pour appeler la fonction avec les paramètres spécifiés. Pour appeler une fonction depuis Postman :
    1. Créez une nouvelle requête GET ;
    2. Fournissez l'URL que vous avez copiée à l'étape 2 ;
    3. Accédez à l'onglet Body et spécifiez les paramètres de la requête.

Exemple de corps de la requête :

Copy
Full screen
Small screen
{

 "FunctionArgument": {

   "uid": "1D384D9EF12EAB8B",

   "sku": "booster_max_1",

   "returnUrl": "https://login.xsolla.com/api/blank"

 }

}
Note
Pour l’ID utilisateur (uid), spécifiez n’importe quelle valeur. En tant que UGS du bien (sku), spécifiez l’UGS de l’objet virtuel que vous avez précédemment ajouté dans le Compte éditeur.

  1. Cliquez sur Send. Dans la réponse, vous devriez recevoir du contenant les paramètres suivants :
    • token — jeton de paiement. Nécessaire pour ouvrir l'interface de paiement ;
    • order_id — ID de la commande créée. Nécessaire pour suivre le statut de la commande.

Exemple de corps de la réponse :

Copy
Full screen
Small screen
{"token":"xsnpCF8tS4ox7quoibgTgPFVFxG9gTvS_lc_en_bg_2C2640_tb_6E7BF7","order_id":90288613}

Fonction d'enregistrement pour obtenir un jeton de paiement dans PlayFab

  1. Ouvrez votre projet dans PlayFab.
  2. Dans le menu latéral, cliquez sur Automation.
  3. Dans la section Register New Cloud Script Function, cliquez sur Register Function.
  4. Entrez le nom de la fonction — GetXsollaPaymentToken.
  5. Entrez l'URL de la fonction que vous avez copiée dans Visual Studio Code (voir étapes 1-2 de Tester un script cloud).

Créer une commande et ouvrir l'interface de paiement dans le projet Unity

  1. Ouvrez le projet Unity.
  2. Créez le script XsollaPlayfabSample.cs avec le contenu suivant :

Copy
Full screen
Small screen
using System;
using PlayFab;
using PlayFab.ClientModels;
using PlayFab.CloudScriptModels;
using UnityEngine;
using Xsolla.Core;

public class XsollaPlayfabSample : MonoBehaviour
{
    private void Start()
    {
        // Logging in anonymously
        LoginAnonymous(
            // Callback function invoked after successful login
            userId => {
                // Requesting Xsolla payment token
                GetXsollaPaymentToken(
                    userId, // PlayFab user ID received after login
                    "booster_max_1", // SKU of the product
                    orderData => {
                        // Creating Xsolla token and opening purchase UI
                        XsollaToken.Create(orderData.token);
                        XsollaWebBrowser.OpenPurchaseUI(orderData.token);

                        // Adding order for tracking
                        OrderTrackingService.AddOrderForTracking(
                            orderData.order_id,
                            true,
                            () => Debug.Log("Payment completed"),
                            onError => Debug.LogError(onError.errorMessage));
                    });
            });
    }

    private static void LoginAnonymous(Action<string> onSuccess)
    {
        // Logging in with custom ID
        PlayFabClientAPI.LoginWithCustomID(
            new LoginWithCustomIDRequest {
                CustomId = SystemInfo.deviceUniqueIdentifier, // Unique ID generated based on the device
                CreateAccount = true
            },
            result => {
                // Logging the result
                Debug.Log("Logged with playfab id: " + result.PlayFabId);

                // Invoking onSuccess callback with PlayFab ID
                onSuccess?.Invoke(result.PlayFabId);
            },
            error => { Debug.LogError(error.GenerateErrorReport()); }); // Handling login error
    }

    private static void GetXsollaPaymentToken(string userId, string sku, Action<OrderData> onSuccess)
    {
        // Creating request data for Xsolla payment token
        var tokenRequestData = new PaymentTokenRequestData {
            uid = userId, // User ID
            sku = sku, // Product SKU
            returnUrl = $"app://xpayment.{Application.identifier}" // Return URL
        };

        // Executing a function in the PlayFab cloud to get payment token
        PlayFabCloudScriptAPI.ExecuteFunction(
            new ExecuteFunctionRequest {
                FunctionName = "GetXsollaPaymentToken", // Name of Azure function
                FunctionParameter = tokenRequestData, // Data passed to the function
                GeneratePlayStreamEvent = false // Setting true if call should show up in PlayStream
            },
            result => {
                // Logging the result
                Debug.Log($"GetXsollaPaymentToken result: {result.FunctionResult}");

                // Parsing JSON result to OrderData object
                OrderData orderData = JsonUtility.FromJson<OrderData>(result.FunctionResult.ToString());

                // Invoking onSuccess callback with order data
                onSuccess?.Invoke(orderData);
            },
            error => Debug.LogError($"Error: {error.GenerateErrorReport()}")); // Handling error
    }

    // Class for payment token request data
    public class PaymentTokenRequestData
    {
        public string uid; // User ID
        public string sku; // Product SKU
        public string returnUrl; // Return URL
    }
}

  1. Créez une nouvelle scène.
  2. Créez un objet de jeu vide. Pour ce faire, accédez au menu principal et sélectionnez GameObject > Create Empty.

  1. Ajoutez un script à l'objet de jeu :
    1. Dans le panneau Hierarchy, sélectionnez l'objet ;
    2. Dans le panneau Inspector, cliquez sur Add Component et sélectionnez le script XsollaPlayfabSample.

  1. Dans le panneau Hierarchy, appelez le menu contextuel et sélectionnez UI > EventSystem.

Pour tester la création d’une commande, exécutez la scène en cliquant sur Play. En conséquence, l’interface de paiement contenant les détails de la commande devrait s’afficher.

Le code source du projet Unity se trouve sur GitHub.

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

La logique de suivi de commande est intégrée dans la méthode GetXsollaPaymentToken. Afin de traiter un achat réussi, passez une fonction qui est appelée lorsque le statut de la commande change à done.

La méthode SDK AddOrderForTracking s’utilise pour le suivi des commandes. Pour des informations détaillées sur le fonctionnement de cette méthode, référez-vous à Suivi du statut de la commande.

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

Avis

Le SDK vous permet de suivre l’état de la commande côté client de l’application. Cependant, nous vous recommandons d’implémenter le gestionnaire du webhook Paiement pour recevoir des informations sur la commande dans le back-end de l’application. Cela vous permet d’implémenter une validation supplémentaire des achats effectués.

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.

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.

Note

Pour tester les webhooks, vous pouvez également choisir n’importe quel site dédié, tel que webhook.site, ou une plateforme, telle que ngrok.

À des fins de test, vous pouvez également ajouter un script cloud qui simule le traitement réussi des webhooks. Le code du script est disponible sur GitHub.

Dans le cadre d’un projet réel, vous devez ajouter une logique de validation des achats.

  1. 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.
  2. Cliquez sur Enable webhooks.

Cet article vous a été utile ?
Merci !
Que pouvons-nous améliorer ? Message
Nous sommes désolés de l'apprendre
Dites-nous pourquoi vous n'avez pas trouvé cet article utile. Message
Merci pour votre commentaire !
Nous examinerons votre message et l'utiliserons pour améliorer votre expérience.
Dernière mise à jour: 3 Octobre 2024

Faute de frappe ou autre erreur dans le texte ? Sélectionnez le texte concerné et appuyez sur Ctrl+Entée.

Signaler un problème
Nous améliorons continuellement notre contenu grâce à vos commentaires.
Indiquez votre adresse e-mail pour un suivi
Merci pour votre commentaire !