Migrer vers la bibliothèque Google Play Billing 9 depuis les versions 7 ou 8

Ce document explique comment migrer de la bibliothèque Google Play Billing (PBL) 7 ou 8 vers la PBL 9 et comment intégrer les nouvelles fonctionnalités.

Pour obtenir la liste complète des modifications apportées à la version 9.0.0, consultez les notes de version.

Présentation

PBL 9 contient des améliorations apportées aux API existantes, ainsi que la suppression des API précédemment obsolètes. Cette version de la bibliothèque introduit également un contexte d'erreur plus riche grâce à de nouveaux codes de sous-réponse.

Rétrocompatibilité pour la mise à niveau de PBL

Pour migrer vers PBL 9, vous devez mettre à jour ou supprimer certaines de vos références d'API existantes dans votre application, comme décrit dans les notes de version et plus loin dans ce guide de migration.

Mettre à niveau PBL 7 ou 8 vers PBL 9

Pour passer de PBL 7 ou 8 à PBL 9, procédez comme suit :

  1. Mettez à jour la version de la dépendance de la bibliothèque Play Billing dans le fichier build.gradle de votre application.

    dependencies {
  def billing_version = "9.0.0"
  implementation "com.android.billingclient:billing:$billing_version"
}

    Si vous utilisez Kotlin, le module KTX de la bibliothèque Google Play Billing contient des extensions et des coroutines Kotlin qui vous permettent d'écrire du code Kotlin idiomatique lors de l'utilisation de la bibliothèque Google Play Billing. Pour inclure ces extensions dans votre projet, ajoutez la dépendance suivante au fichier build.gradle de votre application, comme indiqué ci-dessous :

    dependencies {
  val billing_version = "9.0.0"
  implementation("com.android.billingclient:billing-ktx:$billing_version")
}

  2. (Applicable uniquement pour la mise à niveau de PBL 7 vers PBL 9). Mettez à jour l'implémentation de la méthode queryProductDetailsAsync.

    La signature de la méthode ProductDetailsResponseListener.onProductDetailsResponse a changé, ce qui nécessite des modifications dans votre application pour l'implémentation de queryProductDetailsAsync. Pour en savoir plus, consultez Afficher les produits disponibles à l'achat.

  3. Gérez les API supprimées.

    Le tableau suivant liste les API supprimées et les API alternatives correspondantes que vous devez utiliser dans votre application.

    Mettre à niveau

    PBL 9 n'est plus compatible avec les API listées dans le tableau ci-dessous. Si votre implémentation utilise l'une de ces API supprimées, consultez le tableau pour connaître les API alternatives correspondantes.

    Suppression de l'API précédemment obsolète Autre API à utiliser
    API queryPurchaseHistoryAsync Consultez Interroger l'historique des achats. Si vous utilisiez queryPurchaseHistoryAsync pour déterminer l'éligibilité aux essais sans frais, vous devez maintenant utiliser ProductDetails.getSubscriptionOfferDetails() pour déterminer les offres auxquelles un utilisateur est éligible.
    BillingClient.SkuType BillingClient.ProductType. Les constantes de type de produit INAPP et SUBS restent fonctionnellement similaires aux constantes de type SKU obsolètes.
    SkuDetails ProductDetails. Il s'agit du nouveau modèle de données compatible avec les produits ponctuels.
    SkuDetailsParams Utilisez QueryProductDetailsParams avec queryProductDetailsAsync.
    SkuDetailsResponseListener Utilisez ProductDetailsResponseListener avec queryProductDetailsAsync.
    QueryPurchaseHistoryParams
    • Utilisez queryPurchasesAsync pour les achats actifs ou en attente.
    • Suivez les achats consommés sur vos serveurs de backend.
    • Utilisez l'API Voided Purchases côté serveur pour les achats annulés ou invalidés.
    getSkuDetailsList et setSkuDetailsList Utilisez BillingFlowParams.Builder.setProductDetailsParamsList.
    querySkuDetailsAsync queryProductDetailsAsync
    enablePendingPurchases() (API sans paramètres) enablePendingPurchases(PendingPurchasesParams params)
    Notez que la méthode enablePendingPurchases() obsolète est fonctionnellement équivalente à enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()).
    queryPurchasesAsync(String skuType, PurchasesResponseListener listener) queryPurchasesAsync

    Mettre à niveau

    Le tableau suivant liste les API supprimées dans PBL 9 et les API alternatives correspondantes que vous devez utiliser dans votre application.

    Suppression de l'API précédemment obsolète Autre API à utiliser
    BillingClient.SkuType BillingClient.ProductType. Les constantes de type de produit INAPP et SUBS restent fonctionnellement similaires aux constantes de type SKU obsolètes.
    SkuDetails ProductDetails. Il s'agit du nouveau modèle de données compatible avec les produits ponctuels.
    SkuDetailsParams Utilisez QueryProductDetailsParams avec queryProductDetailsAsync.
    SkuDetailsResponseListener Utilisez ProductDetailsResponseListener avec queryProductDetailsAsync.
    QueryPurchaseHistoryParams
    getSkuDetailsList et setSkuDetailsList Utilisez BillingFlowParams.Builder.setProductDetailsParamsList.

  4. (Recommandé) Activez la reconnexion automatique du service.

    La bibliothèque Play Billing peut tenter de rétablir automatiquement la connexion au service si un appel d'API est effectué alors que le service est déconnecté. Pour en savoir plus, consultez Activer la reconnexion automatique du service.

  5. Gérez les nouveaux codes de sous-réponse.

    Le BillingResult renvoyé par launchBillingFlow() inclut désormais un champ de code de sous-réponse. Ce champ ne sera renseigné que dans certains cas pour fournir une raison plus spécifique de l'échec. Le champ de sous-réponse peut avoir les valeurs suivantes :

    • PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS : renvoyé lorsque les fonds de l'utilisateur sont inférieurs au prix de l'article qu'il tente d'acheter.
    • USER_INELIGIBLE : renvoyé lorsque l'utilisateur ne répond pas aux critères d'éligibilité configurés pour une offre d'abonnement.
    • NO_APPLICABLE_SUB_RESPONSE_CODE : valeur par défaut renvoyée lorsqu'aucun autre code de sous-réponse n'est applicable.

    Étape de migration : Mettez à jour votre gestion des résultats PurchasesUpdatedListener ou équivalente pour reconnaître ces codes de sous-réponse spécifiques et y répondre afin d'améliorer l'expérience utilisateur. Par exemple, en vous invitant à corriger vos modes de paiement ou en affichant un message d'erreur spécifique.

  6. Sensibilisation à la reclassification des codes d'erreur.

    Dans les cas où l'application Play Store est bloquée par le système (par exemple, dans le mode enfant personnalisé par l'OEM), le code de réponse de PBL est passé de ERROR à BILLING_UNAVAILABLE.

    Étape de migration : assurez-vous que votre logique de gestion des exceptions tient compte de ce changement et ne repose pas sur la réception d'une erreur générique dans ces scénarios spécifiques.

  7. Gérez la possibilité de valeur nulle de DeveloperProvidedBillingDetails.getLinkUri().

    Si vous utilisez DeveloperProvidedBillingDetails dans le cadre d'une intégration de paiements externes, getLinkUri() devient @Nullable.

    Étape de migration : Pour gérer ce changement de manière sécurisée, assurez-vous que votre code d'intégration gère à la fois les valeurs null et les valeurs de chaîne vide ("") de la méthode DeveloperProvidedBillingDetails.getLinkUri() avant d'analyser ou de lancer les intents du navigateur. Exemple :

    Kotlin

    val linkUri = details.getLinkUri()
if (!linkUri.isNullOrEmpty()) {
  val intent = Intent(Intent.ACTION_VIEW, Uri.parse(linkUri))
  context.startActivity(intent)
}

    Java

    String linkUri = details.getLinkUri();
if (!android.text.TextUtils.isEmpty(linkUri)) {
  Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(linkUri));
  context.startActivity(intent);
}

  8. Modifications facultatives.