Ce document explique comment intégrer les API de la bibliothèque Play Billing pour proposer des paiements externes dans les applications éligibles. Pour en savoir plus sur ce programme, consultez les exigences du programme.
Configuration de la bibliothèque Play Billing
Ajoutez la dépendance de la bibliothèque Play Billing à votre application Android. Pour pouvoir utiliser les API de paiement externe, la version 8.3 ou ultérieure est nécessaire. Si vous devez migrer depuis une version antérieure, suivez les instructions du guide de migration pour effectuer la mise à niveau avant de commencer votre intégration.
Initialiser le client de facturation
Les premières étapes du processus d'intégration sont les mêmes que celles décrites dans le guide d'intégration de Google Play Billing, avec quelques différences au niveau de l'initialisation du client de facturation :
- Vous devez appeler une nouvelle méthode
enableBillingProgram(EnableBillingProgramParams)pour indiquer que vous souhaitez proposer des paiements externes. - Enregistrez un
DeveloperProvidedBillingListenerpour gérer les cas où l'utilisateur choisit de payer sur votre site Web ou dans une application de paiement.
L'exemple suivant illustre l'initialisation d'un BillingClient avec ces modifications :
Kotlin
val purchasesUpdatedListener =
PurchasesUpdatedListener { billingResult, purchases ->
// Handle new Google Play purchase.
}
val developerProvidedBillingListener =
DeveloperProvidedBillingListener { details ->
// Handle user selection for developer provided billing option.
}
val billingClient = BillingClient.newBuilder(context)
.setListener(purchasesUpdatedListener)
.enablePendingPurchases()
.enableBillingProgram(
EnableBillingProgramParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.setDeveloperProvidedBillingListener(developerProvidedBillingListener)
.build())
.build()
Java
private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
@Override
public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
// Handle new Google Play purchase.
}
};
private DeveloperProvidedBillingListener developerProvidedBillingListener =
new DeveloperProvidedBillingListener() {
@Override
public void onUserSelectedDeveloperBilling(
DeveloperProvidedBillingDetails details) {
// Handle user selection for developer provided billing option.
}
};
private BillingClient billingClient = BillingClient.newBuilder(context)
.setListener(purchasesUpdatedListener)
.enablePendingPurchases()
.enableBillingProgram(
EnableBillingProgramParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.setDeveloperProvidedBillingListener(developerProvidedBillingListener)
.build())
.build();
Se connecter à Google Play
Après avoir initialisé BillingClient, connectez-vous à Google Play comme décrit dans Se connecter à Google Play.
Vérifier l'éligibilité des utilisateurs
Une fois que vous êtes connecté à Google Play, vous pouvez vérifier si l'utilisateur est éligible au programme de paiements externes en appelant la méthode isBillingProgramAvailableAsync(). Cette méthode renvoie BillingResponseCode.OK si l'utilisateur est éligible.
L'exemple suivant montre comment vérifier l'éligibilité :
Kotlin
billingClient.isBillingProgramAvailableAsync(
BillingProgram.EXTERNAL_PAYMENTS,
object : BillingProgramAvailabilityListener {
override fun onBillingProgramAvailabilityResponse(
billingProgram: Int, billingResult: BillingResult) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling external payments unavailable, etc.
return
}
// External payments are available. Can proceed with generating an
// external transaction token.
})
Java
billingClient.isBillingProgramAvailableAsync(
BillingProgram.EXTERNAL_PAYMENTS,
new BillingProgramAvailabilityListener() {
@Override
public void onBillingProgramAvailabilityResponse(
int billingProgram, BillingResult billingResult) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling external payments unavailable, etc.
return;
}
// External payments are available. Can proceed with generating an external transaction token.
}
});
Consultez la section Gestion des réponses pour savoir comment votre application doit répondre à d'autres codes de réponse. Si vous utilisez des extensions Kotlin, vous pouvez utiliser des coroutines Kotlin. Vous n'avez donc pas besoin de définir un écouteur distinct.
Afficher les produits disponibles
Vous pouvez présenter les produits disponibles à l'utilisateur de la même manière qu'une intégration du système de facturation Google Play. Lorsque l'utilisateur a vu les produits disponibles à la vente et qu'il en a sélectionné un, lancez le parcours de paiement externe, comme décrit dans la section Lancer le parcours de paiement externe.
Préparer un jeton de transaction externe
Pour enregistrer une transaction externe dans Google Play, vous devez disposer d'un jeton de transaction externe généré à partir de la bibliothèque Play Billing. Un nouveau jeton de transaction externe doit être généré chaque fois que l'utilisateur accède à un site Web ou à une application externes via l'API de paiements externes. Pour ce faire, appelez l'API createBillingProgramReportingDetailsAsync. Le jeton doit être généré immédiatement avant l'appel de launchBillingFlow.
Kotlin
val params =
BillingProgramReportingDetailsParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.build()
billingClient.createBillingProgramReportingDetailsAsync(
params,
object : BillingProgramReportingDetailsListener {
override fun onCreateBillingProgramReportingDetailsResponse(
billingResult: BillingResult,
billingProgramReportingDetails: BillingProgramReportingDetails?) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return
}
val externalTransactionToken =
billingProgramReportingDetails?.externalTransactionToken
// Persist the external transaction token locally. Pass it to
// the external website using DeveloperBillingOptionParams when
// launchBillingFlow is called.
}
})
Java
BillingProgramReportingDetailsParams params =
BillingProgramReportingDetailsParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.build();
billingClient.createBillingProgramReportingDetailsAsync(
params,
new BillingProgramReportingDetailsListener() {
@Override
public void onCreateBillingProgramReportingDetailsResponse(
BillingResult billingResult,
@Nullable BillingProgramReportingDetails
billingProgramReportingDetails) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return;
}
String transactionToken =
billingProgramReportingDetails.getExternalTransactionToken();
// Persist the external transaction token locally. Pass it to
// the external website using DeveloperBillingOptionParams when
// launchBillingFlow is called.
}
});
Si vous utilisez des extensions Kotlin, vous pouvez utiliser des coroutines Kotlin. Vous n'avez donc pas besoin de définir un écouteur distinct.
Lancer le flux de paiements externes
Lancez le parcours de paiement externe en appelant launchBillingFlow(), comme pour lancer un parcours d'achat avec une intégration du système de facturation Google Play, mais avec un paramètre supplémentaire DeveloperBillingOptionParams indiquant que votre application souhaite activer le parcours de paiement externe pour cet achat.
DeveloperBillingOptionParams doit contenir les éléments suivants :
billingProgramdéfini sur le programme de facturationEXTERNAL_PAYMENTSlinkURIdéfini sur la destination du lienlaunchModedéfini surLAUNCH_IN_EXTERNAL_BROWSER_OR_APPsi Google Play doit lancer le lien ou surCALLER_WILL_LAUNCH_LINKsi votre application doit lancer le lien.
Lorsque votre application appelle launchBillingFlow() avec DeveloperBillingOptionParams fourni, le système de facturation Google Play effectue la vérification suivante :
- Le système vérifie si le pays de l'utilisateur Google Play est un pays qui accepte les paiements externes (c'est-à-dire un pays accepté). Si tel est le cas, Google Play vérifie si les paiements externes sont activés, en fonction de la configuration du BillingClient et si
DeveloperBillingOptionParamsest fourni.- Si les paiements externes ont été activés, le parcours d'achat affiche l'expérience utilisateur au choix de l'utilisateur.
- Si les paiements externes ne sont pas activés, le parcours d'achat affiche l'expérience utilisateur standard du système de facturation Google Play, sans choix pour l'utilisateur.
- Si le pays de l'utilisateur sur Google Play n'est pas un pays accepté, le parcours d'achat affiche l'expérience utilisateur standard du système de facturation Google Play, sans choix pour l'utilisateur.
Le pays de l'utilisateur sur Google Play est un pays pris en charge |
Le pays de l'utilisateur sur Google Play n'est pas pris en charge |
|
Paiements externes activés (configuration de BillingClient et launchBillingFlow) |
L'utilisateur voit le choix de l'utilisateur dans l'expérience utilisateur |
L'utilisateur voit l'expérience utilisateur standard du système de facturation Google Play |
Les paiements externes ne sont pas activés (soit ils ne l'ont pas été lors de la configuration de BillingClient, soit DeveloperBillingOptionParams n'a pas été fourni à launchBillingFlow). |
L'utilisateur voit l'expérience utilisateur standard du système de facturation Google Play |
L'utilisateur voit l'expérience utilisateur standard du système de facturation Google Play |
L'extrait suivant montre comment construire DeveloperBillingOptionParams :
Kotlin
val developerBillingOptionParams =
DeveloperBillingOptionParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.setLinkUri("https://www.example.com/external/purchase")
.setLaunchMode(
DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
.build()
Java
DeveloperBillingOptionParams developerBillingOptionParams =
DeveloperBillingOptionParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.setLinkUri("https://www.example.com/external/purchase")
.setLaunchMode(
DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
.build();
Gérer la sélection de l'utilisateur
La manière dont vous gérez le reste du parcours d'achat varie selon que l'utilisateur a sélectionné le système de facturation de Google Play ou le paiement sur votre site Web.
Lorsque l'utilisateur choisit de payer sur votre site Web ou dans une application de paiement
Si l'utilisateur choisit de payer sur votre site Web, Google Play appelle la méthode DeveloperProvidedBillingListener pour avertir l'application que l'utilisateur a choisi de payer sur votre site Web ou dans une application de paiement. En particulier, la méthode onUserSelectedDeveloperBilling() est appelée.
Si votre application définit launchMode sur LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, Google Play lancera le lien. Si launchMode est défini sur CALLER_WILL_LAUNCH_LINK, votre application est responsable du lancement du lien.
Lorsque vous associez des utilisateurs à une application de paiement, il vous incombe de vérifier que l'utilisateur a déjà installé l'application de paiement sur son appareil.
Utilisez ce jeton pour enregistrer toute transaction résultant de ce choix, comme expliqué dans le guide d'intégration du backend.
Lorsque l'utilisateur sélectionne le système de facturation de Google Play
Si l'utilisateur choisit le système de facturation de Google Play, il continue l'achat via Google Play.
- Pour en savoir plus sur la gestion des nouveaux achats via une application via le système de facturation de Google Play, consultez la section Traitement des achats du guide d'intégration de la bibliothèque.
- Pour obtenir des conseils supplémentaires sur les achats d'abonnements, consultez la section Nouveaux abonnements dans le guide de gestion des abonnements.
Gérer les modifications liées aux abonnements
Pour les développeurs qui utilisent des paiements externes, les achats doivent être traités via le système de facturation de Google Play ou signalés avec un externalTransactionId, selon le choix de l'utilisateur. Les modifications apportées aux abonnements existants et qui ont été traitées via le site Web du développeur peuvent être effectuées via le même système de facturation jusqu'à expiration.
Cette section explique comment gérer certains scénarios courants liés à la modification d'un abonnement.
Parcours de mise à niveau et de rétrogradation
Les changements de forfait d'abonnement, y compris les parcours de mise à niveau et de rétrogradation, doivent être gérés différemment selon que l'abonnement a été initialement souscrit via le système de facturation de Google Play ou sur le site Web du développeur.
Les modules complémentaires qui dépendent d'un abonnement existant, partagent le même mode de paiement et alignent les frais récurrents sont traités comme des mises à niveau. Pour les autres modules complémentaires, les utilisateurs doivent pouvoir choisir le système de facturation par lequel ils souhaitent passer. Initiez une nouvelle expérience d'achat à l'aide de launchBillingFlow(), comme décrit dans Lancer le flux de paiement externe.
Abonnements souscrits sur le site Web du développeur ou dans une application de paiement
Pour les abonnements initialement souscrits sur le site Web du développeur ou dans une application de paiement après le choix de l'utilisateur, les personnes qui demandent une mise à niveau ou une rétrogradation doivent passer par le site Web du développeur ou une application de paiement. Elles n'ont pas à repasser par le parcours de facturation au choix de l'utilisateur.
Pour ce faire, appelez launchBillingFlow() lorsque l'utilisateur demande une mise à niveau ou une rétrogradation. Au lieu de spécifier d'autres paramètres sous l'objet SubscriptionUpdateParams, utilisez setOriginalExternalTransactionId() en fournissant l'ID de transaction externe pour l'achat d'origine.
DeveloperBillingOptionParams doit également être fourni dans cet appel. Cela n'affichera pas l'écran de choix de l'utilisateur, car le choix de l'utilisateur pour l'achat d'origine est conservé pour les mises à niveau et les rétrogradations. Vous devez générer un nouveau jeton de transaction externe pour cette transaction, comme décrit ici.
Une fois la mise à niveau ou la rétrogradation effectuée sur le site Web du développeur ou dans une application de paiement, vous devez enregistrer une nouvelle transaction à l'aide du jeton de transaction externe obtenu via l'appel précédent pour l'achat du nouvel abonnement.
Abonnements souscrits via le système de facturation de Google Play
De même, les utilisateurs ayant choisi de souscrire leur abonnement via le système de facturation de Google Play devraient suivre le parcours de facturation standard de Google Play. DeveloperBillingOptionParams ne doit pas être défini dans l'appel à launchBillingFlow.
Résiliations d'abonnement et restaurations
Les utilisateurs doivent pouvoir résilier leur abonnement à tout moment. Lorsqu'un utilisateur résilie un abonnement, la résiliation du droit d'accès peut être reportée jusqu'à la fin de la période de facturation. Par exemple, si un utilisateur résilie un abonnement mensuel en milieu de mois, il peut continuer à profiter du service pendant encore environ deux semaines jusqu'à ce que son accès soit supprimé. Pendant cette période, l'abonnement est toujours techniquement actif. L'utilisateur peut donc utiliser le service.
Il n'est pas rare que les utilisateurs reviennent sur leur décision pendant cette période activité. Dans ce guide, c'est ce que nous appelons la restauration d'un abonnement. Les sections suivantes expliquent comment gérer les scénarios de restauration dans une intégration avec une API de paiement externe.
Abonnements souscrits sur le site Web du développeur
Si vous disposez d'un ID de transaction externe pour un abonnement résilié, il n'est pas nécessaire d'appeler launchBillingFlow() afin de le restaurer. Vous ne devriez pas avoir à l'utiliser pour ce type d'activation. Si un utilisateur restaure son abonnement pendant la période active avant la résiliation effective, aucune transaction n'est effectuée à ce moment-là. Vous pouvez continuer à enregistrer les renouvellements lorsque le cycle de facturation en cours expire et que la prochaine période de renouvellement commence. Cela inclut les cas où l'utilisateur reçoit un crédit ou un tarif de renouvellement spécial dans le cadre de la restauration (par exemple, une promotion pour l'encourager à poursuivre son abonnement).
Abonnements souscrits via le système de facturation de Google Play
En règle générale, les utilisateurs peuvent restaurer les abonnements via le système de facturation de Google Play. Pour les abonnements résiliés qui ont été souscrits à l'origine via le système de facturation de Google Play, l'utilisateur peut revenir sur sa décision tant que l'abonnement est actif grâce à la fonctionnalité Se réabonner de Google Play. Dans ce cas, vous recevez une notification en temps réel pour les développeurs SUBSCRIPTION_RESTARTED dans votre backend, et aucun nouveau jeton d'achat n'est émis. Le jeton d'origine est utilisé pour poursuivre l'abonnement. Pour découvrir comment gérer la restauration dans le système de facturation de Google Play, consultez la section Restaurations du guide de gestion des abonnements.
Vous pouvez également appeler launchBillingFlow() pour déclencher une restauration dans le système de facturation de Google Play à partir de l'application. Pour découvrir comment procéder, consultez la section Avant l'expiration de l'abonnement (dans l'application). Dans le cas des utilisateurs qui ont suivi le parcours de facturation au choix de l'utilisateur pour l'achat d'origine (qui a été résilié, mais qui reste actif), le système détecte automatiquement leur choix et affiche l'interface utilisateur permettant de restaurer ces achats. Ils sont invités à confirmer le rachat de l'abonnement via Google Play, mais il n'est pas nécessaire de recommencer le parcours utilisateur. Dans ce cas, un nouveau jeton d'achat est émis pour chaque utilisateur.
Votre backend recevra une notification en temps réel pour les développeurs SUBSCRIPTION_PURCHASED, et la valeur linkedPurchaseToken correspondant à l'état du nouvel achat sera définie comme pour une mise à niveau ou une rétrogradation, où le jeton de l'ancien achat d'abonnement est résilié.
Réabonnements
Si un abonnement expire complètement, que ce soit en raison d'une résiliation ou d'un refus de paiement sans récupération (blocage d'un compte arrivé à expiration), l'utilisateur doit se réabonner s'il souhaite réactiver le droit d'accès.
Vous pouvez également activer le réabonnement via l'application de la même manière qu'une inscription standard. Les utilisateurs doivent pouvoir choisir le système de facturation par lequel ils souhaitent passer. Dans ce cas, launchBillingFlow() peut être appelé, comme décrit dans la section Lancer le parcours de paiement externe.
Gestion des réponses
Lorsqu'une erreur se produit, les méthodes isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync() et launchBillingFlow() peuvent fournir un BillingResponseCode autre que BillingResponseCode.OK. Voici comment gérer ces codes de réponse :
BillingResponseCode.ERROR: il s'agit d'une erreur interne. Ne poursuivez pas la transaction ni l'ouverture du site Web externe. Réessayez en appelant à nouveau l'API.BillingResponseCode.FEATURE_NOT_SUPPORTED: les API de paiements externes ne sont pas compatibles avec le Play Store sur l'appareil actuel. Ne poursuivez pas la transaction ni l'ouverture du site Web externe.BillingResponseCode.DEVELOPER_ERROR: une erreur s'est produite au niveau de la requête. Utilisez le message de débogage pour identifier et corriger l'erreur avant de continuer.BillingResponseCode.USER_CANCELED: ne procédez pas à l'ouverture du site Web ou de l'application externes. Appelez à nouveaulaunchBillingFlow()pour afficher la boîte de dialogue d'informations à l'utilisateur la prochaine fois que vous tenterez de le rediriger en dehors de l'application.BillingResponseCode.BILLING_UNAVAILABLE: la transaction n'est pas éligible aux paiements externes. La facturation par le développeur ne sera donc pas disponible dans le cadre de ce programme. Cela est peut-être dû au fait que l'utilisateur ne se trouve pas dans l'un des pays éligibles à ce programme ou que l'inscription de votre compte au programme n'a pas été couronnée de succès. Dans ce dernier cas, vérifiez le statut de votre inscription dans la Play Console.BillingResponseCode.NETWORK_ERROR,BillingResponseCode.SERVICE_DISCONNECTED,BillingResponseCode.SERVICE_UNAVAILABLE: il s'agit d'erreurs temporaires qui doivent être gérées avec une stratégie de réessai appropriée. Dans le cas deSERVICE_DISCONNECTED, rétablissez une connexion avec Google Play avant de réessayer.
Tester les liens vers des paiements externes
Les testeurs de licence doivent être utilisés pour tester votre intégration des paiements externes. Vous ne serez pas facturé pour les transactions initiées par des comptes de testeur de licence. Pour en savoir plus sur la configuration des testeurs de licence, consultez Tester la facturation des achats in-app avec les licences d'application.
Étapes suivantes
Une fois que vous avez terminé l'intégration dans l'application, vous pouvez intégrer le backend.