Passer de la bibliothèque Google Play Billing 4 ou 5 à la version 6

Cet article explique comment passer de la bibliothèque Google Play Billing 4 ou 5 à la bibliothèque Google Play Billing 6, et décrit comment utiliser les nouvelles fonctionnalités d'abonnement.

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

Présentation

La bibliothèque Google Play Billing 6 s'appuie sur les nouvelles fonctionnalités d'abonnement introduites dans la version 5, avec quelques améliorations en plus. Ces fonctionnalités, qui vous offrent encore plus de moyens de vendre des abonnements, réduit les coûts d'exploitation en vous évitant d'avoir à créer et à gérer un nombre croissant de codes SKU.

Pour en savoir plus sur les nouvelles fonctionnalités introduites avec la bibliothèque Play Billing 5, consultez la section Modifications récentes apportées aux abonnements dans la Play Console.

Mise à niveau de la bibliothèque Play Billing rétrocompatible

Tous les produits existants sur abonnement ont été automatiquement convertis et adoptent ce nouveau modèle dans la version de mai 2022 de la bibliothèque Play Billing 5 et de la nouvelle plate-forme d'abonnement. Autrement dit, vous n'avez pas besoin de modifier la configuration du produit sur abonnement pour disposer d'un catalogue compatible avec les nouvelles versions de la bibliothèque Play Billing. Pour en savoir plus sur façon dont les codes SKU ont été convertis en abonnements rétrocompatibles, consultez la section Gérer les anciens abonnements dans l'article d'aide de la Play Console.

Les anciennes versions de votre application continueront à fonctionner

Si vous disposez d'un catalogue d'abonnements rétrocompatible, toutes les versions existantes de votre application devraient continuer à fonctionner comme prévu pour ces produits. Les achats de produits ponctuels devraient également continuer à fonctionner sans problème dans les anciennes versions.

Les versions de votre application qui utilisent des méthodes obsolètes (querySkuDetailsAsync(), par exemple) ne peuvent pas vendre de forfaits de base ni d'offres non rétrocompatibles. Pour en savoir plus sur les offres rétrocompatibles, consultez l'article du centre d'aide de la Play Console.

Passer à la bibliothèque Play Billing 5 ou 6

Les bibliothèques Play Billing 5 et 6 incluent les méthodes obsolètes querySkuDetailsAsync et BillingFlowParams.Builder.setSkuDetails qui utilisent SkuDetails comme paramètre de flux de facturation. Cela signifie que vous pouvez passer progressivement à la bibliothèque Play Billing 6 en planifiant différentes étapes de migration.

Pour commencer, vous pouvez simplement mettre à jour la version de la bibliothèque, sans modifier le catalogue ni le backend, et tester votre application alors qu'elle utilise encore les méthodes obsolètes. Si vous n'utilisez pas queryPurchases, launchPriceChangeFlow ou setVrPurchaseFlow, elle devrait continuer à fonctionner comme prévu. Par la suite, vous pourrez passer à l'étape supérieure en adoptant complètement les nouvelles fonctionnalités d'abonnement publiées en mai 2022.

Si vous avez déjà adopté ces fonctionnalités avec la migration d'une bibliothèque Google Play Billing 5, vous pouvez passer directement aux sections Mettre à jour la bibliothèque Google Play Billing et Modifier les achats d'abonnements d'un utilisateur. Si vous démarrez avec une version antérieure ou que vous n'avez pas encore complètement adopté les nouvelles fonctionnalités, vous pouvez lire la procédure de migration complète ci-dessous pour découvrir comment procéder.

Procédure de migration complète

Créer des abonnements dans votre catalogue de produits backend

À l'aide de la Play Console ou de l'API Play Developer, vous pouvez désormais configurer un seul abonnement avec plusieurs forfaits de base, chacun avec plusieurs offres. Les offres d'abonnement présentent des modèles de tarification et des options d'éligibilité flexibles. Vous pouvez créer des offres tout au long du cycle de vie de votre abonnement, grâce à divers forfaits à renouvellement automatique et prépayés.

