Conseils sur l'intégration dans l'application pour un système de facturation alternatif uniquement

Ce guide explique comment intégrer les API pour proposer un système de facturation alternatif uniquement (c'est-à-dire sans choix de l'utilisateur) dans les applications éligibles. Pour en savoir plus sur ces programmes, y compris sur les critères d'éligibilité et la disponibilité géographique, consultez la page À propos du système de facturation alternatif.

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 facturation alternative, la version 6.1 ou ultérieure est nécessaire.

Se connecter à Google Play

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 pour indiquer que votre application utilise uniquement un système de facturation alternatif : enableAlternativeBillingOnly.

L'exemple suivant illustre l'initialisation d'un objet BillingClient avec ces modifications :

var billingClient = BillingClient.newBuilder(context)
    .enableAlternativeBillingOnly()
    .build()

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableAlternativeBillingOnly()
    .build();

Après avoir initialisé BillingClient, vous devez établir une connexion à Google Play, comme décrit dans le guide d'intégration.

Vérifier la disponibilité

Votre application doit confirmer qu'un système de facturation alternatif uniquement est disponible en appelant isAlternativeBillingOnlyAvailableAsync.

Cette API renvoie BillingResponseCode.OK si un système de facturation alternatif uniquement est disponible. Reportez-vous à la section Gestion des réponses pour savoir comment votre application doit répondre à d'autres codes de réponse.

billingClient.isAlternativeBillingOnlyAvailableAsync(object:
    AlternativeBillingOnlyAvailabilityListener {
        override fun onAlternativeBillingOnlyAvailabilityResponse(
            billingResult: BillingResult) {
            if (billingResult.responseCode !=  BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors,
                // handling alternative billing only being unavailable, etc.
                return
            }

            // Alternative billing only is available. Continue with steps in
            // the guide.
        }
    });

billingClient.isAlternativeBillingOnlyAvailable(
    new AlternativeBillingOnlyAvailabilityListener() {
        @Override
        public void onAlternativeBillingOnlyAvailabilityResponse(
            BillingResult billingResult) {
            if (billingResult.getResponseCode() != BillingResponseCode.OK) {
                 // Handle failures such as retrying due to network errors,
                 // handling alternative billing only being unavailable,
                 // etc.
                return;
            }

            // Alternative billing only is available. Continue with steps in
            // the guide.
        }
    });

Boîte de dialogue d'informations pour les utilisateurs

Pour intégrer un système de facturation alternatif uniquement, votre application éligible doit afficher un écran d'informations expliquant aux utilisateurs que la facturation ne sera pas gérée par Google Play. L'écran d'informations doit systématiquement être présenté aux utilisateurs en appelant l'API showAlternativeBillingOnlyInformationDialog avant de lancer le parcours de facturation alternatif. Si l'utilisateur a déjà confirmé la boîte de dialogue, cette dernière ne sera normalement pas générée à nouveau lors de l'utilisation de l'API. Dans certains cas, la boîte de dialogue peut s'afficher à nouveau, par exemple si l'utilisateur vide des caches sur son appareil.

// An activity reference from which the alternative billing only information
// dialog will be launched.
val activity : Activity = ...;

val listener : AlternativeBillingOnlyInformationDialogListener =
    AlternativeBillingOnlyInformationDialogListener { 
        override fun onAlternativeBillingOnlyInformationDialogResponse(
            billingResult: BillingResult) {
            // check billingResult
        }
}

val billingResult =
    billingClient.showAlternativeBillingOnlyInformationDialog(activity,
        listener)

// An activity reference from which the alternative billing only information
// dialog will be launched.
Activity activity = ...;

AlternativeBillingOnlyInformationDialogListener listener =
    new AlternativeBillingOnlyInformationDialogListener() {
        @Override
        public void onAlternativeBillingOnlyInformationDialogResponse(
            BillingResult billingResult) {
                // check billingResult
            }
    };

BillingResult billingResult =
    billingClient.showAlternativeBillingOnlyInformationDialog(activity,
        listener);

