El sistema de facturación de Google Play es un servicio que te permite vender productos y contenido digital en tu app para Android. En la actualización de mayo de 2022, cambiamos la forma en que se definen los productos de suscripción, y esto afecta la forma en que se venden en la app y se administran en tu backend. Si quieres integrar la Facturación Google Play por primera vez, consulta la sección Preparación.
Si vendías suscripciones con Facturación Google Play antes de mayo de 2022, es importante que comprendas cómo adoptar nuevas funciones mientras mantienes tus suscripciones existentes.
Lo primero que debes saber es que todas tus suscripciones, apps e integraciones de backend funcionan como antes de la actualización de mayo de 2022. No es necesario que realices cambios inmediatos y puedes adoptar estas nuevas funciones con el tiempo. Cada versión importante de la Biblioteca de Facturación Google Play es compatible durante los dos años posteriores al lanzamiento. Las integraciones existentes con la API de Google Play Developer siguen funcionando como antes.
A continuación, se incluye una descripción general de las actualizaciones de mayo de 2022:
- La nueva versión de Google Play Console te permite crear y administrar suscripciones, planes básicos y ofertas. Esto incluye las suscripciones nuevas y las migradas.
- La API de Play Developer contiene actualizaciones para admitir la nueva funcionalidad de la IU de Google Play Console en formato de API. En particular, existe una nueva versión de la API de Subscription Purchases. Usa esta API para verificar el estado de la suscripción y administrar las compras de suscripción.
- La nueva Biblioteca de Facturación Play versión 5 permite que tu app se beneficie de todas las funciones nuevas de la suscripción. Cuando tengas todo listo para actualizar a la versión 5, sigue las instrucciones de la guía de migración.
Configuración de suscripciones
Cómo administrar suscripciones a través de Google Play Console
A partir de mayo de 2022, notarás algunas diferencias en Google Play Console.
Una sola suscripción ahora puede tener varios planes básicos y ofertas. Los SKU de suscripción creados anteriormente ahora aparecen en Play Console como nuevos objetos de suscripción, plan básico y oferta. Si aún no lo hiciste, consulta Cambios recientes en las suscripciones en Play Console para obtener descripciones de los objetos nuevos, incluida su funcionalidad y configuración. Todos los productos de suscripción preexistentes aparecen en Google Play Console en este nuevo formato. Cada SKU ahora está representado por un objeto de suscripción que contiene un solo plan básico y una oferta retrocompatible, si corresponde.
Dado que las integraciones anteriores esperaban que cada suscripción incluyera una sola oferta, representada por un objeto SkuDetails, cada suscripción puede tener una sola oferta o plan básico retrocompatible.
La oferta o el plan básico retrocompatible se muestra como parte de un SKU para las apps que usan el método querySkuDetailsAsync() que dejó de estar disponible.
Para obtener más información sobre la configuración y administración de ofertas retrocompatibles, consulta Información sobre las suscripciones. Una vez que la app use solo el elemento queryProductDetailsAsync() y una vez que no haya versiones anteriores de tu app que aún realicen compras, ya no será necesario que uses una oferta retrocompatible.
Administra suscripciones mediante la API de Subscriptions Publishing
La API de Play Developer incluye nuevas funciones para las compras de suscripciones. La API de inappproducts para la administración de SKU sigue funcionando como antes, lo que incluye el manejo de productos y suscripciones de compra única, por lo que no necesitas realizar ningún cambio inmediato para mantener tu integración.
Sin embargo, es importante tener en cuenta que Google Play Console solo usa las nuevas entidades de suscripción. Una vez que comiences a editar tus suscripciones en Console, ya no se podrá usar la API de inappproducts para suscripciones.
Si usaste la API de Publishing antes de mayo de 2022, para evitar problemas, todas las suscripciones existentes ahora aparecen como de solo lectura en Google Play Console. Si intentas realizar cambios, es posible que recibas una advertencia en la que se explique esta limitación. Antes de editar más suscripciones en Console, debes actualizar la integración de backend para usar los extremos de publicación de suscripciones nuevos. Los nuevos extremos monetization.subscriptions, monetization.subscriptions.baseplans y monetization.subscriptions.offers te permiten administrar todas las ofertas y los planes básicos disponibles. Puedes ver cómo se asignan los diferentes campos de la entidad InAppProduct a los objetos nuevos en monetization.subscriptions en la siguiente tabla:
| InAppProduct | Suscripción |
|---|---|
packageName |
packageName |
sku |
productId |
status |
basePlans[0].state |
prices |
basePlans[0].regionalConfigs.price |
listings |
listings |
defaultPrice |
Sin equivalencia |
subscriptionPeriod |
basePlans[0].autoRenewingBasePlanType.billingPeriodDuration |
trialPeriod |
basePlans[0].offers[0].phases[0].regionalConfigs[0].free |
gracePeriod |
basePlans[0].autoRenewingBasePlanType.gracePeriodDuration |
subscriptionTaxesAndComplianceSettings |
taxAndComplianceSettings |
Esta actualización obligatoria de la API solo se aplica a la API de publicación (administración de SKU).
Cambios en la Biblioteca de Facturación Play
Para permitir una migración gradual, la Biblioteca de Facturación Play incluye todos los métodos y objetos disponibles en versiones anteriores.
Aún existen objetos SkuDetails y funciones como querySkuDetailsAsync(), por lo que puedes hacer una actualización para usar la nueva funcionalidad sin tener que actualizar de inmediato también el código de las suscripciones preexistentes.
También puedes controlar cuáles de estas ofertas están disponibles a través de estos métodos si las marcas como retrocompatibles.
Además de mantener los métodos heredados, la Biblioteca de Facturación Play 5 ahora incluye un nuevo objeto ProductDetails y un método queryProductDetailsAsync() correspondiente para manejar nuevas entidades y funcionalidades. Ahora, ProductDetails también admite productos integrados en la aplicación preexistentes (compras únicas y productos consumibles).
Para una suscripción, ProductDetails.getSubscriptionOfferDetails() muestra una lista de todos los planes básicos y las ofertas que el usuario es apto para comprar.
Esto significa que puedes acceder a todos los planes básicos y las ofertas aptos para el usuario, independientemente de la retrocompatibilidad.
getSubscriptionOfferDetails() muestra null para los productos sin suscripción. Para compras únicas, puedes usar getOneTimePurchaseOfferDetails().
La Biblioteca de Facturación Play 5 también incluye métodos nuevos y heredados para iniciar el flujo de compra. Si el objeto BillingFlowParams que se pasa a BillingClient.launchBillingFlow() se configura con un objeto SkuDetails, el sistema extrae la información de la oferta para vender a partir del plan básico o la oferta retrocompatible que corresponde al SKU. Si el objeto BillingFlowParams que se pasa a BillingClient.launchBillingFlow() se configura con objetos ProductDetailsParams, que incluyen ProductDetails y una String que represente el token de oferta específico de la oferta que se compra, el sistema usa esa información para identificar el producto que adquiere el usuario.
queryPurchasesAsync() muestra todas las compras que posee el usuario. Para indicar el tipo de producto solicitado, puedes pasar un valor BillingClient.SkuType, como en versiones anteriores, o un objeto QueryPurchasesParams que contenga un valor BillingClient.ProductType que represente las nuevas entidades de suscripción.
Te recomendamos que actualices las apps a la versión 5 de la biblioteca pronto para que puedas comenzar a aprovechar estas nuevas funciones de suscripción.
Cómo administrar el estado de la suscripción
En esta sección, se describen los cambios principales en los componentes de backend de una integración del sistema de Facturación Google Play que se deben implementar para la migración a la versión 5.
Notificaciones para desarrolladores en tiempo real
Próximamente, el objeto SubscriptionNotification ya no contendrá un subscriptionId. Si dependes de este campo para identificar el producto de suscripción, debes realizar la actualización para obtener esta información del estado de la suscripción con purchases.subscriptionv2:get una vez que recibas la notificación. Cada elemento SubscriptionPurchaseLineItem en la colección lineItems que se muestra como parte del estado de la compra incluirá el productId correspondiente.
API de Subscriptions Purchases: cómo obtener el estado de la suscripción
En versiones anteriores de la API de Subscriptions Purchases, podías consultar el estado de la suscripción mediante purchases.subscriptions:get.
Este extremo no cambió y continúa funcionando para compras de suscripciones retrocompatibles. Este extremo no admite ninguna funcionalidad nueva de mayo de 2022.
En la versión nueva de la API de Subscriptions Purchases, usa purchases.subscriptionsv2:get para obtener el estado de compra de la suscripción. Esta API es compatible con las suscripciones migradas, las suscripciones nuevas (tanto prepagadas como las de renovación automática) y las compras de todo tipo. Puedes usar este extremo para verificar el estado de la suscripción cuando recibas notificaciones. El objeto que se muestra, SubscriptionPurchaseV2, contiene campos nuevos, pero aún incluye datos heredados que se necesitan para seguir admitiendo las suscripciones existentes.
Campos de SubscriptionPurchaseV2 para planes prepagados
Se agregaron campos nuevos para admitir planes prepagados, que el usuario extiende en lugar de la renovación automática. Todos los campos se aplican a los planes prepagados y a las suscripciones de renovación automática, con las siguientes excepciones:
- [New field] lineItems[0].prepaid_plan.allowextendAfterTime: Indica cuándo un usuario podrá comprar otra recarga para extender su plan prepagado, ya que se permite que un usuario tenga solo una recarga no consumida a la vez.
- [New field] subscriptionState: Especifica el estado del objeto de suscripción.
Para los planes prepagados, este valor siempre es
ACTIVE,PENDINGoCANCELED. - lineItems[0].expirationTime: Este campo siempre está presente en los planes prepagados.
- paused_state_context: Este campo nunca está presente, ya que los planes prepagados no pueden pausarse.
- lineItems[0].auto_renewing_plan: No está presente en los planes prepagados.
- canceled_state_context: No está presente en los planes prepagados, ya que este campo solo se aplica a los usuarios que cancelan de forma activa una suscripción.
- lineItems[0].productId: Este campo reemplaza a
subscriptionIdde versiones anteriores.
Campos de SubscriptionPurchaseV2 para suscripciones recurrentes
purchases.subscriptionv2 contiene campos nuevos que proporcionan más detalles sobre los nuevos objetos de suscripción. En la siguiente tabla, se muestra la asignación de los campos del extremo de suscripción heredado a los campos correspondientes en purchases.subscriptionv2.
| SubscriptionPurchase | SubscriptionPurchaseV2 |
|---|---|
countryCode |
regionCode |
orderId |
latestOrderId |
| (sin campo equivalente) | lineItems (lista de SubscriptionPurchaseLineItem) que representa los productos adquiridos con la compra |
| (sin campo equivalente) | lineItems.offerDetails.basePlanId |
| (sin campo equivalente) | lineItems.offerDetails.offerId |
| (sin campo equivalente) | lineItems.offerDetails.offerTags |
startTimeMillis |
startTime |
expiryTimeMillis |
lineItems.expiryTime (cada suscripción adquirida en la compra tiene su propio expiryTime) |
| (sin campo equivalente) | subscriptionState (indica el estado de la suscripción) |
| (sin campo equivalente) | pausedStateContext (solo presente si el estado de la suscripción es SUBSCRIPTION_STATE_PAUSED) |
autoResumeTimeMillis |
pausedStateContext.autoResumeTime |
| (sin campo equivalente) | canceledStateContext (solo presente si el estado de la suscripción es SUBSCRIPTION_STATE_CANCELED) |
| (sin campo equivalente) | testPurchase (solo presente en compras de verificadores con licencia) |
autoRenewing |
lineItems.autoRenewingPlan.autoRenewEnabled |
priceCurrenceCode,
priceAmountMicros |
lineItems.autoRenewingPlan.recurringPrice |
introductoryPriceInfo |
(sin campo equivalente) Esta información se puede encontrar en offer de cada una de las suscripciones compradas. |
| developerPayload | (sin campo equivalente) la carga útil para desarrolladores dejó de estar disponible |
| paymentState | (sin campo equivalente) Puedes deducir el estado de pago a partir de subscriptionState:
|
cancelReason,
userCancellationTimeMillis,
cancelSurveyResult |
canceledStateContext |
linkedPurchaseToken |
linkedPurchaseToken (sin cambios) |
purchaseType |
Prueba: a través de testPurchasePromoción: signupPromotion |
priceChange |
lineItems.autoRenewingPlan.priceChangeDetails |
profileName,
emailAddress,
givenName,
familyName,
profileId |
subscribeWithGoogleInfo |
acknowledgementState |
acknowledgementState (no change) |
promotionType,
promotionCode |
signupPromotion |
externalAccountId,
obfuscatedExternalAccountId,
obfuscatedExteranlProfileId |
externalAccountIdentifiers |
Otras funciones de administración de suscripciones
Aunque purchases.subscriptions:get se actualizó a purchases.subscriptionsv2:get, el resto de las funciones de administración de suscripciones de desarrollador permanecerán sin cambios por ahora en el extremo purchases.subscriptions, de manera que puedes seguir usando purchases.subscriptions:acknowledge, purchases.subscriptions:cancel, purchases.subscriptions:defer, purchases.subscriptions:refund y purchases.subscriptions:revoke como lo hacías antes.
API de Pricing
Usa el extremo monetization.convertRegionPrices para calcular los precios regionales como lo harías a través de Play Console. Este método acepta un solo precio en cualquier moneda compatible con Play y muestra los precios convertidos (incluida la tasa de impuestos predeterminada cuando corresponda) para todas las regiones donde Google Play admite compras.