Pour créer des produits, nous vous recommandons de suivre la structure des entités de la nouvelle plate-forme d'abonnement spécifique à l'intégration de la bibliothèque Play Billing 6 avant de migrer votre application. Vous pouvez regrouper dans un seul abonnement les produits en double de votre ancien catalogue qui représentent les mêmes avantages, et utiliser les configurations de forfait de base et d'offre en fonction des options que vous souhaitez proposer. Pour en savoir plus sur cette recommandation, consultez la section Gérer les anciens abonnements de l'article d'aide de la Play Console.

Nous vous recommandons de ne pas modifier les produits d'abonnement convertis après la version de mai 2022. Laissez-les tels qu'ils doivent être vendus avec les versions de votre application à l'aide de méthodes obsolètes (par exemple, querySkuDetailsAsync()) sans introduire de modifications susceptibles d'affecter ces anciens builds.

Lors du processus de conversion, les produits sur abonnement qui étaient disponibles dans votre catalogue avant mai 2022 ont été convertis en lecture seule, afin d'éviter les modifications accidentelles susceptibles de causer des problèmes dans votre intégration existante. Il est possible de modifier ces abonnements, mais cela peut avoir des conséquences sur les intégrations de l'interface et du backend :

• Au niveau de l'interface, les versions de l'application qui utilisent querySkuDetailsAsync() pour obtenir des informations détaillées sur les produits sur abonnement ne peuvent vendre que des forfaits de base et des offres rétrocompatibles. Il ne peut y avoir qu'une seule combinaison de forfait de base et d'offre rétrocompatible. Par conséquent, si vous ajoutez des offres ou des forfaits aux abonnements convertis, les nouvelles offres ou forfaits de base supplémentaires ne pourront pas être vendus pour ces anciennes versions de votre application.

• Sur le backend, si vous modifiez les abonnements qui ont été convertis dans l'UI de la Play Console, vous ne pourrez pas les gérer avec le point de terminaison inappproducts, le cas échéant. Vous devrez également utiliser le nouveau point de terminaison de l'état d'achat (purchases.subscriptionsv2.get) pour gérer les achats de ces abonnements, car l'ancien point de terminaison d'achat (purchases.subscriptions.get) ne renvoie que les données nécessaires pour gérer les achats de forfaits de base et d'offres rétrocompatibles. Consultez la section Gérer l'état des achats d'abonnements pour plus d'informations.

Gérer votre catalogue d'abonnements backend avec la nouvelle API

Si vous gérez automatiquement votre catalogue de produits sur abonnement avec l'API Google Play Developer, vous devrez utiliser les nouveaux points de terminaison de définition des produits sur abonnement pour créer et gérer vos abonnements, vos forfaits de base et vos offres. Consultez le guide des fonctionnalités d'abonnement de mai 2022 pour en savoir plus sur les modifications de l'API du catalogue de produits pour cette version.

Pour migrer un module de gestion automatique du catalogue de produits pour les abonnements Google Play Billing, remplacez l'API inappproducts par la nouvelle API Subscription Publishing afin de gérer et de publier votre catalogue d'abonnements. Il existe trois nouveaux points de terminaison :

• Monetization.subscriptions pour gérer les produits sur abonnement
• Monetization.basePlans pour gérer les forfaits de base des abonnements
• Monetization.offers pour gérer les offres des forfaits de base

Ces nouveaux points de terminaison permettent d'exploiter toutes les nouvelles fonctionnalités de votre catalogue : balises de forfait de base et d'offre, ciblage par régions, forfaits prépayés, etc.

Vous devez toujours utiliser l'API inappproducts afin de gérer un catalogue de produits intégrés à l'application pour les achats ponctuels.

Les versions de votre application qui utilisent des méthodes obsolètes (querySkuDetailsAsync(), par exemple) ne peuvent pas vendre de forfaits de base ni d'offres non rétrocompatibles. Pour en savoir plus sur les offres rétrocompatibles, cliquez ici.

Mettre à jour la Bibliothèque Google Play Billing

Une fois que le catalogue de produits sur abonnement est créé, vous pouvez migrer votre application vers la bibliothèque Google Billing 5. Remplacez la dépendance existante de la bibliothèque Play Billing par la version mise à jour du fichier build.gradle de votre application.

dependencies {
    def billingVersion = "6.0.0"

    implementation "com.android.billingclient:billing:$billingVersion"
}

