Guía completa para actualizar e implementar Google Play Billing Library v7

Si trabajas con compras integradas en Android, tarde o temprano te toca pelearte con la Google Play Billing Library v7. No es solo una actualización más: viene con cambios de API, nuevas funciones de suscripción, requisitos de consola y fechas límite muy claras por parte de Google. Ignorarla ya no es una opción si quieres seguir publicando o actualizando tu app sin sustos en Google Play.

A lo largo de este artículo vas a ver cómo actualizar e implementar la Google Play Billing Library v7 paso a paso: desde qué cambia respecto a PBL 5 y 6, hasta cómo integrar suscripciones, compras únicas, RTDN, pruebas con Play Billing Lab y cómo sobrevivir si estás en ecosistemas como .NET MAUI donde el soporte oficial va por detrás. La idea es que, cuando termines de leer, puedas preparar tu migración con bastante tranquilidad y sin dejar dinero encima de la mesa.

Visión general de Google Play Billing Library v7

La Biblioteca de Facturación Google Play 7 introduce mejoras importantes en cómo se gestionan los pagos, suscripciones y planes especiales, pero está diseñada para que la migración sea relativamente suave. La buena noticia es que muchas de las nuevas APIs son opcionales: puedes actualizar la dependencia, ajustar unas cuantas referencias y tu integración básica seguirá funcionando.

Esta versión pone el foco en tres frentes clave: nuevas modalidades de suscripción (como las cuotas virtuales), mejor soporte para compras pendientes en planes prepagados, y cambios de API que limpian lo que ya estaba obsoleto en versiones anteriores (PBL 5 y 6). Además, Google ajusta parte del manejo de errores y la forma en que debes tratar las transacciones pendientes para evitar inconsistencias.

Para empezar, en tu módulo de app necesitas actualizar la dependencia en tu archivo build.gradle:

dependencies {
    def billingVersion = "7.0.0"
    implementation "com.android.billingclient:billing:$billingVersion"
}

Una vez hecho esto, toca revisar el código que usa APIs antiguas. Muchas llamadas relacionadas con prorrateo de suscripciones y facturación alternativa se han renombrado o eliminado, así que conviene pasar un buen ojo a todas las referencias a BillingClient y BillingFlowParams antes de compilar y subir nada a la Play Console.

Estrategias de monetización con compras únicas y suscripciones

Cuando vendes productos digitales dentro de tu app, no basta con pegar el diálogo de compra y listo: es clave diseñar una experiencia de usuario fluida durante todo el ciclo de compra, tanto para productos únicos (consumibles o no consumibles) como para suscripciones. Cuanto más natural y sin fricciones sea el proceso, más suben las conversiones y más baja la tasa de cancelaciones.

Un flujo típico de compra con Play Billing, ya sea suscripción o artículo único, suele seguir estas etapas bien diferenciadas que tu backend también debe conocer:

El usuario explora los productos disponibles y selecciona uno.
La app inicia el flujo de facturación de Google Play para completar el pago.
Se completa la compra y tu app recibe el resultado.
Tu servidor valida la compra contra la API de Google Play Developer.
Se otorga el contenido o derecho correspondiente al usuario en tu sistema.
Se confirma a Google que la compra se ha procesado (consumir o reconocer).

En el caso de los productos consumibles, es vital que consumas el token en el momento adecuado para permitir recompras sin problemas y ayudar a bloquear compras accidentales en Google Play. En suscripciones, debes controlar renovaciones, periodos de gracia, suspensiones y cancelaciones para que el usuario reciba exactamente lo que ha pagado y ni un día menos.

La integración en la app es solo la mitad del trabajo: tu servidor debe mantener un registro fiable de derechos y estados de compra, especialmente si ofreces acceso multiplataforma o si necesitas estadísticas finas de ingresos, retención y abandono. Aquí entran en juego las notificaciones para desarrolladores en tiempo real (RTDN), que actúan como la “caja negra” del ciclo de vida de la compra.

