Conseils sur l'intégration dans l'application pour les paiements externes

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 paiements externes, la version 8.3 ou ultérieure est nécessaire. Si vous devez effectuer la migration à partir d'une version antérieure, suivez les instructions du guide de migration pour effectuer la mise à niveau avant de commencer l'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 :

L'exemple suivant illustre l'initialisation d'un objet 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(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build())
    .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é le BillingClient, connectez-vous à Google Play comme décrit dans Se connecter à Google Play.

Vérifier l'éligibilité de l'utilisateur

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 isBillingProgramAvailableAsync() méthode. 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(
            billingResult: BillingResult,
            billingProgramAvailabilityDetails: BillingProgramAvailabilityDetails
        ) {
            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 pour ne pas avoir à 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 paiements externes , comme décrit dans la section Lancer le parcours de paiements externes.

Préparer un jeton de transaction externe

Pour signaler une transaction externe à 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 externe via l'API de paiements externes. Pour ce faire, vous pouvez appeler l'createBillingProgramReportingDetailsAsync API. 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 pour ne pas avoir à définir un écouteur distinct.

Lancer le parcours de paiements externes

Lancez le parcours de paiements externes en appelant launchBillingFlow() comme vous le feriez 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 paiements externes pour cet achat.

DeveloperBillingOptionParams doit contenir les éléments suivants :

  • billingProgram défini sur le programme de facturation EXTERNAL_PAYMENTS
  • linkURI défini sur la destination du lien
  • launchMode défini sur LAUNCH_IN_EXTERNAL_BROWSER_OR_APP si Google Play doit lancer le lien, ou sur CALLER_WILL_LAUNCH_LINK si votre application doit lancer le lien.

Lorsque votre application appelle launchBillingFlow() avec DeveloperBillingOptionParams, 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 propose des 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 DeveloperBillingOptionParams est 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 utilisateur.
  • Si le pays de l'utilisateur sur Google Play n'est pas pris en charge, le parcours d'achat affiche l'expérience utilisateur standard du système de facturation Google Play, sans choix 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 utilisateur dans l'expérience utilisateur

L'utilisateur voit l'expérience utilisateur standard du système de facturation Google Play

Paiements externes non activés (soit non activés lors de la configuration de BillingClient, soit DeveloperBillingOptionParams non 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".toUri())
        .setLaunchMode(
            DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP
        )
        .build()

Java

DeveloperBillingOptionParams developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .setLinkUri(Uri.parse("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 qu'il a choisi de payer 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 le DeveloperProvidedBillingListener pour avertir l'application qu'il a choisi de payer sur votre site Web ou dans une application de paiement. Plus précisément, la méthode onUserSelectedDeveloperBilling() est appelée.

Si votre application définit launchMode sur LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, Google Play lance 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, vous devez vérifier que l'application de paiement est déjà installée sur leur 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 qui ont été traités via le site Web du développeur peuvent être effectuées via le même système de facturation jusqu'à leur expiration.

Cette section explique comment gérer certains scénarios courants de modification d'abonnement.

Parcours de mise à niveau et de rétrogradation

Les modifications apportées aux forfaits d'abonnement, y compris les parcours de mise à niveau et de rétrogradation, doivent être gérées différemment selon que l'abonnement a été initialement souscrit via le système de facturation de Google Play ou via 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 géré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. Lancez une nouvelle expérience d'achat à l'aide de launchBillingFlow(), comme décrit dans la section Lancer le parcours de paiements externes.

Abonnements souscrits via le site Web du développeur ou une application de paiement

Pour les abonnements initialement souscrits via le site Web du développeur ou 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 choix 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 utilisateur, car le choix 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 à l'aide du site Web du développeur ou d'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 qui ont souscrit leur abonnement actuel via le système de facturation de Google Play's après le choix de l'utilisateur doivent suivre le parcours standard de Google Play Billing. 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 à la moitié du mois, il peut continuer à accéder au service pendant les deux semaines restantes environ, jusqu'à ce que son accès soit supprimé. Pendant cette période, l'abonnement est toujours techniquement actif, de sorte que l'utilisateur peut 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 paiements externes.

Abonnements souscrits via 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's, l'utilisateur peut revenir sur sa décision tant que l'abonnement est actif via la fonctionnalité Resubscribe de Google Play's. 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 savoir 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 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. launchBillingFlow() peut être appelé dans ce cas, comme décrit dans la section Lancer le parcours de paiements externes.

Gestion des réponses

En cas d'erreur, les méthodes isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync(), launchBillingFlow() peuvent fournir un BillingResponseCode autre que BillingResponseCode.OK. Envisagez de gérer ces codes de réponse comme suit :

  • 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 dans la requête. Utilisez le message de débogage pour identifier et corriger l'erreur avant de continuer.
  • BillingResponseCode.USER_CANCELED: ne poursuivez pas l'ouverture du site Web ou de l'application externe. Appelez à nouveau launchBillingFlow() 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. Par conséquent, la facturation du développeur ne sera pas disponible dans le cadre de ce programme. Cela est dû au fait que l'utilisateur ne se trouve pas dans un pays éligible à ce programme ou que votre compte n'a pas été inscrit au programme. 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 nouvelle tentative appropriée. Dans le cas de SERVICE_DISCONNECTED, rétablissez une connexion avec Google Play avant de réessayer.

Tester les liens de paiements externes

Les testeurs de licence doivent être utilisés pour tester votre intégration de paiements externes. Vous ne serez pas facturé pour les transactions initiées par des comptes de testeurs de licence. Pour en savoir plus sur la configuration des testeurs de licence, consultez la page 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 votre backend.