Votre projet devrait se créer immédiatement, même si vous n'avez modifié aucun appel de méthode, car la bibliothèque Play Billing 6 est rétrocompatible. Le concept de SKU est considéré comme obsolète, mais il est toujours présent pour simplifier le portage des applications.

Initialiser le client de facturation et établir une connexion avec Google Play

Les premières étapes à suivre pour permettre les achats depuis une application Android restent les mêmes :

• Initialiser le client de facturation
• Établir une connexion avec Google Play

Afficher les produits disponibles à l'achat

Pour afficher toutes les offres qu'un utilisateur peut acheter, procédez comme suit :

• Remplacez SkuDetailsParams par QueryProductDetailsParams.
• Modifiez l'appel BillingClient.querySkuDetailsAsync() pour utiliser BillingClient.queryProductDetailsAsync().

Notez que les résultats de la requête sont maintenant ProductDetails au lieu de SkuDetails. Chaque élément ProductDetails contient des informations sur le produit (ID, titre, type, etc.). Pour les produits sur abonnement, ProductDetails contient un élément List<ProductDetails.SubscriptionOfferDetails>, qui correspond à la liste des détails de l'offre d'abonnement. Pour les produits à achat unique, ProductDetails contient un élément ProductDetails.OneTimePurchaseOfferDetails. Ces attributs peuvent servir à déterminer les offres à proposer aux utilisateurs.

L'exemple suivant montre comment votre application peut se présenter avant et après avoir apporté ces modifications :

Avant

val skuList = ArrayList<String>()

skuList.add("up_basic_sub")

val params = SkuDetailsParams.newBuilder()

params.setSkusList(skuList).setType(BillingClient.SkuType.SUBS).build()

billingClient.querySkuDetailsAsync(params) {
    billingResult,
    skuDetailsList ->
    // Process the result
}

List<String> skuList = new ArrayList<>();

skuList.add("up_basic_sub");

SkuDetailsParams.Builder params = SkuDetailsParams.newBuilder();

params.setSkusList(skuList).setType(SkuType.SUBS).build();

billingClient.querySkuDetailsAsync(params,
    new SkuDetailsResponseListener() {
        @Override
        public void onSkuDetailsResponse(BillingResult billingResult,
                List<SkuDetails> skuDetailsList) {
            // Process the result.
        }
    }
);

Après

val productList =
    listOf(
        QueryProductDetailsParams.Product.newBuilder()
            .setProductId("up_basic_sub")
            .setProductType(BillingClient.ProductType.SUBS)
            .build()
    )

val params = QueryProductDetailsParams.newBuilder().setProductList(productList).build()

billingClient.queryProductDetailsAsync(params) {
    billingResult,
    productDetailsList ->
    // Process the result
}

ImmutableList<Product> productList = ImmutableList.of(Product.newBuilder()
                                            .setProductId("up_basic_sub")
                                            .setProductType(ProductType.SUBS)
                                            .build());

QueryProductDetailsParams params = QueryProductDetailsParams.newBuilder()
    .setProductList(productList)
    .build();

billingClient.queryProductDetailsAsync(
        params,
        new ProductDetailsResponseListener() {
                public void onProductDetailsResponse(BillingResult billingResult, List<ProductDetails> productDetailsList) {
                    // Process the result
                }
        }
);

Le rappel pour queryProductDetailsAsync renvoie un élément List<ProductDetails>. Chaque élément ProductDetails contient des informations sur le produit (ID, titre, type, etc.). La principale différence est que les produits sur abonnement contiennent désormais également un élément List<ProductDetails.SubscriptionOfferDetails> contenant toutes les offres accessibles à l'utilisateur.

Comme les versions précédentes de la bibliothèque Play Billing ne sont pas compatibles avec les nouveaux objets (abonnements, forfaits de base, offres, etc.), le nouveau système convertit chaque code SKU d'abonnement en offre ou forfait de base rétrocompatible. Les produits à achat unique disponibles sont également transférés vers un objet ProductDetails. Vous pouvez accéder aux détails de l'offre d'un produit à achat unique à l'aide de la méthode getOneTimePurchaseOfferDetails().

