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

Ce guide explique comment intégrer les API afin de prendre en charge des 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 portée géographique, consultez les Conditions du programme.

Configuration de la bibliothèque Play Billing

Pour utiliser les API d'offres externes, ajoutez la version 6.2.1 ou ultérieure de la dépendance de la bibliothèque Play Billing à 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, avec quelques différences au niveau de l'initialisation de votre BillingClient:

• Vous devez appeler une nouvelle méthode pour indiquer que vous souhaitez utiliser des offres externes: enableExternalOffer.

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

Kotlin

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

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableExternalOffer()
    .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 que les offres externes sont disponibles en appelant isExternalOfferAvailableAsync.

Cette API renvoie la valeur 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.isExternalOfferAvailableAsync(
  object : ExternalOfferAvailabilityListener {
    override fun onExternalOfferAvailabilityResponse(
      billingResult: BillingResult) {
        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.isExternalOfferAvailableAsync(
  new ExternalOfferAvailabilityListener() {
    @Override
    public void onExternalOfferAvailabilityResponse(
      BillingResult billingResult) {
        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. Un nouveau jeton de transaction externe doit être généré chaque fois que l'utilisateur visite un site Web externe via l'API Externaloffers. Pour ce faire, appelez l'API createExternalOfferReportingDetailsAsync. Ce jeton doit être généré immédiatement avant que l'utilisateur ne soit redirigé vers l'extérieur de l'application. Il ne doit jamais être mis en cache et un nouveau jeton doit être généré chaque fois que l'utilisateur est redirigé vers l'extérieur de l'application.

Kotlin

billingClient.createExternalOfferReportingDetailsAsync(
  object : ExternalOfferReportingDetailsListener {
    override fun onExternalOfferReportingDetailsResponse(
      billingResult: BillingResult,
      externalOfferReportingDetails: ExternalOfferReportingDetails?) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            externalOfferReportingDetails?.externalTransactionToken
        // Persist the transaction token locally. Pass it to the external
        // website when showExternalOfferInformationDialog is called.
    }
})

Java

billingClient.createExternalOfferReportingDetailsAsync(
  new ExternalOfferReportingDetailsListener() {
    @Override
    public void onExternalOfferReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable ExternalOfferReportingDetails
        externalOfferReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          externalOfferReportingDetails.getExternalTransactionToken();

        // Persist the external transaction token locally. Pass it to the
        // external website when showExternalOfferInformationDialog is
        // called.
      }
});

Boîte de dialogue d'informations pour les utilisateurs

Pour intégrer des offres externes, votre application éligible doit afficher un écran d'informations qui aide les utilisateurs à comprendre qu'ils sont sur le point d'être redirigés vers un site Web externe en dehors de l'application. L'écran d'informations doit être présenté aux utilisateurs en appelant l'API showExternalOfferInformationDialog avant de l'associer à une offre externe à chaque fois.

Kotlin

// An activity reference from which the external offers information dialog
// will be launched.
val activity : Activity = ...;

val listener : ExternalOfferInformationDialogListener =
  ExternalOfferInformationDialogListener {
      override fun onExternalOfferInformationDialogResponse(
        billingResult: BillingResult){
        // Check billingResult
    }
}

val billingResult = billingClient.showExternalOfferInformationDialog(
  activity, listener)

Java

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

ExternalOfferInformationDialogListener listener =
  new ExternalOfferInformationDialogListener() {
    @Override
    public void onExternalOfferInformationDialogResponse(
      BillingResult billingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
          // Handle failures such as retrying due to network errors.
        }
        // Open the external website, passing along the external transaction
        // token as a URL parameter. If the user purchases an item, be sure
        // to report the transaction to Google Play.
      }
}

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

Si cette méthode renvoie BillingResponseCode.OK, votre application peut rediriger l'utilisateur vers le site Web externe. Si la méthode renvoie BillingResponseCode.USER_CANCELED, votre application ne doit pas continuer à ouvrir le site Web.

Enregistrer des transactions dans Google Play

Remarque :Consultez S'inscrire au programme d'offres externes pour connaître les exigences concernant les rapports sur les transactions.

Toutes les transactions externes doivent être signalées à Google Play en appelant l'API Google Play Developer depuis votre backend. Les transactions externes doivent être signalées tout en fournissant un externalTransactionToken obtenu à l'aide de l'API createExternalOfferReportingDetailsAsync. Si un utilisateur effectue plusieurs achats, vous pouvez utiliser le même externalTransactionToken pour enregistrer chaque achat. 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 isExternalOfferAvailableAsync, createExternalOfferReportingDetailsAsync et showExternalOfferInformationDialog 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 ou n’ouvrez pas le site web externe. Réessayez en appelant showExternalOfferInformationDialog() 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 ou n’ouvrez pas le site web externe.
• USER_CANCELED: ne pas ouvrir le site Web externe. Appelez à nouveau showExternalOfferInformationDialog() pour afficher la boîte de dialogue d'informations la prochaine fois que vous tenterez de le rediriger en dehors de l'application.
• BILLING_UNAVAILABLE: la transaction n'est pas éligible à des offres externes et ne doit donc pas être traitée par ce programme. Cela peut être dû au fait que l'utilisateur ne se trouve pas dans l'un des pays éligibles à ce programme ou que votre compte n'a pas été inscrit au programme. Dans ce dernier cas, vérifiez l'état 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 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 offres externes

Les testeurs de licence doivent être utilisés pour tester l'intégration de vos offres externes. 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.