Activez Buy Button via des liens externes redirigeant vers Web Shop

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.

• Flux transparent : en appuyant sur Buy Button, le Web Shop s’ouvre pour l’achat d’un objet spécifique, puis l’utilisateur est automatiquement redirigé vers le jeu après un paiement réussi.
• Prise en charge de différents modes de paiement, y compris les paiements en un clic via Apple Pay, offrant un paiement mobile rapide et familier.
• Configuration rapide : si le Web Shop est déjà configuré, il suffit d’ajouter un lien avec les paramètres du jeu.
• Onboarding instantané : si le Web Shop n’est pas encore configuré, créez-le instantanément, ajoutez des liens de paiement au jeu et passez en production.

Cette option d’intégration vous donne accès non seulement à Buy Button, mais aussi aux fonctionnalités de Web Shop, telles que la personnalisation, le programme de parrainage, le système de fidélité, les codes promo, et bien plus encore.

Si vous utilisez un Web Shop personnalisé non basé sur Site Builder et que vous souhaitez intégrer Pay Station directement dans le jeu, utilisez l’intégration via Xsolla Mobile SDK.

Comment ça marche

1. L’utilisateur ouvre l’application sur iOS.
2. L’utilisateur appuie sur Buy Button à côté de l’objet souhaité.
3. L’application lance le navigateur avec un lien Web Shop contenant les paramètres user-id, purchase-sku et redirect-url.
4. Web Shop authentifie automatiquement l’utilisateur et affiche l’interface de paiement pour l’achat de l’objet sélectionné.
5. L’utilisateur choisit un mode de paiement et effectue l’achat.
6. L’utilisateur est automatiquement redirigé vers le jeu via un lien profond.
7. L’application reçoit la confirmation de l’achat via un webhook et attribue l’objet acheté.

Comment configurer

1. Créer un Web Shop :
   1. Créez un projet dans le Compte éditeur ;
   2. Configurez un modèle ;
   3. Créez un catalogue des objets ;
   4. Configurez l’authentification utilisateur ;
   5. Configurez les webhooks pour attribuer des achats à l’utilisateur ;
   6. Testez le site ;
   7. Publiez le site.
2. Ajoutez une logique à l’application iOS pour afficher le bouton avec le lien d’achat uniquement aux utilisateurs situés aux États-Unis :
   1. Ajoutez le bouton au jeu ;
   2. Détectez la vitrine iOS.

Démarrage rapide

Inscrivez un Compte éditeur et créez un projet

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.

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.

Configurez un modèle Web Shop

1. Ouvrez votre projet dans le Compte éditeur.
2. Sur la page principale du projet, appuyez sur Change focus et sélectionnez Enable Buy Button via link-outs to Web Shop.
3. À l’étape Create your Web Shop page, appuyez sur Create template.

4. Sélectionnez le type de Web Shop :
   • Single-page shop — site où toutes les sections sont regroupées sur une seule page ;
   • Multi-page web portal — site composé de trois pages distinctes : page principale, page de catalogue des objets et page de nouvelles.

5. Cliquez sur Continue.
6. Dans l’onglet Express, ajoutez un lien vers votre jeu sur l’App Store. Cette possibilité permet de créer rapidement un site personnalisé pour votre jeu : l’image, le titre, le nom du développeur et la palette de couleurs sont automatiquement intégrés lors de la création.
7. Appuyez sur Create Web Shop.

Configurez le catalogue des objets

Côté Xsolla, créez un catalogue des objets que vous vendez dans le jeu. Choisissez l’une des méthodes suivantes pour configurer le catalogue :

• Importez les objets : téléchargez un fichier JSON pour ajouter rapidement votre catalogue au Compte éditeur.
• Utilisez les appels API : idéal pour les mises à jour automatisées ou à grande échelle.
• Importez le catalogue depuis l’App Store, Google Play ou PlayFab : transférez un catalogue existant directement depuis une plateforme externe.
• Configurez le catalogue manuellement : ajoutez et modifiez des objets directement dans le Compte éditeur.

Configurez l'authentification utilisateur