Dans de rares cas, certains appareils ne peuvent pas prendre en charge ProductDetails ni queryProductDetailsAsync(), généralement en raison de versions obsolètes des services Google Play. Pour assurer la compatibilité dans ce scénario, appelez isFeatureSupported() pour la fonctionnalité PRODUCT_DETAILS avant d'appeler queryProductDetailsAsync. Si la réponse est OK, l'appareil est compatible avec cette fonctionnalité. Vous pouvez alors appeler queryProductDetailsAsync(). Si la réponse est FEATURE_NOT_SUPPORTED, vous pouvez demander la liste des produits disponibles rétrocompatibles avec querySkuDetailsAsync(). Pour en savoir plus sur l'utilisation des fonctionnalités de rétrocompatibilité, consultez le guide des fonctionnalités d'abonnement de mai 2022.

Lancer le parcours d'achat de l'offre

Le lancement d'un parcours d'achat pour une offre est très semblable à celui d'un parcours d'achat pour un code SKU. Pour lancer une demande d'achat à l'aide de la version 6, procédez comme suit :

• Au lieu d'utiliser SkuDetails pour BillingFlowParams, préférez ProductDetailsParams.
• Vous pouvez obtenir les détails de l'offre (ID de l'offre, ID du forfait de base, etc.) à l'aide de l'objet SubscriptionOfferDetails.

Pour acheter un produit avec l'offre sélectionnée par l'utilisateur, récupérez l'élément offerToken de l'offre sélectionnée et transmettez-le dans l'objet ProductDetailsParams.

Une fois que vous avez créé un objet BillingFlowParams, le lancement du processus de facturation avec BillingClient reste le même.

L'exemple suivant montre comment votre application peut se présenter avant et après avoir apporté ces modifications :

Avant

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...
// Retrieve a value for "skuDetails" by calling querySkuDetailsAsync().
val billingFlowParams = BillingFlowParams.newBuilder()
                            .setSkuDetails(skuDetails)
                            .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

// An activity reference from which the billing flow will be launched.
Activity activity = ...;
// Retrieve a value for "skuDetails" by calling querySkuDetailsAsync().
BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
        .setSkuDetails(skuDetails)
        .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Après

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...;

val productDetailsParamsList = listOf(
    BillingFlowParams.ProductDetailsParams.newBuilder()
        // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
        .setProductDetails(productDetails)
        // For One-time product, "setOfferToken" method shouldn't be called.
        // For subscriptions, to get the offer token corresponding to the selected
        // offer call productDetails.subscriptionOfferDetails?.get(selectedOfferIndex)?.offerToken
        .setOfferToken(selectedOfferToken)
        .build()
)

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(productDetailsParamsList)
    .build()

// Launch the billing flow
val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

// An activity reference from which the billing flow will be launched.
Activity activity = ...;

ImmutableList<ProductDetailsParams> productDetailsParamsList =
    ImmutableList.of(
        ProductDetailsParams.newBuilder()
             // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
            .setProductDetails(productDetails)
            // For one-time products, "setOfferToken" method shouldn't be called.
            // For subscriptions, to get the offer token corresponding to the selected
            // offer call productDetails.getSubscriptionOfferDetails().get(selectedOfferIndex).getOfferToken()
            .setOfferToken(selectedOfferToken)
            .build()
    );

BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(productDetailsParamsList)
    .build();

// Launch the billing flow
BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

Traiter les achats

Le traitement des achats avec la bibliothèque Google Play Billing 6 reste semblable aux versions précédentes.

Pour extraire tous les achats actifs appartenant à l'utilisateur et rechercher les nouveaux achats, procédez comme suit :

• Au lieu de transmettre une valeur BillingClient.SkuType à queryPurchasesAsync(), transmettez un objet QueryPurchasesParams contenant une valeur BillingClient.ProductType.

L'exemple suivant montre comment votre application peut se présenter avant et après avoir apporté ces modifications :

Avant

billingClient.queryPurchasesAsync(BillingClient.SkuType.SUBS) {
    billingResult,
    purchaseList -> {
        // Process the result
    }
}

billingClient.queryPurchasesAsync(
    BillingClient.SkuType.SUBS,
    new PurchasesResponseListener() {
        public void onQueryPurchasesResponse(
                BillingResult billingResult,
                List<Purchase> purchases) {
            // process the result
        }
    }
);