Con RTDN puedes reaccionar en casi tiempo real a eventos críticos: una nueva compra, un fallo de renovación, una suscripción que entra en periodo de gracia, o una compra anulada. Esto permite montar estrategias de recuperación de suscriptores y prevención de fraude, como envíos de email automáticos cuando un pago falla o ajustes de derechos si el cliente no recibe el mensaje por problemas de red.

Notificaciones para desarrolladores en tiempo real (RTDN) y Google Cloud Pub/Sub

Las RTDN utilizan Google Cloud Pub/Sub como sistema de mensajería en tiempo real entre Google Play y tu backend. Google Play publica eventos sobre un tema (topic) de Pub/Sub, y tú te suscribes a ese tema para recibir mensajes cada vez que cambia el estado de una compra o suscripción.

El flujo básico es sencillo: Google Play envía un mensaje codificado en base64 al tema de Pub/Sub, tu suscriptor lo extrae, lo decodifica y procesa la notificación. Dentro del campo data del mensaje encontrarás un JSON con el objeto DeveloperNotification, que incluye información como la versión del mensaje, el nombre del paquete, el momento del evento y datos específicos de compras únicas, suscripciones, compras anuladas o pruebas.

{
  "version": string,
  "packageName": string,
  "eventTimeMillis": long,
  "oneTimeProductNotification": OneTimeProductNotification,
  "subscriptionNotification": SubscriptionNotification,
  "voidedPurchaseNotification": VoidedPurchaseNotification,
  "testNotification": TestNotification
}

Gracias a estos mensajes puedes mantener sincronizado tu backend incluso si el dispositivo del usuario falla. Imagina que el usuario compra con éxito, Google Play confirma, pero el móvil pierde la conexión antes de que tu app reciba el callback de la Billing Library. Sin RTDN, podrías no enterarte nunca. Con Pub/Sub, tu servidor recibe una notificación independiente y puede otorgar el derecho sin depender del cliente.

Configuración de Cloud Pub/Sub para RTDN

Antes de activar RTDN en la consola de Google Play, tienes que preparar un proyecto en Google Cloud Platform (GCP) y configurar allí Pub/Sub. El proceso es relativamente directo, pero conviene seguirlo al detalle para no tener sustos con permisos o nombres de recursos.

Creación del tema (topic)

Primero debes crear un tema de Pub/Sub que actuará como punto de publicación de Google Play. Desde la consola de Google Cloud, selecciona tu proyecto, ve a la sección de Pub/Sub y crea un nuevo topic siguiendo la guía oficial de “crear tema”. El resultado tendrá un nombre con formato:

projects/{project_id}/topics/{topic_name}

Ese nombre completo es el que luego tendrás que pegar en la Play Console cuando actives las notificaciones.

Creación de la suscripción

Para poder leer los mensajes del tema, necesitas una suscripción Pub/Sub. Puedes configurarla como push o como pull. En el codelab de referencia se trabaja con suscripción de extracción (pull), donde es tu backend el que inicia las peticiones para recuperar mensajes.

Debes revisar las opciones en la guía de suscriptores de Cloud Pub/Sub para decidir si te encaja mejor push o pull según tu arquitectura. Una vez decidido, sigues la documentación de “agregar suscripción” y la enlazas al tema creado antes. A partir de ese momento, cualquier mensaje que Google Play publique en el tema quedará accesible para tu suscriptor.

Permisos para que Google Play publique en tu tema

Pub/Sub no permitirá que Google Play publique nada si no le das permisos explícitos a su cuenta de servicio. En la consola de Google Cloud tienes que ir a la configuración de permisos del topic y añadir el principal:

google-play-developer-notifications@system.gserviceaccount.com

Concede a esta cuenta el rol de publicador de Pub/Sub (Publisher). Guarda los cambios y, desde ese momento, Google Play podrá enviar RTDN a tu tema sin problemas de autorización.