Pour attribuer les achats au compte en jeu de l’utilisateur, configurez l’authentification via l’ID de l’utilisateur dans le jeu.

Vous devez également configurer le traitement du webhook pour confirmer l’existence de l’utilisateur. Ce webhook apporte une validation supplémentaire lorsque le Web Shop est ouvert via un lien direct depuis le jeu et est indispensable pour authentifier l’utilisateur en dehors du client du jeu.

Pour configurer l’authentification :

1. Côté application, implémentez la gestion du webhook de validation utilisateur.

Lors de la réception d’un webhook, l’application doit effectuer les opérations suivantes :

• Rechercher l’utilisateur à l’aide de son ID passé dans le webhook.
• En fonction du résultat, envoyer l’un des codes d’état suivants :
  • Un code HTTP 200 avec une réponse du webhook, si l’utilisateur est trouvé ;
  • Un code HTTP 404, si l’ID utilisateur n’est pas trouvé.
• Envoyer les attributs utilisateur à des fins de personnalisation.

2. Ouvrez le projet dans le Compte éditeur et accédez à la section Storefronts > Websites.
3. Dans le volet du site web souhaité, appuyez sur Open Site Builder.
4. Accédez au bloc Login settings.

5. Sélectionnez l'option User ID.

6. Dans la liste déroulante, sélectionnez New Login.

7. Entrez l'URL pour recevoir les webhooks. Cette URL peut être différente de celle spécifiée dans Project settings > Webhooks.

Configurez les webhooks pour octroyer les achats à l'utilisateur

Les webhooks sont des notifications sur les événements survenant dans le système. Lorsqu’un événement spécifique survient, Xsolla envoie une requête HTTP avec les données associées à votre serveur de jeu. Ces webhooks permettent à votre client ou à votre serveur de recevoir des informations sur les paiements réussis ou échoués, ainsi que sur les tentatives d’authentification utilisateur.

Activation des 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.

Test de webhooks

Dans l’onglet Payments and Store, vous pouvez tester les webhooks suivants :

Validation utilisateur (“notification_type”:“user_validation”) :

 1curl -v 'https://your.hostname/your/uri' \
 2-X POST \
 3-H 'Accept: application/json' \
 4-H 'Content-Type: application/json' \
 5-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
 6-d '{
 7    "notification_type":"user_validation",
 8    "settings": {
 9      "project_id": 18404,
10      "merchant_id": 2340
11    },
12    "user": {
13        "ip": "127.0.0.1",
14        "phone": "18777976552",
15        "email": "email@example.com",
16        "id": "1234567",
17        "name": "John Smith",
18        "country": "US"
19    }
20}'

