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 les critères d'éligibilité et la portée géographique, consultez Conditions du programme.

Configuration de la bibliothèque Play Billing

Pour utiliser les API d'offres externes, ajouter la version 6.2.1 ou une version 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 suivez les instructions du guide de migration avant d'essayer d'implémenter les offres externes.

Se connecter à Google Play

Les premières étapes du processus d'intégration sont les mêmes que celles décrites dans la section le guide d'intégration de la facturation, en apportant quelques modifications au moment Initialisation de votre BillingClient:

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

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

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

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 la disponibilité des offres externes en appelant isExternalOfferAvailableAsync

Cette API renvoie BillingResponseCode.OK si des offres externes sont disponibles. Consultez la section Gestion des réponses pour en savoir plus sur la manière dont votre application doit répondre à d'autres codes de réponse.

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.
})

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 jeton de transaction généré à partir de la bibliothèque Play Billing. Une nouvelle instance le jeton de transaction doit être généré chaque fois que l'utilisateur accède à via l'API d'offres externes. Pour ce faire, appelez la méthode API createExternalOfferReportingDetailsAsync. Ce jeton doit être immédiatement avant que l'utilisateur ne soit redirigé en dehors de l'application. Il doit ne doivent jamais être mis en cache, et un nouveau mot de passe doit être généré chaque fois que l'utilisateur est redirigé en dehors de l'application.

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.
    }
})

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 permettre l'intégration avec des offres externes, votre appli éligible doit afficher des informations un écran qui aide les utilisateurs à comprendre qu'ils sont sur le point d'être dirigés vers l'extérieur l'application vers un site Web externe. L'écran d'informations doit être présenté aux utilisateurs appeler l'API showExternalOfferInformationDialog avant de procéder à l'association à un une offre externe à chaque fois.

// 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)

// 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 passer à rediriger l'utilisateur vers le site Web externe. Si la méthode renvoie BillingResponseCode.USER_CANCELED, votre application ne doit pas continuer à ouvrir le sur votre site Web.

Enregistrer des transactions dans Google Play

Toutes les transactions externes doivent être signalées à Google Play en appelant l'API Google Play Developer depuis votre backend. Transactions externes doit être signalé tout en fournissant externalTransactionToken obtenu à l'aide de API createExternalOfferReportingDetailsAsync. Si un utilisateur effectue plusieurs achats, vous pouvez utiliser le même externalTransactionToken pour enregistrer chaque achat. Pour savoir comment signaler un , consultez le guide d'intégration du backend.

Gestion des réponses

Lorsqu'une erreur se produit, les méthodes isExternalOfferAvailableAsync, createExternalOfferReportingDetailsAsync showExternalOfferInformationDialog peut 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 en ouvrant le site Web externe. Réessayez en appelant showExternalOfferInformationDialog() pour afficher les informations 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 en ouvrant le site Web externe.
• USER_CANCELED: ne poursuivez pas l'ouverture du site Web externe. Appeler showExternalOfferInformationDialog() pour afficher les 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 poursuivre ce programme. Cela peut être dû au l'utilisateur ne se trouve pas dans un pays éligible à ce programme ou votre compte a ne pas avoir été correctement 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: il s'agit les erreurs temporaires qui doivent être traité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 des offres externes

Nous vous conseillons de faire appel à des testeurs de licence pour tester l'intégration de vos offres externes. Toi ne seront pas facturées pour les transactions initiées par les testeurs de licence Google Cloud. Pour en savoir plus, consultez Tester la facturation des achats in-app avec les licences d'application. des informations sur la configuration des testeurs de licence.

Étapes suivantes

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