Activar RTDN en Google Play Console

Una vez configurado Pub/Sub, toca decirle a Play Console dónde enviar las notificaciones. Dentro de tu app en Google Play Console, ve a Monetiza con Play > Configuración de la monetización y localiza la sección de notificaciones para desarrolladores en tiempo real.

Ahí deberás:

Marcar la casilla para habilitar las notificaciones en tiempo real.
Introducir el nombre completo del topic de Pub/Sub en el campo correspondiente, respetando el formato projects/{project_id}/topics/{topic_name}.
Enviar un mensaje de prueba usando el botón de test.

El mensaje de prueba es fundamental para comprobar que la integración está bien montada. Si tienes una suscripción de tipo pull, podrás ir a la consola de Cloud, seleccionar la suscripción, hacer clic en “Ver mensajes” y extraer el mensaje de prueba. No olvides hacer ack de cualquier mensaje que leas para evitar recepciones repetidas.

En suscripciones push, revisa que tu endpoint reciba el mensaje y responda con un código HTTP correcto. Si algo falla, la consola te mostrará un error al publicar la prueba, normalmente relacionado con el nombre del tema o los permisos de la cuenta de servicio.

suscribirse a pruebas de aplicaciones en Google Play Store

Construir un suscriptor de Pub/Sub en tu backend

Con el tema y la suscripción listos, toca implementar un suscriptor que lea y procese los RTDN. Google proporciona ejemplos en varios lenguajes; un caso típico en Java utiliza las bibliotecas cliente de Cloud Pub/Sub para arrancar un Subscriber que escucha mensajes y llama a un MessageReceiver.

El patrón general es siempre el mismo: recuperas el mensaje, decodificas el campo data de base64 a texto, parseas el JSON, extraes los campos relevantes (como packageName, oneTimeProductNotification o subscriptionNotification) y decides qué hacer en tu sistema. Tras procesar correctamente la notificación, debes confirmar el mensaje con un ack para que Pub/Sub no lo vuelva a enviar.

En el código de ejemplo se ve cómo el receptor imprime la versión y el nombre del paquete, pero en una implementación real irías más allá: validarías la compra, otorgarías el derecho al usuario correcto, actualizarías tu base de datos y, si procede, llamarías a la API de Play Developer para consumir o reconocer la compra.

Vincular las notificaciones con el usuario: uso de obfuscatedAccountId

Un problema clásico cuando gestionas compras desde el servidor es saber a qué usuario corresponde una notificación RTDN concreta. Para eso, la API de Billing Client permite adjuntar un identificador ofuscado de cuenta cuando lanzas el flujo de compra: obfuscatedAccountId.

La idea es que uses un identificador estable de tu sistema (por ejemplo, el ID interno del usuario) pero ofuscado por motivos de privacidad y seguridad. Este valor se asocia a la compra y luego aparece en la información que se devuelve desde la API de Google Play Developer, de modo que, cuando recibas la RTDN y verifiques el token, podrás saber de manera inequívoca a qué cuenta de tu base de datos debes conceder el derecho.

En el lado cliente, al preparar el BillingFlowParams, solo tienes que construir la lista de ProductDetailsParams y llamar a setObfuscatedAccountId(obfuscatedAccountId) antes de lanzar el flujo. Eso no cambia la experiencia visible para el usuario, pero te simplifica muchísimo la lógica de asignación de compras en el backend y ayuda a Google en la detección de fraude.

Verificar las compras con la API de Google Play Developer

Antes de otorgar cualquier derecho en tu servidor, es obligatorio verificar que la compra es legítima llamando a la API de Google Play Developer. No basta con fiarse de lo que diga el cliente o incluso la RTDN: debes validar el purchaseToken directamente contra los endpoints oficiales, y en caso necesario gestionar reembolsos.

En el caso de productos únicos, utilizarás el endpoint purchases.products:get. Para suscripciones, el camino pasa por purchases.subscriptionsv2:get. El flujo recomendado es:

