Conseils sur l'intégration dans l'application pour les liens vers des contenus externes

Ce document explique comment intégrer les API de la bibliothèque Play Billing pour proposer des liens vers du contenu externe dans les applications éligibles. Cela inclut la possibilité de rediriger les utilisateurs aux États-Unis en dehors de votre application Play pour leur proposer des offres de contenu numérique intégré et de téléchargements d'applications. 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 liens externes, la version 8.2 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 avant d'ajouter les liens vers le contenu externe.

Initialiser le client de facturation

Pour initialiser le client de facturation, suivez les mêmes étapes que celles décrites dans Initialiser un BillingClient, avec les modifications suivantes :

  • N'activez pas PurchasesUpdatedListener, car cet écouteur n'est pas nécessaire pour les liens vers des contenus externes.
  • Appelez enableBillingProgram() avec BillingProgram.EXTERNAL_CONTENT_LINK pour indiquer que votre application utilise des liens vers des contenus externes.

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

Kotlin

val billingClient = BillingClient.newBuilder(context)
  .enableBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
  .build()

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .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 vous êtes connecté à Google Play, vous devez vérifier si l'utilisateur est éligible au programme de liens vers des contenus externes en appelant la méthode isBillingProgramAvailableAsync(). Cette méthode renvoie BillingResponseCode.OK si l'utilisateur est éligible au programme de liens vers des contenus externes. L'exemple suivant montre comment vérifier l'éligibilité de l'utilisateur aux liens vers des contenus externes :

Kotlin

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_CONTENT_LINK,
  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 content links unavailable, etc.
            return
        }

        // External content links are available. Prepare an external
        // transaction token.
      }
    })

Java

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_CONTENT_LINK,
  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 content links unavailable, etc.
            return;
        }

        // External content links are available. Prepare 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.

Préparer un jeton de transaction externe

Vous devez ensuite générer un jeton de transaction externe à 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 externe via l'API External Links. Pour ce faire, appelez l'API createBillingProgramReportingDetailsAsync. Le jeton doit être généré immédiatement avant la redirection de l'utilisateur.

Remarque : Le jeton de transaction externe ne doit jamais être mis en cache. Vous devez générer un nouveau jeton chaque fois que l'utilisateur est redirigé.

Kotlin

val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
        .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 when launchExternalLink is called.
    }
  })

Java

BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
        .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 when launchExternalLink 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 lien externe

Une fois le jeton de transaction externe prêt, l'utilisateur peut être redirigé en dehors de l'application vers une offre de contenu numérique ou un téléchargement d'application en appelant la méthode launchExternalLink. Google Play peut afficher des boîtes de dialogue d'informations supplémentaires à l'utilisateur en fonction de ses paramètres utilisateur lorsque vous appelez cette API.

Lorsque vous appelez la méthode launchExternalLink, vous devez fournir les détails du lien externe via LaunchExternalLinkParams. Cette classe contient les paramètres suivants :

  • URI du lien : 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.
  • Type de lien : type de contenu proposé à l'utilisateur.
  • Mode de lancement : spécifie comment le lien est lancé. Pour les téléchargements d'applications, vous devez définir cette valeur sur LAUNCH_IN_EXTERNAL_BROWSER_OR_APP.

  • Programme de facturation : définissez cette valeur sur BillingProgram.EXTERNAL_CONTENT_LINK.

Kotlin

val params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .setLinkUri(Uri.parse("https://www.myapprovedsite.com"))
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
    .setLaunchMode(
      LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .build()

val listener : LaunchExternalLinkResponseListener =
    object : LaunchExternalLinkResponseListener {
      override fun onLaunchExternalLinkResponse(
        billingResult: BillingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }

        // If Launch Mode was set to LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, the
        // user was directed outside of the app by Play. This does not give
        // any information on the user's actions during the link out, such
        // as if a transaction was completed.

        // If Launch Mode was set to CALLER_WILL_LAUNCH_LINK, then your app
        // may proceed to direct the user to the external website.
    }
}

billingClient.launchExternalLink(activity, params, listener)

Java

LaunchExternalLinkParams params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .setLinkUri(Uri.parse("https://www.myapprovedsite.com"))
    .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.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        // If Launch Mode was set to LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, the
        // user was directed outside of the app by Play. This does not give
        // any information on the user's actions during the link out, such
        // as if a transaction was completed.

        // If Launch Mode was set to CALLER_WILL_LAUNCH_LINK, then your app
        // may proceed to direct the user to the external website.
    }
  }

billingClient.launchExternalLink(activity, params, listener);

Gestion des réponses

En cas d'erreur, les méthodes isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync() et onLaunchExternalLinkResponse() peuvent fournir un BillingResponseCode autre 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 à nouveau l'API ou en appelant launchExternalLink() la prochaine fois que vous tenterez de rediriger l'utilisateur en dehors de l'application.
  • FEATURE_NOT_SUPPORTED : les API de liens vers des contenus 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 la prochaine fois que vous tenterez de rediriger l'utilisateur en dehors de l'application.
  • BILLING_UNAVAILABLE : la transaction n'est pas éligible aux liens vers des contenus 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 liens vers des contenus 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.