Le système de facturation de Google Play est un service qui vous permet de vendre des produits et des contenus numériques dans votre application Android. Avec la version de mai 2022, nous avons modifié la définition des produits sur abonnement, ce qui influence la manière dont ils sont vendus dans l'application et gérés sur votre backend. Si vous effectuez une intégration avec Google Play Billing pour la première fois, vous pouvez commencer par lire la section Préparation.
Si vous vendiez des abonnements avec Google Play Billing avant mai 2022, il est important de comprendre comment adopter de nouvelles fonctionnalités tout en conservant vos abonnements existants.
Tout d'abord, sachez que tous vos abonnements, applications et intégrations backend existants fonctionnent exactement comme avant la version de mai 2022. Vous n'avez pas à les modifier immédiatement et vous pouvez adopter ces nouvelles fonctionnalités petit à petit. Chaque version majeure de la Bibliothèque Google Play Billing est compatible pendant deux ans après sa sortie. Les intégrations existantes avec l'API Google Play Developer continuent de fonctionner comme avant.
Voici un aperçu des nouveautés de mai 2022 :
- La nouvelle Google Play Console vous permet de créer et de gérer des abonnements, des forfaits de base et des offres. Cela inclut les nouveaux abonnements et les migrations.
- L'API Play Developer contient des mises à jour compatibles avec la nouvelle fonctionnalité de l'interface utilisateur de la Google Play Console sous forme d'API. Il existe d'ailleurs une nouvelle version de l'API Subscription Purchases. Cette API vous permet de vérifier l'état des abonnements et de gérer leurs achats.
- La nouvelle Bibliothèque Play Billing 5 permet à votre application de bénéficier des dernières fonctionnalités d'abonnement. Lorsque vous êtes prêt à passer à la version 5, suivez les instructions du guide de migration.
Configuration des abonnements
Gérer les abonnements via la Google Play Console
En mai 2022, vous remarquerez quelques différences dans la Google Play Console.
Un même abonnement peut désormais comporter plusieurs offres et forfaits de base. Les codes SKU d'abonnements créés précédemment apparaissent désormais dans la Play Console sous la forme de nouveaux objets "Abonnement", "Forfait de base" et "Offre". Si vous ne l'avez pas déjà fait, consultez les modifications récentes apportées aux abonnements dans la Play Console pour obtenir une description des nouveaux objets, y compris leur fonctionnalité et leur configuration. Tous vos anciens produits sur abonnement apparaissent dans la Google Play Console dans ce nouveau format. Chaque code SKU est désormais représenté par un objet d'abonnement contenant un seul forfait de base et une offre rétrocompatible, le cas échéant.
Comme les anciennes intégrations s'attendaient à ce que chaque abonnement n'inclue qu'une seule offre, représentée par un objet SkuDetails, chaque abonnement peut avoir une offre ou un forfait de base rétrocompatible.
L'offre ou le forfait de base rétrocompatible est renvoyé dans un code SKU pour les applications qui utilisent la méthode querySkuDetailsAsync(), désormais obsolète.
Pour en savoir plus sur la configuration et la gestion des offres rétrocompatibles, consultez l'article Comprendre les abonnements. Une fois que votre application n'utilise que queryProductDetailsAsync() et qu'aucune ancienne version n'effectue encore des achats, vous n'avez plus besoin d'utiliser une offre rétrocompatible.
Gérer les abonnements via l'API Subscriptions Publishing
L'API Play Developer contient une nouvelle fonctionnalité pour les abonnements. L'API inappproducts pour la gestion des codes SKU continue de fonctionner comme auparavant, et continue à gérer les abonnements et produits à achat unique de façon à ce que vous n'ayez pas à implémenter de modification pour maintenir votre intégration.
Toutefois, il est important de noter que la Google Play Console n'utilise que les nouvelles entités d'abonnement. Une fois que vous avez commencé à modifier vos abonnements dans la Console, vous ne pouvez plus utiliser l'API inappproducts pour les abonnements.
Pour éviter tout problème, si vous avez utilisé l'API Publishing avant mai 2022, tous les abonnements existants apparaissent désormais en lecture seule dans la Google Play Console. Si vous essayez de les modifier, un avertissement vous expliquant cette restriction peut s'afficher Avant de modifier d'autres abonnements dans la Console, vous devez mettre à jour l'intégration de votre backend pour qu'il utilise les nouveaux points de terminaison de Subscription Publishing. Les nouveaux points de terminaison monetization.subscriptions, monetization.subscriptions.baseplans et monetization.subscriptions.offers vous permettent de gérer l'ensemble des offres et des forfaits de base disponibles. Dans le tableau ci-dessous, vous pouvez voir comment les différents champs de l'entité InAppProduct sont mappés avec les nouveaux objets sous monetization.subscriptions dans le tableau suivant.
| InAppProduct | Abonnement |
|---|---|
packageName |
packageName |
sku |
productId |
status |
basePlans[0].state |
prices |
basePlans[0].regionalConfigs.price |
listings |
listings |
defaultPrice |
Aucune équivalence |
subscriptionPeriod |
basePlans[0].autoRenewingBasePlanType.billingPeriodDuration |
trialPeriod |
basePlans[0].offers[0].phases[0].regionalConfigs[0].free |
gracePeriod |
basePlans[0].autoRenewingBasePlanType.gracePeriodDuration |
subscriptionTaxesAndComplianceSettings |
taxAndComplianceSettings |
Cette mise à jour obligatoire de l'API ne s'applique qu'à l'API Publishing (gestion des codes SKU).
Modifications apportées à la Bibliothèque Play Billing
Pour permettre une migration progressive, la Bibliothèque Play Billing inclut toutes les méthodes et tous les objets disponibles dans les versions précédentes.
Les objets et fonctions SkuDetails tels que querySkuDetailsAsync() n'ont pas disparu pour vous permettre d'effectuer une mise à niveau afin d'utiliser de nouvelles fonctionnalités sans avoir à mettre à jour immédiatement les codes d'abonnement existants.
Vous pouvez également contrôler les offres disponibles via ces méthodes en les marquant comme rétrocompatibles.
En plus de conserver les anciennes méthodes, la Bibliothèque Play Billing 5 inclut désormais un nouvel objet ProductDetails et une méthode queryProductDetailsAsync() correspondante pour gérer les nouvelles entités et fonctionnalités. Les produits intégrés existants (achats uniques et consommables) sont maintenant compatibles avec ProductDetails.
Pour un abonnement, ProductDetails.getSubscriptionOfferDetails() renvoie une liste de tous les forfaits et offres de base que l'utilisateur pourrait acheter.
Cela signifie que vous pouvez accéder à toutes les offres et tous les forfaits de base auxquels l'utilisateur peut prétendre, indépendamment de la rétrocompatibilité.
getSubscriptionOfferDetails() renvoie null pour les produits sans abonnement. Pour les achats uniques, vous pouvez utiliser getOneTimePurchaseOfferDetails().
La Bibliothèque Play Billing 5 inclut également les nouvelles et anciennes méthodes pour lancer le parcours d'achat. Si l'objet BillingFlowParams transmis à BillingClient.launchBillingFlow() est configuré à l'aide d'un objet SkuDetails, le système extrait les informations de l'offre à vendre du forfait de base rétrocompatible ou de l'offre correspondant au code SKU. Si l'objet BillingFlowParams transmis à BillingClient.launchBillingFlow() est configuré à l'aide d'objets ProductDetailsParams, qui incluent ProductDetails et une String (Chaîne) représentant le jeton d'offre spécifique à l'offre achetée, le système utilise ensuite ces informations pour identifier le produit acquis par l'utilisateur.
queryPurchasesAsync() retourne tous les achats appartenant à l'utilisateur. Pour indiquer le type de produit demandé, vous pouvez transmettre une valeur BillingClient.SkuType, comme dans les versions antérieures, ou un objet QueryPurchasesParams contenant une valeur BillingClient.ProductType qui représente les nouvelles entités d'abonnement.
Nous vous recommandons de mettre à jour vos applications vers la version 5 de la bibliothèque dès maintenant pour commencer à profiter de ces nouvelles fonctionnalités d'abonnement.
Gérer l'état d'un abonnement
Cette section décrit les principales modifications apportées aux composants backend d'une intégration du système de facturation Google Play qui doivent être implémentées pour migrer vers la version 5.
Notifications en temps réel pour les développeurs
L'objet SubscriptionNotification ne contiendra bientôt plus de subscriptionId. Si vous utilisez ce champ pour identifier le produit sur abonnement, vous devez le mettre à jour pour obtenir cette information à partir de l'état de l'abonnement en utilisant purchases.subscriptionv2:get une fois la notification reçue. Chaque élément SubscriptionPurchaseLineItem dans la collection lineItems, qui est renvoyé dans l'état de l'achat contiendra le productId correspondant.
API Subscriptions Purchases : obtenir l'état de l'abonnement
Dans les versions précédentes de l'API Subscriptions Purchases, vous pouviez interroger l'état de l'abonnement à l'aide de purchases.subscriptions:get.
Ce point de terminaison n'est pas modifié et continue de fonctionner pour les achats d'abonnements rétrocompatibles. Ce point de terminaison n'est pas compatible avec les nouvelles fonctionnalités de la version de mai 2022.
Dans la nouvelle version de l'API Subscriptions Purchases, utilisez purchases.subscriptionsv2:get pour obtenir l'état d'achat de l'abonnement. Cette API est compatible avec les abonnements migrés, les nouveaux abonnements (prépayés et à renouvellement automatique) et les achats de tous types. Vous pouvez utiliser ce point de terminaison pour vérifier l'état de l'abonnement lorsque vous recevez des notifications. L'objet renvoyé, SubscriptionPurchaseV2, contient de nouveaux champs, mais inclut toujours les anciennes données nécessaires pour continuer à prendre en charge les abonnements existants.
Champs SubscriptionPurchaseV2 pour les forfaits prépayés
De nouveaux champs ont été ajoutés pour prendre en charge les forfaits prépayés prolongés par l'utilisateur au lieu d'être renouvelés automatiquement. Tous les champs s'appliquent aux forfaits prépayés, comme c'est le cas pour les abonnements à renouvellement automatique, à quelques exceptions près :
- [New field] lineItems[0].prepaid_plan.allowExtendAfterTime : indique quand un utilisateur sera autorisé à acheter une autre recharge pour prolonger son forfait prépayé, puisqu'un utilisateur ne peut posséder qu'une recharge non consommée à la fois.
- [New field] SubscriptionState : spécifie l'état des objets d'abonnement.
Pour les forfaits prépayés, cette valeur est toujours
ACTIVE,PENDINGouCANCELED. - lineItems[0].expiryTime : ce champ est toujours présent pour les forfaits prépayés.
- paused_state_context : ce champ n'est jamais présent, car les forfaits prépayés ne peuvent pas être suspendus.
- lineItems[0].auto_renewing_plan : non disponible pour les forfaits prépayés.
- canceled_state_context : non disponible pour les forfaits prépayés, car ce champ s'applique uniquement aux utilisateurs qui annulent activement un abonnement.
- lineItems[0].productId : ce champ remplace
subscriptionIddes versions précédentes.
Champs SubscriptionPurchaseV2 pour les abonnements récurrents
purchases.subscriptionv2 contient de nouveaux champs qui fournissent plus de détails sur les nouveaux objets d'abonnement. Le tableau suivant montre comment les champs de l'ancien point de terminaison de l'abonnement sont mappés avec les champs correspondants dans purchases.subscriptionv2.
| SubscriptionPurchase | SubscriptionPurchaseV2 |
|---|---|
countryCode |
regionCode |
orderId |
latestOrderId |
| (aucun champ équivalent) | lineItems (liste de SubscriptionPurchaseLineItem) qui représente les produits acquis lors de l'achat |
| (aucun champ équivalent) | lineItems.offerDetails.basePlanId |
| (aucun champ équivalent) | lineItems.offerDetails.offerId |
| (aucun champ équivalent) | lineItems.offerDetails.offerTags |
startTimeMillis |
startTime |
expiryTimeMillis |
lineItems.expiryTime (chaque abonnement acquis lors de l'achat possède sa propre date d'expiration (expiryTime)) |
| (aucun champ équivalent) | subscriptionState (indique l'état de l'abonnement) |
| (aucun champ équivalent) | pausedStateContext (uniquement si l'état de l'abonnement est SUBSCRIPTION_STATE_PAUSED) |
autoResumeTimeMillis |
pausedStateContext.autoResumeTime |
| (aucun champ équivalent) | canceledStateContext (uniquement si l'état de l'abonnement est SUBSCRIPTION_STATE_CANCELED) |
| (aucun champ équivalent) | testPurchase (uniquement pour les achats de testeurs agréés) |
autoRenewing |
lineItems.autoRenewingPlan.autoRenewEnabled |
priceCurrenceCode, priceAmountMicros, introductoryPriceInfo |
(aucun champ équivalent) Ces informations sont disponibles dans basePlan/offer pour chacun des abonnements souscrits. |
| developerPayload | (aucun champ équivalent) la charge utile du développeur est obsolète |
| paymentState | (aucun champ équivalent) Vous pouvez déduire l'état du paiement à partir de subscriptionState :
|
cancelReason, userCancellationTimeMillis, cancelSurveyResult |
canceledStateContext |
linkedPurchaseToken |
linkedPurchaseToken (aucune modification) |
purchaseType |
Test : grâce à testPurchasePromotion : (aucun champ équivalent) ; bientôt disponible |
priceChange |
lineItems.autoRenewingPlan.priceChangeDetails |
profileName, emailAddress, givenName, familyName, profileId |
subscribeWithGoogleInfo |
acknowledgementState |
acknowledgementState (no change) |
promotionType, promotionCode |
(aucun champ équivalent) ; bientôt disponible |
externalAccountId, obfuscatedExternalAccountId, obfuscatedExteranlProfileId |
externalAccountIdentifiers |
Autres fonctions de gestion des abonnements
Alors que purchases.subscriptions:get a été mis à niveau vers purchases.subscriptionsv2:get, les autres fonctions de gestion des abonnements du développeur restent inchangées dans le point de terminaison purchases.subscriptions pour que vous puissiez continuer à utiliser purchases.subscriptions:acknowledge ,purchases.subscriptions:cancel ,purchases.subscriptions:defer ,purchases.subscriptions:refund etpurchases.subscriptions:revoke comme vous le faisiez auparavant.
API Pricing
Utilisez le point de terminaison monetization.convertRegionPrices pour calculer les prix régionaux comme vous le feriez dans la Play Console. Cette méthode accepte un seul prix dans toutes les devises acceptées par Play et renvoie les prix convertis (y compris le taux de taxe par défaut, si applicable) pour toutes les régions où les achats sur Google Play sont disponibles.