Extraer el purchaseToken del mensaje de Pub/Sub.
Comprobar en tu base de datos si ya lo has procesado; cada token es globalmente único, así que es perfecto como clave primaria para evitar duplicados.
Si es nuevo, llamar a la API de Google Play Developer con el paquete, el SKU y el purchaseToken.
Verificar que la respuesta indica un estado de compra PURCHASED (no PENDING ni cancelado).
Si todo cuadra, registrar el token y otorgar el derecho correspondiente al usuario asociado.

Para hablar con la API de Play Developer desde Java puedes usar AndroidPublisher, inicializado con credenciales de cuenta de servicio en formato JSON. Configuras el alcance AndroidPublisherScopes.ANDROIDPUBLISHER, construyes el cliente y llamas al método purchases().products().get(...). Si la llamada falla por un problema transitorio de red o de servicio, es recomendable implementar reintentos con backoff exponencial para no perder el evento.

Confirmar o consumir la compra desde el servidor

Cuando ya has verificado la compra y has concedido el derecho en tu sistema, el siguiente paso es comunicar a Google que has procesado correctamente la transacción. Para ello tienes dos opciones en el caso de productos únicos: consumir la compra o simplemente reconocerla.

Los productos consumibles (por ejemplo monedas virtuales, vidas, etc.) deben pasar por el endpoint purchases.products:consume. Esto marca el token como usado y permite que el usuario vuelva a comprar el mismo artículo sin conflicto. Para productos no consumibles (como desbloquear la versión premium de por vida), debes llamar a purchases.products:acknowledge, que informa a Google de que el usuario ya tiene el derecho asociado.

En suscripciones se utiliza purchases.subscriptions:acknowledge, indicando que la suscripción ha sido correctamente procesada y asignada al usuario. Si no reconoces una compra en un plazo razonable, Google puede entender que hay un problema y acabar revirtiendo la transacción, así que es importante que el ack se haga justo después de otorgar el derecho.

En tu helper de AndroidPublisher puedes añadir métodos como executeProductPurchasesConsume y executeProductPurchasesAcknowledge que llamen a los endpoints correspondientes. De nuevo conviene implementar reintentos en caso de fallos puntuales, para asegurarte de que ningún token queda en un estado intermedio peligroso.

Pruebas avanzadas con Play Billing Lab

Una parte que muchos desarrolladores subestiman es la fase de pruebas. Para lanzar con cierta seguridad, necesitas poder simular errores de red, respuestas no estándar y casos extremos. Ahí entra Play Billing Lab, una app gratuita en Google Play pensada específicamente para probar integraciones de la Play Billing Library.

Play Billing Lab incluye un simulador de respuestas que permite forzar distintos BillingResponseCode en las llamadas de tu app a la Biblioteca de Facturación. De esta forma, puedes recrear escenarios donde, por ejemplo, el cliente no consigue consumir la compra por un problema de red, pero tu backend sí procesa la RTDN correctamente y acaba concediendo el derecho sin intervención del usuario.

Para que tu app pueda comunicarse con el simulador, tienes que habilitar las pruebas de “billing overrides” usando metadatos en el AndroidManifest.xml:

<manifest ... >
  <application ... >
    ...
    <meta-data
        android:name="com.google.android.play.largest_release_audience.NONPRODUCTION"
        android:value="" />
    <meta-data
        android:name="com.google.android.play.billingclient.enableBillingOverridesTesting"
        android:value="true" />
  </application>
</manifest>

La etiqueta enableBillingOverridesTesting activa las pruebas de respuestas simuladas de la Billing Library. La etiqueta NONPRODUCTION es una especie de salvavidas para recordar que esa build no debe ir a producción con los overrides activos. Cuando prepares la versión final para los usuarios, asegúrate de eliminar estos metadatos o usar un manifest separado.

