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

Ce document explique comment passer de la bibliothèque Google Play Billing (PBL) 7 ou 8 à 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

La PBL 9 apporte des améliorations aux API existantes et supprime les 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 la PBL

Pour passer à la 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.

Passer de la PBL 7 ou 8 à la PBL 9

Pour passer de la PBL 7 ou 8 à la 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.1.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.1.0"
  implementation("com.android.billingclient:billing-ktx:$billing_version")
}

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

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

  3. Gérez les API supprimées.

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

    Mise à niveau depuis

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

    API précédemment obsolète supprimée API alternative à utiliser
    API queryPurchaseHistoryAsync Consultez Lancer une requête sur 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 de SKU obsolètes.
    SkuDetails ProductDetails. Il s'agit du nouveau modèle de données compatible avec les produits uniques.
    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 backend.
    • Utilisez l'API Voided Purchases côté serveur pour les achats annulés ou annulés.
    getSkuDetailsList et setSkuDetailsList Utilisez BillingFlowParams.Builder.setProductDetailsParamsList
    querySkuDetailsAsync queryProductDetailsAsync
    enablePendingPurchases() (API sans paramètres) enablePendingPurchases(PendingPurchasesParams params)
    Notez que la méthode obsolète enablePendingPurchases() est fonctionnellement équivalente à enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()).
    queryPurchasesAsync(String skuType, PurchasesResponseListener listener) queryPurchasesAsync

    Mise à niveau depuis

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

    API précédemment obsolète supprimée API alternative à utiliser
    BillingClient.SkuType BillingClient.ProductType. Les constantes de type de produit INAPP et SUBS restent fonctionnellement similaires aux constantes de type de SKU obsolètes.
    SkuDetails ProductDetails. Il s'agit du nouveau modèle de données compatible avec les produits uniques.
    SkuDetailsParams Utilisez QueryProductDetailsParams avec queryProductDetailsAsync.
    SkuDetailsResponseListener Utilisez ProductDetailsResponseListener avec queryProductDetailsAsync.
    QueryPurchaseHistoryParams
    • Utilisez queryProductDetailsAsync pour les achats actifs ou en attente.
    • Suivez les achats consommés sur vos serveurs backend.
    • Utilisez l'API Voided Purchases côté serveur pour les achats annulés ou annulés.
    getSkuDetailsList et setSkuDetailsList Utilisez BillingFlowParams.Builder.setProductDetailsParamsList

  4. (Recommandé) Activez la reconnexion automatique au 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 au service.

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

    Le BillingResult renvoyé par launchBillingFlow() inclura 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 exigences d'éligibilité configurées 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 PurchasesUpdatedListener ou la gestion des résultats é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 invitant l'utilisateur à corriger ses modes de paiement ou en affichant un message d'erreur spécifique.

  6. Prise en compte de la reclassification des codes d'erreur.

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

    Étape de migration : Assurez-vous que votre logique de gestion des erreurs tient compte de cette modification 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() est désormais @Nullable.

    Étape de migration : Pour gérer cette modification en toute sécurité, assurez-vous que votre code d'intégration gère les valeurs null et les chaînes vides ("") de la méthode DeveloperProvidedBillingDetails.getLinkUri() avant d'analyser ou de lancer des intents de navigateur. Exemple :

    Kotlin

    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.