Activez Buy Button pour des paiements personnalisés

Pourquoi c'est important

Suite aux récentes mises à jour des règles d’Apple dans certaines régions, les développeurs peuvent désormais rediriger les utilisateurs depuis leurs applications vers des sites externes pour accepter les paiements d’objets virtuels.

Vous pouvez ajouter des boutons, bannières, messages et autres appels à l’action visibles qui redirigent les utilisateurs en un seul clic depuis le jeu vers l’achat d’objets via un paiement sécurisé par navigateur (vers votre Web Shop ou une interface de paiement), sans enfreindre les règles d’Apple ni risquer de sanctions.

L’intégration du Buy Button via le Headless checkout est idéale si vous souhaitez concevoir votre propre interface de paiement et proposer une expérience utilisateur unique. Elle permet aux utilisateurs de passer facilement du jeu à l’achat dans un navigateur, en profitant d’un large choix de modes de paiement, dont le paiement en un clic avec Apple Pay, pour un processus de paiement mobile rapide et familier.

Headless checkout est une solution d’acceptation de paiement basée sur une architecture d’application headless, dans laquelle la fonctionnalité est accessible via API. Cette approche dissocie le backend et la logique métier de l’interface utilisateur.

Pour utiliser le Headless checkout pour les applications de jeux iOS :

1. Créez votre propre magasin.
2. Intégrez le Headless checkout à votre magasin.
3. Ajoutez un lien dans votre jeu qui redirige les utilisateurs vers votre magasin.

Si vous cherchez l’option d’intégration la plus rapide avec peu de code, consultez l’intégration basée Web Shop.

Si vous utilisez un Web Shop personnalisé non conçu avec Xsolla Site Builder et que vous souhaitez intégrer une interface de paiement prête à l’emploi au jeu, consultez l’intégration via Xsolla Mobile SDK.

Comment ça marche

Flux utilisateur

1. L’utilisateur ouvre l’application de jeu sur iOS.
2. L’utilisateur clique sur le bouton d’achat à côté de l’objet souhaité.
3. Votre magasin s’ouvre dans un navigateur web. Pour garantir une expérience utilisateur transparente, implémentez une autorisation de bout en bout.
4. L’utilisateur sélectionne un objet et effectue l’achat sans quitter le magasin.
5. L’utilisateur est redirigé vers l’application de jeu après une transaction réussie.
6. L’application reçoit la confirmation d’achat via un webhook.

Flux d'intégration

1. Créez un projet dans le Compte éditeur et signez le contrat de licence avec Xsolla.
2. Créez un catalogue des objets.
3. Implémentez des interactions avec le backend : créez un jeton et configurez des webhooks.
4. Installez le SDK.
5. Intégrez le SDK côté application.
6. Ajoutez un lien dans votre jeu qui redirige les utilisateurs vers votre magasin, où le Headless checkout est intégré.

Créer un projet et signer le contrat de licence

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

Pour vous inscrire, accédez au Compte éditeur et créez un compte. Pour créer un projet, appuyez sur Create project dans le menu latéral et fournissez toutes les informations nécessaires. Vous pourrez modifier les paramètres ultérieurement.

Pour signer le contrat de licence, accédez à la section Agreements & Taxes > Agreements et remplissez le formulaire de contrat.

Créer un catalogue des objets

Dans l’écosystème Xsolla, les achats in-app (IAP) sont représentés sous forme d’objets virtuels. Chaque objet possède un nom, une description, une UGS et un prix. Pour configurer votre catalogue IAP, vous pouvez :

1. Télécharger un fichier JSON pour ajouter rapidement votre catalogue au Compte éditeur.
2. Créez un catalogue des objets à l’aide des appels API de la section Virtual items & currency > Admin de la documentation.

Implémenter l'interaction avec le backend

Créer un jeton

Configurer les webhooks

Pour activer les webhooks :

1. Dans votre projet, dans le Compte éditeur, accédez à la section Project setting > Webhooks.
2. Dans le champ Webhook server, indiquez l’URL du serveur sur lequel vous souhaitez recevoir les webhooks, au format https://example.com. Vous pouvez également utiliser l’URL générée par un outil de test de webhooks.
3. Une clé secrète pour signer les webhooks du projet est générée par défaut. Si vous souhaitez générer une nouvelle clé secrète, cliquez sur l’icône d’actualisation.
4. Cliquez sur Enable webhooks.

Pour gérer pleinement le magasin en jeu et les paiements, il est nécessaire d’implémenter le traitement des principaux webhooks :

Installer le SDK

1. Installez le SDK en tant que package npm en exécutant la commande :

1npm install --save @xsolla/pay-station-sdk

2. Initialisez le SDK en passant les paramètres d’environnement :

1import { headlessCheckout } from '@xsolla/pay-station-sdk';
2
3await headlessCheckout.init({
4  sandbox: true,
5});

3. Passez le jeton de paiement pour le SDK initialisé :

