Conseils sur l'intégration dans l'application pour le programme d'offres externes

Ce guide explique comment effectuer l'intégration avec les API pour prendre en charge les offres externes dans les applications et les régions éligibles. Pour en savoir plus sur le programme d'offres externes y compris sur les critères d'éligibilité et la disponibilité géographique, consultez les exigences du programme.

Configuration de la bibliothèque Play Billing

Pour utiliser les API d'offres externes, ajoutez la dépendance de la bibliothèque Play Billing version 8.2.1 ou ultérieure à votre application Android. Si vous devez effectuer la migration à partir d'une version antérieure, suivez les instructions du guide de migration avant d'essayer d'implémenter des offres externes.

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 la facturation, sauf que vous devez appeler enableBillingProgram pour indiquer que vous souhaitez utiliser des offres externes lors de l'initialisation de votre BillingClient :

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

Kotlin

val billingClient = BillingClient.newBuilder(context)
    .enableBillingProgram(
        EnableBillingProgramParams.newBuilder()
            .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
            .build()
    )
    .build()

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableBillingProgram(BillingProgram.EXTERNAL_OFFER)
    .build();

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

Vérifier la disponibilité

Pour confirmer que les offres externes sont disponibles pour l'utilisateur actuel, appelez isBillingProgramAvailableAsync.

Cette API renvoie BillingResponseCode.OK si des offres externes sont disponibles. Reportez-vous à la section Gestion des réponses pour savoir comment votre application doit répondre à d'autres codes de réponse.

Kotlin

billingClient.isBillingProgramAvailableAsync(
    BillingProgram.EXTERNAL_OFFER,
    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 offers unavailable, etc.
                return
            }

            // External offers are available. Continue with steps in the
            // guide.
        }
    }
)

Java


billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_OFFER,
  new BillingProgramAvailabilityListener() {
    @Override
    public void onBillingProgramAvailabilityResponse(
      BillingResult billingResult,
      BillingProgramAvailabilityDetails billingProgramAvailabilityDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external offers being unavailable, etc.
            return;
        }
        // External offers are available. Continue with steps in the
        // guide.
      }
  });

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. Vous pouvez obtenir ce jeton en appelant l'API createBillingProgramReportingDetailsAsync. Un nouveau jeton doit être généré immédiatement avant de rediriger l'utilisateur en dehors de l'application pour chaque offre externe. Les jetons ne doivent pas être mis en cache entre les transactions.

Kotlin

val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
        .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 transaction token in your backend. You may pass it
            // to the external website when calling the launchExternalLink API.
        }
    }
)

Java

BillingProgramReportingDetailsParams params =
  BillingProgramReportingDetailsParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
    .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 transaction token in your backend. You may pass it
        // to the external website when calling the launchExternalLink API.
      }
});

Vous pouvez également interroger la fonction de suspension createBillingProgramReportingDetailsAsync avec des extensions Kotlin afin que vous n'ayez pas à définir d'écouteur :

val createBillingProgramReportingDetailsResult =
    withContext(coroutineContext) {
        billingClient
            .createBillingProgramReportingDetails(params)
    }
// Process the result

Lancer le flux d'offres externes

Pour démarrer un flux d'offres externes, votre application éligible doit appeler l' launchExternalLink() API à partir du thread principal de votre application. Cette API prend en entrée un objet LaunchExternalLinkParams. Pour créer un LaunchExternalLinkParams objet, utilisez la LaunchExternalLinkParams.Builder classe. Cette classe contient les paramètres suivants :

  • linkUri : lien vers le site Web externe où le contenu numérique ou le téléchargement d'application est proposé. Pour les téléchargements d'applications, ce lien doit être enregistré et approuvé dans la Play Console.
  • linkType : type de contenu proposé à l'utilisateur.
  • launchMode : spécifie le mode de lancement du lien. Pour les téléchargements d'applications, vous devez définir ce paramètre sur LAUNCH_IN_EXTERNAL_BROWSER_OR_APP.
  • billingProgram : définissez ce paramètre sur BillingProgram.EXTERNAL_OFFER.