Una vez configurado, desde la app Play Billing Lab inicias sesión con una cuenta de tester de licencias, activas la opción “Simulate Play Billing Library response” y seleccionas qué códigos de error quieres devolver para cada API (por ejemplo, un error concreto en consumeAsync). Luego simplemente abres tu app y ejecutas el flujo que quieres probar: el simulador devolverá las respuestas configuradas y podrás verificar que tu lógica de reintentos, manejo de errores y RTDN se comporta como esperas.

Cambios clave de API al migrar a Play Billing Library 7

Más allá de RTDN y las pruebas, la migración a PBL 7 implica tocar algunos puntos concretos de API. Para quienes venís de PBL 5 o 6, conviene repasar los cambios más relevantes para que el proyecto compile sin sorpresas y la lógica de negocio siga cuadrando.

En primer lugar, las APIs relacionadas con ProrationMode para cambios de suscripción han sido retiradas. Ahora se utiliza ReplacementMode para gestionar cambios de plan (upgrades, downgrades, etc.). Si todavía usas métodos como setReplaceProrationMode o setReplaceSkusProrationMode, tendrás que migrarlos a las nuevas variantes de setSubscriptionReplacementMode y ajustar la lógica según la documentación actualizada.

También se ha eliminado la API launchPriceConfirmationFlow, que ya estaba previamente marcada como obsoleta. Para manejar cambios de precio de suscripción deberás apoyarte en los nuevos flujos y recomendaciones de la guía de cambios de precios, donde se detalla cómo informar correctamente al usuario y cómo se gestionan los consentimientos.

Otro punto importante son las APIs de facturación alternativa. Los métodos BillingClient.Builder.enableAlternativeBilling, AlternativeBillingListener y AlternativeChoiceDetails han desaparecido en favor de una nomenclatura más alineada: ahora debes usar BillingClient.Builder.enableUserChoiceBilling() junto a UserChoiceBillingListener y UserChoiceDetails. Según la propia Google, se trata básicamente de un cambio de nombre sin variaciones de comportamiento, en un contexto marcado por acuerdos como Google y Epic Games pactan abrir Android.

Por último, se introduce un nuevo código de error NETWORK_ERROR en BillingResult, y se ajustan los significados y condiciones de SERVICE_TIMEOUT y SERVICE_UNAVAILABLE. Si tienes lógica personalizada de manejo de errores (por ejemplo, decidir cuándo mostrar un mensaje al usuario, cuándo reintentar en silencio, etc.), es recomendable revisarla para tener en cuenta estos nuevos matices.

Transacciones pendientes y ausencia de orderId hasta PURCHASED

Un cambio delicado en PBL 7 es que la biblioteca ya no genera un ID de pedido para compras pendientes. En estos casos, el orderId solo estará disponible cuando la compra pase al estado PURCHASED. Esto afecta especialmente a los flujos donde usabas el ID de pedido como referencia primaria desde el primer momento.

La recomendación de Google es que te apoyes en el purchaseToken para tus registros y conciliaciones, al menos mientras la transacción esté en estado pendiente. Si encuentras una compra que ha desaparecido de Play, consulta qué hacer si la compra desaparece.

Si no has trabajado aún con pendientes, revisa la guía de integración de la Billing Library y la documentación sobre gestión del ciclo de vida de las compras. Ahí encontrarás los distintos estados, cómo reaccionar a cada uno y cómo encajan las RTDN en este rompecabezas.

Nuevas capacidades opcionales en PBL 7: cuotas virtuales y prepagos

Entre las novedades “bonitas” de PBL 7 están las suscripciones de cuotas virtuales (virtual installment subscriptions) y el soporte extendido de compras pendientes para suscripciones prepagadas. Estas funciones no son obligatorias, pero pueden darte más juego a la hora de adaptar tu modelo de negocio a distintos mercados.