Successful payment for order (“notification_type”: “order_paid”) :

  1curl -v 'https://your.hostname/your/uri' \
  2-X POST \
  3-H 'Accept: application/json' \
  4-H 'Content-Type: application/json' \
  5-H 'Authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \
  6-d '{
  7    "notification_type": "order_paid",
  8    "items": [
  9      {
 10        "sku": "com.xsolla.item_1",
 11        "type": "virtual_good",
 12        "is_pre_order": false,
 13        "quantity": 3,
 14        "amount": "1000",
 15        "promotions": [
 16          {
 17            "amount_without_discount": "6000",
 18            "amount_with_discount": "5000",
 19            "sequence": 1
 20          },
 21          {
 22            "amount_without_discount": "5000",
 23            "amount_with_discount": "4000",
 24            "sequence": 2
 25          }
 26        ],
 27        "custom_attributes":
 28          {
 29            "purchased": 0,
 30            "attr": "value"
 31          }
 32      },
 33      {
 34        "sku": "com.xsolla.item_new_1",
 35        "type": "bundle",
 36        "is_pre_order": false,
 37        "quantity": 1,
 38        "amount": "1000",
 39        "promotions": []
 40      },
 41      {
 42        "sku": "com.xsolla.gold_1",
 43        "type": "virtual_currency",
 44        "is_pre_order": false,
 45        "quantity": 1500,
 46        "amount": null,
 47        "promotions": []
 48      }
 49    ],
 50    "order": {
 51      "id": 1,
 52      "mode": "default",
 53      "currency_type": "virtual",
 54      "currency": "sku_currency",
 55      "amount": "2000",
 56      "status": "paid",
 57      "platform": "xsolla",
 58      "comment": null,
 59      "invoice_id": "1",
 60      "promotions": [
 61        {
 62          "amount_without_discount": "4000",
 63          "amount_with_discount": "2000",
 64          "sequence": 1
 65        }
 66      ],
 67      "promocodes": [
 68        {
 69          "code": "promocode_some_code",
 70          "external_id": "promocode_sku"
 71        }
 72      ],
 73      "coupons": [
 74        {
 75          "code": "WINTER2021",
 76          "external_id": "coupon_sku"
 77        }
 78      ]
 79    },
 80    "user": {
 81      "external_id": "id_xsolla_login_1",
 82      "email": "gc_user@xsolla.com"
 83    },
 84    "billing": {
 85      "notification_type": "payment",
 86      "settings": {
 87        "project_id": 18404,
 88        "merchant_id": 2340
 89      },
 90      "purchase": {
 91          "subscription": {
 92              "plan_id": "b5dac9c8",
 93              "subscription_id": "10",
 94              "product_id": "Demo Product",
 95              "date_create": "2014-09-22T19:25:25+04:00",
 96              "date_next_charge": "2014-10-22T19:25:25+04:00",
 97              "currency": "USD",
 98              "amount": 9.99
 99          },
100          "total": {
101              "currency": "USD",
102              "amount": 200
103          },
104          "promotions": [{
105              "technical_name": "Demo Promotion",
106              "id": 853
107          }],
108          "coupon": {
109              "coupon_code": "ICvj45S4FUOyy",
110              "campaign_code": "1507"
111          }
112        },
113      "transaction": {
114          "id": 1,
115          "external_id": 1,
116          "payment_date": "2014-09-24T20:38:16+04:00",
117          "payment_method": 1,
118          "payment_method_name": "PayPal",
119          "payment_method_order_id": 1234567890123456789,
120          "dry_run": 1,
121          "agreement": 1
122      },
123      "payment_details": {
124          "payment": {
125              "currency": "USD",
126              "amount": 230
127          },
128          "vat": {
129              "currency": "USD",
130              "amount": 0,
131              "percent": 20
132          },
133          "sales_tax": {
134              "currency": "USD",
135              "amount": 0,
136              "percent": 0
137          },
138          "direct_wht": {
139              "currency": "USD",
140              "amount": 0,
141              "percent": 0
142          },
143          "payout_currency_rate": "1",
144          "payout": {
145              "currency": "USD",
146              "amount": 200
147          },
148          "country_wht": {
149              "currency": "USD",
150              "amount": 2,
151              "percent": 10
152          },
153          "user_acquisition_fee": {
154              "currency": "USD",
155              "amount": 2,
156              "percent": 1
157          },
158          "xsolla_fee": {
159              "currency": "USD",
160              "amount": 10
161          },
162          "payment_method_fee": {
163              "currency": "USD",
164              "amount": 20
165          },
166          "repatriation_commission": {
167              "currency": "USD",
168              "amount": 10
169          }
170      }
171    }
172 ,
173  "custom_parameters": {
174    "parameter1": "value1",
175    "parameter2": "value2"
176  }
177}'

Tester le site en mode bac à sable

Pour tester le site, utilisez le mode bac à sable :

1. Ouvrez le projet dans le Compte éditeur et accédez à la section Storefronts > Websites.
2. Cliquez sur Open Site Builder dans le volet du site souhaité.
3. Cliquez sur Preview.

4. Sélectionnez un objet et cliquez sur le bouton d’achat.
5. Choisissez le groupe de modes de paiement Card.
6. Entrez les informations de la carte bancaire de test. Entrez des valeurs aléatoires dans les champs restants. Vous pouvez également indiquer des informations incorrectes (numéro de carte, date d’expiration ou CVV) afin de générer une erreur.

Publier le site