Après

billingClient.queryPurchasesAsync(
    QueryPurchasesParams.newBuilder()
        .setProductType(BillingClient.ProductType.SUBS)
        .build()
) { billingResult, purchaseList ->
    // Process the result
}

billingClient.queryPurchasesAsync(
    QueryPurchasesParams.newBuilder().setProductType(ProductType.SUBS).build(),
    new PurchasesResponseListener() {
        public void onQueryPurchasesResponse(
                BillingResult billingResult,
                List<Purchase> purchases) {
            // Process the result
        }
    }
);

La procédure à suivre pour gérer les achats hors application et les transactions en attente n'a pas changé.

Gérer l'état des achats d'abonnements avec la nouvelle API dans votre backend

Vous devez migrer le composant de gestion de l'état des achats d'abonnements dans votre backend pour pouvoir gérer les achats des nouveaux produits créés lors des étapes précédentes. Votre composant actuel de gestion de l'état des achats d'abonnements devrait fonctionner normalement pour les produits sur abonnement convertis que vous avez définis avant le lancement de mai 2022. Il devrait suffire à gérer les achats d'offres rétrocompatibles, mais il n'est pas compatible avec les nouvelles fonctionnalités.

Vous devez mettre en œuvre la nouvelle API Subscription Purchases pour le module de gestion de l'état des achats de vos abonnements, qui vérifie l'état des achats et gère les droits d'accès à l'abonnement Play Billing dans votre backend. L'ancienne version de l'API ne renvoie pas tous les détails nécessaires pour gérer les achats sur la nouvelle plate-forme. Pour en savoir plus sur les modifications apportées aux versions précédentes, consultez les nouvelles fonctionnalités d'abonnement de mai 2022.

Vous devez généralement appeler l'API Subscription Purchases chaque fois que vous recevez une notification en temps réel pour les développeurs SubscriptionNotification afin d'obtenir les dernières informations sur l'état de l'abonnement. Remplacez vos appels vers purchases.subscriptions.get par la nouvelle version de l'API Subscription Purchases, purchases.subscriptionsv2.get. Une nouvelle ressource appelée SubscriptionPurchaseV2 fournit suffisamment d'informations pour gérer les droits d'achat des abonnements dans le nouveau modèle.

Ce nouveau point de terminaison renvoie l'état de tous vos produits sur abonnement et de tous vos achats, quelle que soit la version de l'application qui les a vendus et la date à laquelle le produit a été défini (avant ou après la version de mai 2022). Après la migration, vous n'aurez besoin que de cette version du module de gestion de l'état des achats d'abonnements.

Modifier les achats d'abonnements d'un utilisateur

Dans la bibliothèque Play Billing 5 et les versions antérieures, ProrationMode permettait d'appliquer les modifications apportées aux achats d'abonnements d'un utilisateur, telles que le passage à un forfait supérieur ou inférieur. Cette version est obsolète et a été remplacée par ReplacementMode dans la version 6.

Gérer les changements de prix des abonnements

L'API launchPriceConfirmationFlow, désormais obsolète, a été supprimée de la bibliothèque Play Billing 6. Pour découvrir d'autres options, consultez le Guide des changements de prix.

Gérer les erreurs de la bibliothèque Play Billing

Dans la bibliothèque Play Billing 6, un nouveau code NETWORK_ERROR a été ajouté pour indiquer les problèmes de connexion réseau entre l'appareil de l'utilisateur et le système Google Play. Des modifications ont également été apportées aux codes SERVICE_TIMEOUT et SERVICE_UNAVAILABLE. Pour en savoir plus, consultez Gérer les codes de réponse BillingResult.

Gérer les transactions en attente

À partir de la version 6.0.0, la bibliothèque Play Billing ne crée plus d'ID de commande pour les achats en attente. Pour ces achats, l'ID de commande est renseigné une fois que l'achat passe à l'état PURCHASED. Assurez-vous que votre intégration n'attend un ID de commande qu'une fois la transaction terminée. Vous pouvez toujours utiliser le jeton d'achat pour vos enregistrements. Pour en savoir plus sur la gestion des achats en attente, consultez le guide d'intégration de la bibliothèque Play Billing et le guide de gestion du cycle de vie des achats.