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

Ce guide explique comment intégrer les API pour prendre en charge les offres externes dans les applications et 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 conditions 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 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(BillingProgram.EXTERNAL_OFFER)
  .build()

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableBillingProgram(BillingProgram.EXTERNAL_OFFER)
    .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é

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

Cette API renvoie BillingResponseCode.OK si des offres externes sont disponibles. Consultez 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 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. 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 les extensions Kotlin pour ne pas avoir à définir d'écouteur :

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

Lancer le parcours d'offre externe

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

  • linkUri : lien vers le site Web externe où le contenu numérique ou le téléchargement de l'application sont proposés. 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 cette valeur sur LAUNCH_IN_EXTERNAL_BROWSER_OR_APP.
  • billingProgram : définissez cette valeur 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 mode LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, 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 mode CALLER_WILL_LAUNCH_LINK. Pour protéger la confidentialité des utilisateurs, assurez-vous qu'aucune information permettant de les identifier personnellement n'est transmise dans l'URI.

Kotlin


// An activity reference from which the external offers flow will be launched.
val 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 {
      override fun 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)

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'API createBillingProgramReportingDetailsAsync. Si un utilisateur effectue plusieurs achats, vous pouvez utiliser le même externalTransactionToken pour signaler chacun d'eux. Pour savoir comment enregistrer 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. Voici comment gérer ces codes de réponse :

  • 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 : n'ouvre pas le site Web externe. Appelez launchExternalLink() à nouveau 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 règle 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 l'intégration de vos 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 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.