Lorsque vous appelez launchExternalLink(), des boîtes de dialogue d'informations supplémentaires peuvent s'afficher pour l'utilisateur en fonction de ses paramètres. Selon le paramètre launchMode, Play lance l'URI du lien dans un navigateur externe ou renvoie le flux à votre application pour lancer l'URI. Dans la plupart des cas, vous pouvez utiliser le LAUNCH_IN_EXTERNAL_BROWSER_OR_APP mode, dans lequel Play lance l'URI pour vous. Si vous souhaitez un comportement plus personnalisé, par exemple lancer l'URI dans une WebView ou l'ouvrir dans un navigateur spécifique, vous pouvez utiliser le CALLER_WILL_LAUNCH_LINK mode. Pour protéger la confidentialité des utilisateurs, assurez-vous qu'aucune information permettant d'identifier personnellement l'utilisateur (PII) n'est transmise dans l'URI.

Kotlin

// An activity reference from which the external offers flow will be launched.
val activity = this.activity

val params =
    LaunchExternalLinkParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
        // You can pass along the external transaction token from
        // BillingProgramReportingDetails as a URL parameter in the URI
        .setLinkUri(yourLinkUri)
        .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
        .setLaunchMode(
            LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP
        )
        .build()

val listener: LaunchExternalLinkResponseListener =
    LaunchExternalLinkResponseListener { billingResult ->
        if (billingResult.responseCode == BillingResponseCode.OK) {
            // Proceed with the rest of the external offer flow. If the user
            // purchases an item, be sure to report the transaction to Google Play.
        } else {
            // Handle failures such as retrying due to network errors.
        }
    }

billingClient.launchExternalLink(activity, params, listener)

Java


// An activity reference from which the external offers flow will be launched.
Activity activity = ...;

LaunchExternalLinkParams params = LaunchExternalLinkParams.newBuilder()
  .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
  // You can pass along the external transaction token from  
  // BillingProgramReportingDetails as a URL parameter in the URI
  .setLinkUri(yourLinkUri)
  .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
  .setLaunchMode(
    LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
  .build();

LaunchExternalLinkResponseListener listener =
  new LaunchExternalLinkResponseListener() {
    @Override
    public void onLaunchExternalLinkResponse(BillingResult billingResult) {
      if (billingResult.responseCode == BillingResponseCode.OK) {
        // Proceed with the rest of the external offer flow. If the user
        // purchases an item, be sure to report the transaction to Google
        // Play.
      } else {
        // Handle failures such as retrying due to network errors.
      }
    }
  }

billingClient.launchExternalLink(activity, params, listener);

Si vous définissez LaunchMode sur CALLER_WILL_LAUNCH_LINK, vous ne devez rediriger l'utilisateur en dehors de l'application que si onLaunchExternalLinkResponse fournit BillingResponseCode.OK.

Signaler des transactions à Google Play

Vous devez signaler toutes les transactions externes à Google Play en appelant l'API Google Play Developer depuis votre backend. Lorsque vous signalez une transaction, vous devez fournir un externalTransactionToken obtenu à partir de l' createBillingProgramReportingDetailsAsync API. Si un utilisateur effectue plusieurs achats, vous pouvez utiliser le même externalTransactionToken pour signaler chaque achat. Pour savoir comment signaler une transaction, consultez le guide d'intégration du backend.

Gestion des réponses

En cas d'erreur, les méthodes isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync() et launchExternalLink() peuvent renvoyer des réponses autres que BillingResponseCode.OK. Envisagez de gérer ces codes de réponse comme suit :

  • ERROR : il s'agit d'une erreur interne. Ne poursuivez pas la transaction ni l'ouverture du site Web externe. Réessayez en appelant launchExternalLink() 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.
  • FEATURE_NOT_SUPPORTED: les API d'offres 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.
  • USER_CANCELED : ne poursuivez pas l'ouverture du site Web externe. Appelez à nouveau launchExternalLink() 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.
  • BILLING_UNAVAILABLE: la transaction n'est pas éligible aux offres externes 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 gestion 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 offres externes

Les testeurs de licence doivent être utilisés pour tester votre intégration d'offres externes. Les transactions initiées par des comptes de testeurs de licence ne vous seront pas facturées. Pour en savoir plus sur la configuration des testeurs de licence, consultez la section Tester la facturation des achats in-app avec les licences d'application pour plus d'informations.

Étapes suivantes

Une fois que vous avez terminé l'intégration dans l'application, vous pouvez intégrer le backend.