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 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 la bibliothèque Play Billing

Pour migrer vers PBL 9, vous devez mettre à jour ou supprimer certaines de vos références d'API existantes de 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 bibliothèque PBL 7 ou 8 à la bibliothèque 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 PBL 7 vers PBL 9). Mettez à jour l'implémentation de la méthode queryProductDetailsAsync.

    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 de queryProductDetailsAsync. Pour en savoir plus, consultez Afficher les produits disponibles à l'achat.

  3. Gérer les API supprimées

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

    Mettre à niveau depuis

    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 de remplacement correspondantes.

    Suppression de l'API précédemment obsolète API alternative à utiliser
    API queryPurchaseHistoryAsync Consultez Interroger l'historique des achats. Si vous utilisiez queryPurchaseHistoryAsync pour déterminer l'éligibilité aux essais sans frais, vous devez désormais 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 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 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 enablePendingPurchases() obsolète est fonctionnellement équivalente à enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()).
    queryPurchasesAsync(String skuType, PurchasesResponseListener listener) queryPurchasesAsync

    Mettre à niveau depuis

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

    Suppression de l'API précédemment obsolète 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 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 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 n'est 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 remplit pas les 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 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'offrir une meilleure expérience utilisateur. Par exemple, en invitant l'utilisateur à corriger les modes de paiement ou en affichant un message d'erreur spécifique.

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

    Lorsque 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 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érer 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 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 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.