Las cuotas virtuales permiten que un usuario pague una suscripción de mayor duración en pequeñas cuotas periódicas, en lugar de un pago único grande. A efectos de cobro para el desarrollador, Google indica que sigues recibiendo pagos mensuales en un plan anual con cuotas mensuales, y que si el usuario deja de pagar una cuota, ni Google ni tú debéis intentar recuperar cuotas pasadas. Esto hace que, en la práctica, su utilidad sea bastante parecida a una suscripción mensual normal, al menos en su fase inicial.

De momento, estas suscripciones de cuotas solo están disponibles en Brasil, Francia, Italia y España, y Google recomienda vigilar la Play Console para ver nuevos países soportados. La configuración se hace mediante ProductDetails.InstallmentPlanDetails y siguiendo la guía específica para integrarlas en tu app.

En paralelo, se amplía el soporte de compras pendientes para suscripciones prepagadas. Ahora puedes ofrecer modelos donde el usuario inicia la compra en la app y completa el pago posteriormente por otros medios, y la Billing Library sabe manejar ese flujo correctamente. La activación se realiza llamando a enablePendingPurchases() al inicializar BillingClient y, para el caso específico de planes prepagados, usando PendingPurchasesParams.Builder.enablePrepaidPlans().

Plazos de deprecación de Play Billing Library 5 y 6

Con PBL 7 en escena, Google ha puesto fechas claras para la retirada de soporte de las versiones 5 y 6. Si sigues en alguna de ellas, tienes que marcar en rojo el calendario:

Google Play Billing Library 5 se depreca oficialmente el 31 de agosto de 2024 para nuevas apps y actualizaciones. Existe la posibilidad de solicitar una extensión hasta el 1 de noviembre de 2024, pero no es algo en lo que debas confiar a largo plazo.
Google Play Billing Library 6 podrá usarse para publicar nuevas apps hasta el 1 de agosto de 2025, y para actualizar apps existentes hasta el 1 de noviembre de 2025.

Pasada esa fecha, si no has migrado al menos a la versión 6 o idealmente a la versión 7, tendrás bloqueadas las actualizaciones en la Play Console. Aunque tu app seguirá funcionando en los dispositivos de los usuarios, vas a quedar congelado sin poder corregir bugs ni añadir nuevas funciones que dependan de publicación en la tienda.

El caso de .NET MAUI y las limitaciones actuales

Si estás trabajando con .NET MAUI y suscripciones en Android, probablemente ya habrás leído o sufrido que la cosa no está tan sencilla. Muchos proyectos usaban Plugin.InAppBilling de James Montemagno, pero el plugin está archivado y sin mantenimiento, así que no se va a actualizar para soportar Billing Library 7. Al mismo tiempo, el paquete oficial Xamarin.Android.Google.BillingClient se ha quedado anclado al ecosistema Xamarin.Android y no es compatible de forma directa con .NET MAUI.

La consecuencia práctica es que la Play Console avisa de que tu app no utiliza Billing Library 7.0.0 o superior, lo que bloquea actualizaciones si sigues tirando de librerías antiguas. Algunos desarrolladores han optado por soluciones drásticas, como eliminar temporalmente las suscripciones para poder subir una versión, pero obviamente eso no es sostenible si tu modelo de negocio depende de esa monetización.

En este contexto, muchos equipos están valorando alternativas como SDKs de terceros que ya soportan PBL 7 por debajo y exponen una API más estable y multiplataforma (por ejemplo, soluciones de backend de suscripciones con SDK para Android, iOS y otras plataformas). Estos servicios suelen encargarse de las migraciones de versión de Billing Library y exponen un wrapper estable, lo que reduce bastante el estrés con cada nueva deprecación de Google.

Mientras Microsoft y el equipo de MAUI no ofrezcan un paquete oficial actualizado y plenamente compatible con Billing Library 7, las opciones pasan por: implementar tu propio binding a la Billing Library nativa, usar un servicio de terceros o replantear la forma en que integras las compras dentro del proyecto MAUI. En cualquier caso, conviene no dejar la decisión para el último momento, porque las fechas límite de Play no se mueven.