1await headlessCheckout.setToken(accessToken);

Intégrer le SDK côté application

Après l’installation et l’initialisation du SDK :

1. Initialisez l’interface de paiement en spécifiant l’ID du mode de paiement. La méthode headlessCheckout.form.init renvoie un objet utilisé pour une interaction ultérieure avec l’interface de paiement.

1await headlessCheckout.form.init({
2  paymentMethodId: 3175, // Apple Pay payment ID
3});

2. Ajoutez le traitement de l’événement show_fields pour l’affichage de champs supplémentaires.

1headlessCheckout.form.onNextAction((nextAction) => {
2  switch (nextAction.type) {
3    case 'show_fields':
4      this.handleShowFieldsAction(nextAction);
5  }
6});

3. Ajoutez le composant suivant au balisage HTML de l’interface de paiement :
   • Composants obligatoires :
     • psdk-legal — pour afficher des informations sur les documents juridiques,
     • psdk-total — pour afficher le montant total des achats ;
   • Composants du formulaire de paiement. Vous pouvez utiliser le composant intégré psdk-payment-form ou créer manuellement des éléments d’interface de paiement à l’aide des composants prêts à l’emploi ;
   • Le composant bouton de paiement — psdk-apple-pay. Vous pouvez également utiliser le composant psdk-submit-button qui comprend déjà psdk-apple-pay.

1<psdk-legal></psdk-legal>
2<psdk-total></psdk-total>
3
4
5<psdk-payment-form></psdk-payment-form>
6<psdk-apple-pay text="Apple Pay"></psdk-apple-pay>

4. Ajoutez le traitement de l’événement check_status pour suivre le changement de statut du paiement.

1headlessCheckout.form.onNextAction((nextAction) => {
2  switch (nextAction.type) {
3    case 'check_status': {
4      showStatus = true;
5    }
6  }
7});

5. Ajoutez le composant psdk-status au balisage HTML de l’interface de paiement pour afficher le statut du paiement.

1@if (showStatus) {
2  <psdk-status></psdk-status>
3}

Comment détecter la région de la vitrine App Store

Pour déterminer la région de la vitrine actuelle de l’App Store et ajuster les fonctionnalités du SDK en conséquence, utilisez les extraits de code suivants :

1[SKPaymentQueue loadCurrentStorefrontCountryCodeWithCompletion:^(NSString* _Nullable countryCode) {
2    settings.enablePayments = countryCode && [countryCode isEqualToString:@"USA"];
3
4    [[SKPaymentQueue defaultQueue] startWithSettings:settings];
5}];

1SKPaymentQueue.loadCurrentStorefrontCountryCode { countryCode in
2    settings.enablePayments = countryCode == "USA"
3
4    SKPaymentQueue.default().start(settings)
5}

La méthode loadCurrentStorefrontCountryCode récupère de manière asynchrone le code pays à trois lettres de la vitrine actuelle. Utilisez cette information pour activer ou désactiver certaines fonctionnalités du SDK selon la région.

Vous pouvez également utiliser directement la classe native Storefront d’Apple, comme indiqué ci-dessous :

1let storefront = await Storefront.current   
2let countryCode = storefront?.countryCode
3
4settings.enablePayments = countryCode == "USA"
5
6SKPaymentQueue.default().start(settings)

Paiement en un clic avec Apple Pay

Le paiement en un clic permet aux utilisateurs de payer avec Apple Pay, un moyen de paiement natif, sécurisé et familier, sur les appareils compatibles. Pour configurer le paiement en un clic :

1. Créez une demande pour activer cette option. Pour ce faire :

   a. Ouvrez votre Compte éditeur et accédez à la section Support Hub.

   b. Cliquez sur Submit request.

   

   c. Dans la fenêtre qui s’ouvre, remplissez les champs :

   • Summary. Par exemple : Configuration du paiement en un clic avec Apple Pay.
   • Description. Spécifiez le domaine utilisé pour ouvrir l’interface de paiement, par exemple amazing.store.com.
   • Project ID. Sélectionnez un ID de projet dans la liste déroulante. Si vous souhaitez configurer l’option de paiement en un clic pour plusieurs projets, indiquez leurs ID dans le champ Description.

   d. Cliquez sur Send.

2. Attendez la réception de votre fichier d’association de domaine. Cette étape est gérée par Xsolla :
   1. Xsolla enregistre votre domaine auprès d’Apple.
   2. Xolla reçoit le fichier d’association de domaine d’Apple.
   3. Xsolla vous envoie le fichier d’association de domaine par e-mail et vous indique où l’importer.

3. Mettez à jour le script d’initialisation du SDK comme indiqué ci-dessous :

1const config: InitialOptions = {
2  isWebview: false,
3  theme: 'default',
4  language: parameters.language,
5  topLevelDomain: 'amazing.store.com',
6  isApplePayInstantFlowEnabled: true
7};
8
9await initHeadlessCheckoutLib(config);