1. Pour améliorer les performances de votre site :

   a. Dans le bloc SEO Settings, définissez les paramètres qui seront utilisés par les moteurs de recherche, ainsi que ceux destinés à la prévisualisation des pages sur les réseaux sociaux : téléchargez une favicône, indiquez le titre et la description du magasin et ajoutez une image de prévisualisation ;

   b. Configurez la localisation du site ;

   c. Modifiez le domaine (facultatif). Pour ce faire, accédez à la section Storefronts > Websites et cliquez sur Configure dans le volet du site. Dans la section Domain, modifiez la valeur Xsolla domain ou créez votre propre domaine.

2. Après avoir effectué toutes les modifications nécessaires et préparé le magasin en ligne pour le lancement, cliquez sur Publish.

Ajoutez un bouton avec un lien d'achat à votre jeu

Ajoutez un bouton à votre jeu qui redirige l’utilisateur vers le Web Shop pour payer l’objet sélectionné. Le bouton doit contenir un lien au format suivant : https://yourwebshop.xsolla.site/?user-id=<USER_ID>&purchase-sku=<ITEM_SKU>&redirect-url=<RETURN_TO_GAME_URL>, où :

• yourwebshop.xsolla.site est le lien vers le site de votre Web Shop ;
• user-id est l’ID utilisateur dans votre système ;
• purchase-sku est l’UGS de l’objet souhaité dans le catalogue du Web Shop ;
• redirect-url est l’URL d’une page web (p. ex. https://example.com/success) ou un lien profond (p. ex. mygame://open) vers laquelle l’utilisateur est redirigé après un paiement. Lors de l’utilisation d’un lien profond, assurez-vous que :
  • le format est correct, incluant le schéma et le chemin (p. ex. mygame://open) et non seulement le schéma (mygame://) ;
  • le lien profond est pris en charge dans votre application de jeu mobile.

Pour trouver l’UGS de l’objet (en utilisant un objet virtuel comme exemple) :

1. Ouvrez le projet dans le Compte éditeur et accédez à la section Items catalog > Virtual Items.
2. Accédez au groupe contenant l’objet recherché.
3. Copiez l’UGS affichée sur la ligne de l’objet, sous son nom.

Détectez de la région de l'iOS App Store

Pour déterminer si vous pouvez afficher Buy Button, récupérez les informations storefront au lancement initial de l’application après installation, ou lors des lancements suivants si nécessaire. La vitrine peut être intégrée à votre implémentation actuelle de StoreKit ou fournie par votre partenaire de mesure mobile (MMP). Si le code pays de la vitrine est “USA”, activez la fonctionnalité pour afficher Buy Button.

Veillez à ce que votre implémentation soit suffisamment flexible pour prendre en charge d’autres pays à l’avenir, car les conditions réglementaires et les politiques des plateformes sont susceptibles d’évoluer.

Notez que la valeur de la vitrine sur l’appareil ne change que si l’utilisateur met explicitement à jour la région de son identifiant Apple dans les réglages du système.

1let countryCode = await Storefront.current?.countryCode
2let showBuyButton = countryCode == "USA"

Fonctionnalités supplémentaires

Vous pouvez proposer aux utilisateurs un accès rapide aux fonctionnalités du Web Shop en utilisant des paramètres de requête dans l’URL. Pour plus d’informations, reportez-vous aux instructions sur l’utilisation des paramètres de requête.

Analyses avancées dans AppsFlyer

Lorsque vous utilisez des liens externes pour permettre aux utilisateurs d’effectuer des achats via l’interface de paiement Web directement depuis le jeu, vous pouvez toujours suivre leurs achats et mesurer leur valeur à vie (LTV) à l’aide d’un partenaire de mesure mobile (MMP), comme AppsFlyer. Xsolla prend en charge deux types d’intégration, permettant un suivi optimisé de l’acquisition des utilisateurs, du reciblage et de l’activité d’achat sur les plateformes mobiles et Web.

Choisissez le type d’intégration le mieux adapté à votre configuration afin de conserver une visibilité complète sur vos campagnes et vos revenus :