Guide de migration de la bibliothèque Google Play Billing 4 vers Google Play Billing 5

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

Présentation

La bibliothèque Google Play Billing 5 inclut des forfaits de base et des offres d'abonnement. Ces fonctionnalités élargissent la manière dont vous pouvez vendre des abonnements. Comme il n'est plus nécessaire de créer ni de gérer un nombre croissant de SKU, les coûts d'exploitation sont réduits. Pour en savoir plus, consultez la section Modifications récentes apportées aux abonnements dans la Play Console.

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. Pour en savoir, consultez la section Gérer les anciens abonnements de l'article d'aide de la Play Console.

À 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 d'un abonnement en utilisant différents forfaits à renouvellement automatique ou prépayés. Pour en savoir plus, consultez le guide d'intégration.

Toutefois, si vous ne prévoyez pas d'adopter ces nouvelles fonctionnalités immédiatement, vous pouvez toujours migrer votre application vers la bibliothèque Play Billing 5 et planifier la migration de vos composants backend ultérieurement, à condition que votre catalogue de produits reste dans une configuration rétrocompatible.

Procédure de migration

Créer votre catalogue de produits backend

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 5 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 :

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 = "5.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 nous avons intégré la rétrocompatibilité dans la bibliothèque Play Billing 5. Toutefois, le concept de SKU est considéré comme obsolète.

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

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

Affichage des 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

Kotlin

val skuList = ArrayList<String>()

skuList.add("up_basic_sub")

val params = SkuDetailsParams.newBuilder()

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

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

Java

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

skuList.add("up_basic_sub");

SkuDetailsParams.Builder params = SkuDetailsParams.newBuilder();

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

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

Après

Kotlin

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

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

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

Java

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 savoir comment utiliser les fonctionnalités de rétrocompatibilité de la bibliothèque Play Billing 5, consultez le guide sur les 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 5, 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

Kotlin

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

Java

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

Kotlin

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...;
// Retrieve a value for "productDetails" by calling queryProductDetailsAsync()
// Get the offerToken of the selected offer
val offerToken = productDetails.subscriptionOfferDetails?.get(selectedOfferIndex)?.offerToken

val productDetailsParamsList =
    listOf(
        BillingFlowParams.ProductDetailsParams.newBuilder()
            .setProductDetails(productDetails)
            .setOfferToken(offerToken)
            .build()
    )
val billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(productDetailsParamsList)
        .build()

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

Java

// Retrieve a value for "productDetails" by calling queryProductDetailsAsync()
// Get the offerToken of the selected offer
String offerToken = productDetails
                     .getSubscriptionOfferDetails()
                     .get(selectedOfferIndex)
                     .getOfferToken();
// Set the parameters for the offer that will be presented
// in the billing flow creating separate productDetailsParamsList variable
ImmutableList<ProductDetailsParams> productDetailsParamsList =
        ImmutableList.of(
                 ProductDetailsParams.newBuilder()
                     .setProductDetails(productDetails)
                     .setOfferToken(offerToken)
                     .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 5 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

Kotlin

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

Java


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

Après

Kotlin

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

Java

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.