Si cette méthode renvoie BillingResponseCode.OK, alors votre application peut poursuivre la transaction. Si la méthode renvoie BillingResponseCode.USER_CANCELED, votre application doit appeler showAlternativeBillingOnlyInformationDialog pour afficher à nouveau la boîte de dialogue à l'utilisateur. Pour les autres codes de réponse, consultez la section Gestion des réponses.

Signaler des transactions à Google Play

Toutes les transactions effectuées via un système de facturation alternatif doivent être signalées à Google Play en appelant l'API Google Play Developer depuis votre backend dans les 24 heures, en fournissant un externalTransactionToken obtenu à l'aide de l'API décrite ci-dessous. Un nouveau jeton externalTransactionToken doit être généré pour chaque achat unique, chaque nouvel abonnement, et pour toute mise à niveau ou rétrogradation d'un abonnement existant. Pour savoir comment enregistrer une transaction une fois qu'un externalTransactionToken est obtenu, consultez le guide d'intégration du backend.

billingClient.createAlternativeBillingOnlyReportingDetailsAsync(object:
    AlternativeBillingOnlyReportingDetailsListener {
        override fun onAlternativeBillingOnlyTokenResponse(
            billingResult: BillingResult,
            alternativeBillingOnlyReportingDetails:
                AlternativeBillingOnlyReportingDetails?) {
            if (billingResult.responseCode !=  BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors.
                return
            }

            val externalTransactionToken =
                alternativeBillingOnlyReportingDetails?
                    .externalTransactionToken

            // Send transaction token to backend and report to Google Play.
        }
    });

billingClient.createAlternativeBillingOnlyReportingDetailsAsync(
    new AlternativeBillingOnlyReportingDetailsListener() {
        @Override
        public void onAlternativeBillingOnlyTokenResponse(
            BillingResult billingResult,
            @Nullable AlternativeBillingOnlyReportingDetails
                alternativeBillingOnlyReportingDetails) {
            if (billingResult.getResponseCode() != BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors.
                return;
            }

            String transactionToken =
                alternativeBillingOnlyReportingDetails
                .getExternalTransactionToken();

            // Send transaction token to backend and report to Google Play.
        }
    });

Gestion des réponses

Les méthodes isAlternativeBillingOnlyAvailableAsync(), showAlternativeBillingOnlyInformationDialog() et createAlternativeBillingOnlyReportingDetailsAsync() ci-dessus peuvent renvoyer des réponses non-BillingResponseCode.OK en cas d'erreurs. La gestion recommandée pour les erreurs est décrite ci-dessous :

• ERROR : il s'agit d'une erreur interne. Procédez au traitement de la transaction via le système de facturation alternatif. Il n'est pas nécessaire de signaler la transaction à Google ni de signaler les renouvellements des abonnements concernés.
• FEATURE_NOT_SUPPORTED : les API de système de facturation alternatif ne sont pas compatibles avec le Play Store sur l'appareil actuel. Procédez au traitement de la transaction via le système de facturation alternatif. Il n'est pas nécessaire de signaler la transaction à Google ni de signaler les renouvellements des abonnements concernés.
• USER_CANCELED : appelez à nouveau showAlternativeBillingOnlyInformationDialog() pour afficher la boîte de dialogue d'informations la prochaine fois que l'utilisateur tentera d'effectuer un achat.
• BILLING_UNAVAILABLE : la transaction n'est pas éligible à un système de facturation alternatif uniquement et ne doit donc pas être traitée par 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.
• 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.
• NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE : erreurs temporaires nécessitant une nouvelle tentative. Dans le cas de SERVICE_DISCONNECTED, rétablissez une connexion avec Google Play avant de réessayer.

Tester un système de facturation alternatif

Les testeurs de licence doivent être utilisés pour tester l'intégration de votre système de facturation alternatif. Vous ne serez pas facturé pour les transactions lancées par des comptes de testeurs 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.