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 :
- Inscrivez un Compte éditeur et créez un nouveau projet. L'ID du projet créé sera nécessaire aux étapes suivantes.
- 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.
- 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.
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.
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 :
- Ouvrez votre Compte éditeur.
- Dans le menu latéral, cliquez sur Create project.
- Entrez le nom de votre projet en anglais (obligatoire).
- Sélectionnez un ou plusieurs plateformes de sortie pour votre jeu (obligatoire).
- 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).
- Choisissez le moteur de jeu.
- Sélectionnez les options de monétisation que vous utilisez ou prévoyez d'utiliser.
- 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.
- 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 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 :
- Ouvrez le projet dans le Compte éditeur.
- Dans le menu latéral, cliquez sur Store.
- Dans le volet Virtual Items, cliquez sur Connect.
- Dans le menu déroulant, sélectionnez Create item.
- 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).
- Spécifiez le prix de l'objet :
- Réglez la bascule Price in real currency sur On.
- Dans le champ Default currency, modifiez la devise (facultatif) et spécifiez le prix de l'objet.
- Si vous avez changé la devise dans le champ Default currency, sélectionnez la même devise dans le champ Price in real currency.
- Changez le statut de l'objet en Available.
- Cliquez sur Create item.
Installer et configurer le SDK
- Téléchargez le lanceur Epic Games.
- Créez un nouveau projet Unreal Engine.
- Téléchargez et installez le SDK :
- Pour télécharger et installer le SDK depuis l'Unreal Engine Marketplace :
- Accédez à la page du SDK sur l'Unreal Engine Marketplace.
- Cliquez sur
Open in Launcher .
- Pour télécharger et installer le SDK depuis l'Unreal Engine Marketplace :
- Accédez au lanceur Epic Games.
- Cliquez sur
Install to Engine . - Ouvrez votre projet Unreal Engine dans l'éditeur Unreal.
- Accédez à la section
Settings > Plugins > Installed > Xsolla SDK . Cochez la caseEnabled et cliquez surRestart Now pour enregistrer les paramètres et recharger l'éditeur Unreal.
- Cliquez sur
- Pour télécharger et installer le SDK depuis GitHub :
- Téléchargez le package avec le SDK pour votre version du moteur.
- Décompressez le package.
- Déplacez le dossier du SDK dans le répertoire
plugins
à la racine de votre projet Unreal Engine.
- Pour télécharger et installer le SDK depuis GitHub :
- Accédez à
Settings > Project Settings > Plugins > Xsolla Settings > General . - 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.
Afficher le catalogue côté client de l'application
Dans cette instruction, la méthode SDK GetVirtualItems
est utilisée pour obtenir une liste d’objets virtuels. Vous pouvez également obtenir des informations sur les objets du catalogue en utilisant d’autres méthodes SDK.
Pour un tutoriel étape par étape sur la création d’une page de catalogue, consultez la section Affichage du catalogue des objets.
Créer un catalogue des objets
- Dans
Content Browser , accédez au répertoireContent . - Appelez le menu contextuel et sélectionnez
Blueprint Class .
- Dans la section
All Classes , sélectionnezObject et cliquez surSelect .
- Spécifiez
StoreItemData comme nom de la classe. - Ouvrez le blueprint de la classe créée.
- Dans le panneau
My Blueprint , cliquez surAdd New et sélectionnezVariable . - Dans le panneau
Details :
- Spécifiez
StoreItem dans le champVariable Type ; - Cochez les cases
Instance Editable etExpose on Spawn .
- Spécifiez
- Enregistrez et fermez le blueprint
StoreItemData .
Créer un widget pour un objet du catalogue
- Dans
Content Browser , accédez au répertoireContent . Appelez le menu contextuel et sélectionnezUser Interface > Widget Blueprint . - Spécifiez
StoreItem comme nom du blueprint. - Ouvrez le blueprint créé.
- Dans le panneau
Hierarchy , appelez le menu contextuel pour l'élémentCanvasPanel . SélectionnezReplace With > Overlay .
- Disposez les primitives d'interface depuis le panneau
Palette , comme illustré ci-dessous. Pour l'image, le titre et la description d'un élément, cochez la caseIs Variable dans le panneauDetails .
- Ouvrez une vue
Graph . - Cliquez sur
Class settings . - Dans le panneau
Details , accédez àInterfaces > Implemented Interfaces . - Cliquez sur
Add et sélectionnezUserObjectListEntry . Il s'agit d'une interface UE standard qui permet à la primitive d'interface d'implémenter un comportement normal pour l'élément de la liste.
- Ajoutez la logique pour l'événement
OnListItemObjectSet
:- Dans le panneau
My Blueprint , ouvrez le menu contextuel pour la sectionInterfaces et sélectionnezImplement event ;
- Dans le panneau
- Ajoutez des nœuds comme illustré ci-dessous :
- Enregistrez et fermez le blueprint
StoreItem .
Créer un widget de page de catalogue
- Dans
Content Browser , accédez au répertoireContent et sélectionnezUser Interface > Widget Blueprint dans le menu contextuel. - Spécifiez
WBP_Store en tant que nom du blueprint. - Ouvrez le blueprint créé.
- Dans la zone d'affichage des éléments, ajoutez l'élément
List View et nommez-leStoreListView .
- Dans le panneau
Details , dans le champEntry Widget Class , sélectionnez la classe précédemment créée pour l'élément (StoreItem
). - Accédez à la vue
Graph . - Liez l'appel à la méthode SDK
GetVirtualItems
au nœudEventConstruct
, comme illustré dans la figure ci-dessous.
StoreItemData
est créé pour transférer correctement le tableau d’objets.- Dans le panneau
My Blueprint , cliquez surAdd New et sélectionnezVariable . - Dans le panneau
Details :- Dans le champ
Variable Type , sélectionnezString ; - Cochez les cases
Instance Editable etExpose on Spawn ; - Spécifiez
PlayFabId comme nom.
- Dans le champ
- Enregistrez et fermez le widget
WBP_Store . - Ajoutez la logique d'affichage du répertoire. Voici un exemple d'implémentation de l'affichage du répertoire après l'authentification réussie de l'utilisateur.
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 Create payment token for purchase. 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.
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 :
- Visual Studio Code est installé ;
- L'extension pour travailler avec les fonctions Azure est installée.
Ajouter un script cloud à votre projet
- Ouvrez Visual Studio Code et accédez à l'onglet
Azure . - Dans la section
Workspace , cliquez sur l'icône + et sélectionnezCreate Function .
- 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.
- Spécifiez les nouveaux paramètres du projet :
- Sélectionnez une langue pour votre projet de fonction —
JavaScript . - Sélectionnez un modèle de programmation JavaScript —
model V4 . - Sélectionnez un modèle pour la première fonction de votre projet —
HTTP trigger . - Entrez un nom de fonction —
getXsollaPaymentToken
. - Sélectionnez la manière dont vous souhaitez ouvrir le projet —
Open in current window .
- Sélectionnez une langue pour votre projet de fonction —
- En conséquence, Visual Studio Code générera un projet JS et ouvrira le fichier
getXsollaPaymentToken.js
généré.
- Modifiez le fichier
getXsollaPaymentToken.js
:
- js
const { app } = require('@azure/functions');
const projectId = ""; //your xsolla project id from publisher account
const apiKey = ""; your api key from publisher account
app.http('getXsollaPaymentToken', {
methods: ['POST'],
authLevel: 'anonymous',
handler: async (request, context) => {
var body = await request.json();
const userId = body.uid;
const email = body.email;
const sku = body.sku;
const returnUrl = body.returnUrl;
if (!userId) {
return {status: 400, body: 'Request body is missing' };
}
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/v2/project/" + projectId.toString() + "/admin/payment/token";
return 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 {
return { status: 400, body: `HTTP request failed with error: ${xsollaRes.statusText}` };
}
})
.then(data => {
return { status: 200, body: JSON.stringify(data) };
})
.catch(error => {
return { status: 501, body: `Error = ${error}` };
});
}
});
- 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
- Dans Visual Studio Code, accédez à la section
Azure > Resources et cliquez sur l'icône +. - 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. - Définissez les paramètres de l'application :
- Entrez le nom de la nouvelle application de fonction —
XsollaFunctions
; - Sélectionnez une pile d'exécution —
.NET 8 Isolated ; - Sélectionnez un emplacement pour les nouvelles ressources (vous pouvez choisir n'importe quelle option).
- Entrez le nom de la nouvelle application de fonction —
- Attendez que le groupe de ressources soit créé.
- Dans la liste des ressources, sélectionnez
XsollaFunctions
, appelez le menu contextuel et choisissezDeply 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 :
- Dans Visual Studio Code, accédez à la section
Azure > Workspace > Local Project > Functions et cliquez surStart debugging to update this list . - 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
.
- Utilisez l'URL copiée pour appeler la fonction avec les paramètres spécifiés. Pour appeler une fonction depuis Postman :
- Créez une nouvelle requête
GET
; - Fournissez l'URL que vous avez copiée à l'étape 2 ;
- Accédez à l'onglet
Body et spécifiez les paramètres de la requête.
- Créez une nouvelle requête
Exemple de corps de la requête :
- json
{
"FunctionArgument": {
"uid": "1D384D9EF12EAB8B",
"sku": "booster_max_1",
"returnUrl": "https://login.xsolla.com/api/blank"
}
}
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.- 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 :
- json
{"token":"xsnpCF8tS4ox7quoibgTgPFVFxG9gTvS_lc_en_bg_2C2640_tb_6E7BF7","order_id":90288613}
Fonction d'enregistrement pour obtenir un jeton de paiement dans PlayFab
- Ouvrez votre projet dans PlayFab.
- Dans le menu latéral, cliquez sur
Automation . - Dans la section
Register New Cloud Script Function , cliquez surRegister Function . - Entrez le nom de la fonction —
GetXsollaPaymentToken
. - 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 Unreal Engine
- Ouvrez votre projet Unreal Engine.
- Ouvrez le widget
WBP_Store . - Dans le panneau
Hierarchy , sélectionnezStoreListView . - Dans le panneau
Details , cliquez sur l'icône + à côté de l'événementOn Clicked .
- Accédez à la vue
Graph . - Ajoutez la logique pour créer un objet
PlayfabJsonObject
et pour passer les données au nœudOnItemClicked
en vue de création d'une commande, comme illustré ci-dessous :
- Ajoutez un appel à la méthode
ExecuteFunction
. Passez-lui les paramètresfunctionName = getXsollaPaymentToken
etFunctionParameter = PlayfabJsonObject
.
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 suivre les modifications du statut de la commande, utilisez la méthode SDK CheckPendingOrder
. Passez les paramètres suivants à la méthode :
AuthToken
— jeton d’autorisation utilisateur ;OrderId
— ID de commande reçu depuis achat via le panier, achat en un clic ou achat contre de la monnaie virtuelle ;SuccessCallback
— fonction de rappel appelée si le statut de la commande passe à done ;ErrorCallback
— fonction de rappel appelée si le serveur Xsolla renvoie une erreur.
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
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 :
- Ouvrez le projet dans le Compte éditeur.
- Dans le menu latéral, cliquez sur Project settings et accédez à la section Webhooks.
- Dans le champ Webhook server, entrez l’URL vers laquelle Xsolla enverra les webhooks.
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.
- 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.
- Cliquez sur Enable webhooks.
Faute de frappe ou autre erreur dans le texte ? Sélectionnez le texte concerné et appuyez sur Ctrl+Entée.