Si treballes amb compres integrades a Android, tard o d'hora et toca barallar-te amb la Google Play Billing Library v7. No és només una actualització més: ve amb canvis d'API, noves funcions de subscripció, requisits de consola i dates límit molt clares per part de Google. Ignorar-la ja no és una opció si vols continuar publicant o actualitzant la teva app sense ensurts a Google Play.
Al llarg d'aquest article veureu com actualitzar i implementar la Google Play Billing Library v7 pas a pas: des de què canvia respecte a PBL 5 i 6, fins a com integrar subscripcions, compres úniques, RTDN, proves amb Play Billing Lab i com sobreviure si estàs en ecosistemes com .NET MAUI on el suport oficial va darrere. La idea és que, quan acabis de llegir, puguis preparar la teva migració amb força tranquil·litat i sense deixar diners sobre la taula.
Visió general de Google Play Billing Library v7
La Biblioteca de Facturació Google Play 7 introdueix millores importants en com es gestionen els pagaments, subscripcions i plans especials, però està dissenyada perquè la migració sigui relativament suau. La bona notícia és que moltes de les noves API són opcionals: pots actualitzar la dependència, ajustar unes quantes referències i la teva integració bàsica continuarà funcionant.
Aquesta versió posa el focus en tres fronts clau: noves modalitats de subscripció (com les quotes virtuals), millor suport per compres pendents en plans prepagats, i canvis d'API que netegen el que ja estava obsolet en versions anteriors (PBL 5 i 6). A més, Google ajusta part del maneig derrors i la manera com has de tractar les transaccions pendents per evitar inconsistències.
Per començar, al teu mòdul d'app necessites actualitzar la dependència al teu fitxer construir.gradle:
dependencies {
def billingVersion = "7.0.0"
implementation "com.android.billingclient:billing:$billingVersion"
}
Un cop fet això, toca revisar el codi que utilitza APIs antigues. Moltes trucades relacionades amb prorrateig de subscripcions i facturació alternativa s'han reanomenat o eliminat, així que convé passar un bon ull a totes les referències a BillingClient i BillingFlowParams abans de compilar i pujar res a la Play Console.
Estratègies de monetització amb compres úniques i subscripcions
Quan vens productes digitals dins de la teva app, no n'hi ha prou amb enganxar el diàleg de compra i llest: és clau dissenyar-ne una experiència d'usuari fluida durant tot el cicle de compra, tant per a productes únics (consumibles o no consumibles) com per a subscripcions. Com més natural i sense friccions sigui el procés, més pugen les conversions i més baixa la taxa de cancel·lacions.
Un flux típic de compra amb Play Billing, ja sigui subscripció o article únic, sol seguir aquestes etapes ben diferenciades que el teu backend també ha de conèixer:
- L'usuari explora els productes disponibles i en selecciona un.
- L'app inicia el flux de facturació de Google Play per completar el pagament.
- Es completa la compra i la teva app rep el resultat.
- El vostre servidor valida la compra contra l'API de Google Play Developer.
- S'atorga el contingut o dret corresponent a l'usuari al vostre sistema.
- Es confirma a Google que la compra s'ha processat (consumir o reconèixer).
En el cas dels productes consumibles, és vital que consumeixis el token en el moment adequat per permetre recompres sense problemes i ajudar a bloquejar compres accidentals a Google Play. En subscripcions, heu de controlar renovacions, períodes de gràcia, suspensions i cancel·lacions perquè l'usuari rebi exactament el que ha pagat i ni un dia menys.
La integració a l'app és només la meitat de la feina: el teu servidor ha de mantenir un registre fiable de drets i estats de compra, especialment si ofereixes accés multiplataforma o si necessites estadístiques fines dingressos, retenció i abandonament. Aquí entren en joc les notificacions per a desenvolupadors en temps real (RTDN), que actuen com la “caixa negra” del cicle de vida de la compra.
Amb RTDN pots reaccionar en gairebé temps real a esdeveniments crítics: una nova compra, una fallada de renovació, una subscripció que entra en període de gràcia, o una compra anul·lada. Això permet muntar estratègies de recuperació de subscriptors i prevenció de frau, com enviaments de correu electrònic automàtics quan un pagament falla o ajustaments de drets si el client no rep el missatge per problemes de xarxa.
Notificacions per a desenvolupadors en temps real (RTDN) i Google Cloud Pub/Sub
Les RTDN utilitzen Google Cloud Pub/Sub com a sistema de missatgeria en temps real entre Google Play i el teu backend. Google Play publica esdeveniments sobre un tema (topic) de Pub/Sub, i tu us subscriviu a aquest tema per rebre missatges cada vegada que canvieu l'estat d'una compra o subscripció.
El flux bàsic és senzill: Google Play envia un missatge codificat a base64 al tema de Pub/Sub, el teu subscriptor l'extreu, el descodifica i processa la notificació. Dins el camp data del missatge trobareu un JSON amb l'objecte DeveloperNotification, que inclou informació com la versió del missatge, el nom del paquet, el moment de l'esdeveniment i dades específiques de compres úniques, subscripcions, compres anul·lades o proves.
{
"version": string,
"packageName": string,
"eventTimeMillis": long,
"oneTimeProductNotification": OneTimeProductNotification,
"subscriptionNotification": SubscriptionNotification,
"voidedPurchaseNotification": VoidedPurchaseNotification,
"testNotification": TestNotification
}
Gràcies a aquests missatges pots mantenir sincronitzat el vostre backend fins i tot si el dispositiu de l'usuari falla. Imagina't que l'usuari compra amb èxit, Google Play confirma, però el mòbil perd la connexió abans que la teva app rebi el callback de la Billing Library. Sense RTDN, podries no assabentar-te mai. Amb Pub/Sub, el vostre servidor rep una notificació independent i pot atorgar el dret sense dependre del client.
Configuració de Cloud Pub/Sub per a RTDN
Abans d'activar RTDN a la consola de Google Play, heu de preparar un projecte a Google Cloud Platform (GCP) i configurar-hi Pub/Sub. El procés és relativament directe, però cal seguir-lo al detall per no tenir ensurts amb permisos o noms de recursos.
Creació del tema (topic)
Primer has de crear un tema de Pub/Sub que actuarà com a punt de publicació de Google Play. Des de la consola de Google Cloud, selecciona el teu projecte, vés a la secció de Pub/Sub i crea un nou topic seguint la guia oficial de “crear tema”. El resultat tindrà un nom amb format:
projects/{project_id}/topics/{topic_name}
Aquest nom complet és el que després haureu d'enganxar a la Play Console quan activeu les notificacions.
Creació de la subscripció
Per poder llegir els missatges del tema, necessites una subscripció Pub/Sub. Pots configurar-la com empenta o com tirar. Al codelab de referència es treballa amb subscripció d'extracció (pull), on és el teu backend el que inicia les peticions per recuperar missatges.
Has de revisar les opcions a la guia de subscriptors de Cloud Pub/Sub per decidir si t'encaixa millor push o pull segons la teva arquitectura. Un cop decidit, segueixes la documentació d'“afegir subscripció” i l'enllaçes al tema creat abans. A partir d'aquest moment, qualsevol missatge que Google Play publiqui al tema quedarà accessible per al vostre subscriptor.
Permisos perquè Google Play publiqui al teu tema
Pub/Sub no permetrà que Google Play publiqui res si no dónes permisos explícits al seu compte de servei. A la consola de Google Cloud has d'anar a la configuració de permisos del topic i afegir-ne el principal:
google-play-developer-notifications@system.gserviceaccount.com
Concedeix a aquest compte el rol de publicador de Pub/Sub (Publisher). Desa els canvis i, des d'aleshores, Google Play podrà enviar RTDN al tema sense problemes d'autorització.
Activar RTDN a Google Play Console
Un cop configurat Pub/Sub, toca dir-li a Play Console on enviar les notificacions. Dins la teva app a Google Play Console, vés a Monetitza amb Play > Configuració de la monetització i localitza la secció de notificacions per a desenvolupadors en temps real.
Aquí hauràs:
- Marqueu la casella per habilitar les notificacions en temps real.
- Introduir el nom complet del topic de Pub/Sub al camp corresponent, respectant el format
projects/{project_id}/topics/{topic_name}. - Enviar un missatge de prova usant el botó de test.
El missatge de prova és fonamental per comprovar que la integració està ben muntada. Si tens una subscripció de tipus pull, podràs anar a la consola de Cloud, seleccionar la subscripció, fer clic a “Veure missatges” i extreure'n el missatge de prova. No oblidis fer ACK de qualsevol missatge que llegeixis per evitar recepcions repetides.
En subscripcions push, revisa que el teu endpoint rebi el missatge i respongui amb un codi HTTP correcte. Si alguna cosa falla, la consola us mostrarà un error en publicar la prova, normalment relacionat amb el nom del tema o els permisos del compte de servei.
Finalment, pots configurar quins tipus de notificacions vols rebre: només subscripcions i compres anul·lades, o bé totes les notificacions incloent compres úniques (esdeveniments com ONE_TIME_PRODUCT_PURCHASED i ONE_TIME_PRODUCT_CANCELED). El més habitual, si utilitzes també productes únics, és activar el conjunt complet per no perdre visibilitat sobre res.
Construir un subscriptor de Pub/Sub al teu backend
Amb el tema i la subscripció llestos, toca implementar un subscriptor que llegiu i processeu els RTDN. Google proporciona exemples en diversos llenguatges; un cas típic a Java utilitza les biblioteques client de Cloud Pub/Sub per arrencar un Subscriber que escolta missatges i truca a un MessageReceiver.
El patró general és sempre el mateix: recuperes el missatge, descodifiques el camp data de base64 a text, parseges el JSON, extreu els camps rellevants (com packageName, oneTimeProductNotification o subscriptionNotification) i decideixes què fer al teu sistema. Després de processar correctament la notificació, has de confirmar el missatge amb un ack perquè Pub/Sub no el torneu a enviar.
Al codi d'exemple es veu com el receptor imprimeix la versió i el nom del paquet, però en una implementació real aniries més enllà: validaries la compra, atorgaries el dret a l'usuari correcte, actualitzaries la teva base de dades i, si escau, trucaries a l'API de Play Developer per consumir o reconèixer la compra.
Vincular les notificacions amb l'usuari: ús d'obfuscatedAccountId
Un problema clàssic quan gestiones compres des del servidor és saber a quin usuari correspon una notificació RTDN concreta. Per això, l'API de Billing Client permet adjuntar un identificador ofuscat de compte quan llances el flux de compra: obfuscatedAccountId.
La idea és que facis servir un identificador estable del teu sistema (per exemple, l'ID intern de l'usuari) però ofuscat per motius de privadesa i seguretat. Aquest valor s'associa a la compra i després apareix a la informació que es torna des de l'API de Google Play Developer, de manera que, quan rebis la RTDN i verifiquis el token, podràs saber de manera inequívoca a quin compte de la teva base de dades has de concedir el dret.
Al costat client, en preparar el BillingFlowParams, només has de construir la llista de ProductDetailsParams i cridar a setObfuscatedAccountId(obfuscatedAccountId) abans de llançar el flux. Això no canvia l'experiència visible per a l'usuari, però et simplifica molt la lògica d'assignació de compres al backend i ajuda Google a la detecció de frau.
Verificar les compres amb l'API de Google Play Developer
Abans d'atorgar qualsevol dret al vostre servidor, és obligatori verificar que la compra és legítima trucant a la API de Google Play Developer. No n'hi ha prou de refiar-se del que digui el client o fins i tot la RTDN: has de validar el purchaseToken directament contra els endpoints oficials, i en cas necessari gestionar reemborsament.
En el cas de productes únics, utilitzaràs l'endpoint purchases.products:get. Per subscripcions, el camí passa per purchases.subscriptionsv2:get. El flux recomanat és:
- extreure el
purchaseTokendel missatge de Pub/Sub. - Comprovar a la teva base de dades si ja ho has processat; cada token és globalment únic, així que és perfecte com a clau primària per evitar duplicats.
- Si és nou, trucar a l'API de Google Play Developer amb el paquet, l'SKU i el
purchaseToken. - Verificar que la resposta indica un estat de compra COMPRAT (no PENDING ni cancel·lat).
- Si tot quadra, registrar el token i atorgar el dret corresponent a lusuari associat.
Per parlar amb l'API de Play Developer des de Java pots fer servir AndroidPublisher, inicialitzat amb credencials de compte de servei en format JSON. Configures l'abast AndroidPublisherScopes.ANDROIDPUBLISHER, construeixes el client i truques al mètode purchases().products().get(...). Si la trucada falla per un problema transitori de xarxa o de servei, és recomanable implementar reintents amb backoff exponencial per no perdre lesdeveniment.
Confirmar o consumir la compra des del servidor
Quan ja has verificat la compra i has concedit el dret al sistema, el següent pas és comunicar a Google que has processat correctament la transacció. Per això tens dues opcions en el cas de productes únics: consumir la compra o simplement reconèixer-la.
Els productes consumibles (per exemple, monedes virtuals, vides, etc.) han de passar per l'endpoint purchases.products:consume. Això marca el token com a usat i permet que lusuari torni a comprar el mateix article sense conflicte. Per a productes no consumibles (com desbloquejar la versió premium de per vida), has de trucar a purchases.products:acknowledge, que informa Google que l'usuari ja té el dret associat.
En subscripcions s'utilitza purchases.subscriptions:acknowledge, indicant que la subscripció ha estat correctament processada i assignada a l'usuari. Si no reconeixes una compra en un termini raonable, Google pot entendre que hi ha un problema i acabar revertint la transacció, així que és important que el ack es faci just després d'atorgar el dret.
Al teu helper d'AndroidPublisher pots afegir mètodes com executeProductPurchasesConsume y executeProductPurchasesAcknowledge que truquin als endpoints corresponents. Novament convé implementar reintents en cas de fallades puntuals, per assegurar-te que cap token queda en un estat intermedi perillós.
Proves avançades amb Play Billing Lab
Una part que molts desenvolupadors subestimen és la fase de proves. Per llançar amb certa seguretat, necessites poder simular errors de xarxa, respostes no estàndard i casos extrems. Aquí entra Play Billing Lab, una app gratuïta a Google Play pensada específicament per provar integracions de la Play Billing Library.
Play Billing Lab inclou un simulador de respostes que permet forçar diferents BillingResponseCode a les trucades de la teva app a la Biblioteca de Facturació. D'aquesta manera, pots recrear escenaris on, per exemple, el client no aconsegueix consumir la compra per un problema de xarxa, però el teu backend sí que processa la RTDN correctament i acaba concedint el dret sense intervenció de l'usuari.
Perquè la teva app pugui comunicar-se amb el simulador, has d'habilitar les proves de “billing overrides” usant metadades al 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>
l'etiqueta enableBillingOverridesTesting activa les proves de respostes simulades de la Billing Library. L'etiqueta NONPRODUCTION és una mena de salvavides per recordar que aquesta build no ha d'anar a producció amb els overrides actius. Quan prepareu la versió final per als usuaris, assegureu-vos de eliminar aquestes metadades o utilitzar un manifest separat.
Un cop configurat, des de l'app Play Billing Lab inicies sessió amb un compte de tester de llicències, actives l'opció “Simulate Play Billing Library response” i selecciones quins codis d'error vols tornar per a cada API (per exemple, un error concret a consumeAsync). Després simplement obris la teva app i executes el flux que vols provar: el simulador tornarà les respostes configurades i podràs verificar que la teva lògica de reintents, maneig derrors i RTDN es comporta com esperes.
Canvis clau d'API en migrar a Play Billing Library 7
Més enllà de les RTDN i les proves, la migració a PBL 7 implica tocar alguns punts concrets d'API. Per als que veniu de PBL 5 o 6, convé repassar els canvis més rellevants perquè el projecte compile sense sorpreses i la lògica de negoci segueixi quadrant.
En primer lloc, les APIs relacionades amb ProrationMode per a canvis de subscripció han estat retirades. Ara es fa servir ReplacementMode per gestionar canvis de pla (upgrades, downgrades, etc.). Si encara fas servir mètodes com setReplaceProrationMode o setReplaceSkusProrationMode, hauràs de migrar-los a les noves variants de setSubscriptionReplacementMode i ajustar la lògica segons la documentació actualitzada.
També s'ha eliminat l'API launchPriceConfirmationFlow, que ja estava prèviament marcada com a obsoleta. Per manejar canvis de preu de subscripció hauràs de recolzar-te en els nous fluxos i recomanacions de la guia de canvis de preus, on es detalla com informar correctament l'usuari i com es gestionen els consentiments.
Un altre punt important són les APIs de facturació alternativa. Els mètodes BillingClient.Builder.enableAlternativeBilling, AlternativeBillingListener y AlternativeChoiceDetails han desaparegut a favor d'una nomenclatura més alineada: ara has d'usar BillingClient.Builder.enableUserChoiceBilling() al costat de UserChoiceBillingListener y UserChoiceDetails. Segons Google, es tracta bàsicament d'un canvi de nom sense variacions de comportament, en un context marcat per acords com Google i Epic Games pacten obrir Android.
Finalment, s'introdueix un codi d'error nou NETWORK_ERROR en BillingResult, i s'ajusten els significats i condicions de SERVICE_TIMEOUT i SERVICE_UNAVAILABLE. Si tens lògica personalitzada de maneig derrors (per exemple, decidir quan mostrar un missatge a lusuari, quan reintentar en silenci, etc.), és recomanable revisar-la per tenir en compte aquests nous matisos.
Transaccions pendents i absència de ordre fins a PURCHASED
Un canvi delicat a PBL 7 és que la biblioteca ja no genera un ID de comanda per a compres pendents. En aquests casos, el orderId només estarà disponible quan la compra passi a l'estat PURCHASED. Això afecta especialment els fluxos on feies servir l'ID de comanda com a referència primària des del primer moment.
La recomanació de Google és que et donis suport al purchaseToken per als teus registres i conciliacions, almenys mentre la transacció estigui en estat pendent. Si trobes una compra que ha desaparegut de Play, consulta què fer si la compra desapareix.
Si encara no heu treballat amb pendents, revisa la guia d'integració de la Billing Library i la documentació sobre gestió del cicle de vida de les compres. Aquí trobaràs els diferents estats, com reaccionar a cadascú i com encaixen les RTDN en aquest trencaclosques.
Noves capacitats opcionals a PBL 7: quotes virtuals i prepagaments
Entre les novetats “boniques” de PBL 7 hi ha les subscripcions de quotes virtuals (virtual installment subscriptions) i el suport estès de compres pendents per a subscripcions prepagades. Aquestes funcions no són obligatòries, però us poden donar més joc a l'hora d'adaptar el vostre model de negoci a diferents mercats.
Les quotes virtuals permeten que un usuari pagui una subscripció de més durada a petites quotes periòdiques, en lloc d'un pagament únic gran. A efectes de cobrament per al desenvolupador, Google indica que segueixes rebent pagaments mensuals en un pla anual amb quotes mensuals, i que si l'usuari deixa de pagar una quota, ni Google ni tu heu d'intentar recuperar quotes passades. Això fa que, a la pràctica, la seva utilitat sigui força semblant a una subscripció mensual normal, almenys en la seva fase inicial.
De moment, aquestes subscripcions de quotes només estan disponibles a Brasil, França, Itàlia i Espanya, i Google recomana vigilar la Play Console per veure nous països suportats. La configuració es fa mitjançant ProductDetails.InstallmentPlanDetails i seguint la guia específica per integrar-les a la teva app.
En paral·lel, s'amplia el suport de compres pendents per a subscripcions prepagades. Ara pots oferir models on l'usuari inicia la compra a l'app i completa el pagament posteriorment per altres mitjans, i la Billing Library sap manejar aquest flux correctament. L'activació es realitza trucant a enablePendingPurchases() en inicialitzar BillingClient i, per al cas específic de plans prepagats, usant PendingPurchasesParams.Builder.enablePrepaidPlans().
Terminis de deprecació de Play Billing Library 5 i 6
Amb PBL 7 en escena, Google ha posat dates clares per a la retirada de suport de les versions 5 i 6. Si segueixes en alguna, has de marcar en vermell el calendari:
- Google Play Billing Library 5 es depreca oficialment el 31 d'agost del 2024 per a noves apps i actualitzacions. Hi ha la possibilitat de sol·licitar una extensió fins a l'1 de novembre de 2024, però no és una cosa en què hagis de confiar a llarg termini.
- Google Play Billing Library 6 es podrà fer servir per publicar noves apps fins a l'1 d'agost de 2025, i per actualitzar apps existents fins a l'1 de novembre de 2025.
Passada aquesta data, si no has migrat almenys a la versió 6 o idealment a la versió 7, tindràs bloquejades les actualitzacions a la Play Console. Encara que la teva app seguirà funcionant als dispositius dels usuaris, quedaràs congelat sense poder corregir bugs ni afegir noves funcions que depenguin de publicació a la botiga.
El cas de .NET MAUI i les limitacions actuals
Si estàs treballant amb .NET MAUI i subscripcions a Android, probablement ja hauràs llegit o patit que la cosa no és tan senzilla. Molts projectes feien servir Plugin.InAppBilling de James Montemagno, però el plugin està arxivat i sense manteniment, així que no s'actualitzarà per suportar Billing Library 7. Al mateix temps, el paquet oficial Xamarin.Android.Google.BillingClient s'ha quedat ancorat a l'ecosistema Xamarin.Android i no és compatible de manera directa amb .NET MAUI.
La conseqüència pràctica és que la Play Console avisa que la teva app no utilitza Billing Library 7.0.0 o superior, cosa que bloqueja actualitzacions si segueixes tirant de llibreries antigues. Alguns desenvolupadors han optat per solucions dràstiques, com eliminar temporalment les subscripcions per poder pujar-ne una versió, però òbviament això no és sostenible si el teu model de negoci depèn d'aquesta monetització.
En aquest context, molts equips estan valorant alternatives com SDKs de tercers que ja suporten PBL 7 per sota i exposen una API més estable i multiplataforma (per exemple, solucions de backend de subscripcions amb SDK per a Android, iOS i altres plataformes). Aquests serveis solen encarregar-se de les migracions de versió de Billing Library i exposen un wrapper estable, cosa que redueix força l'estrès amb cada nova deprecació de Google.
Mentre Microsoft i l'equip de MAUI no ofereixin un paquet oficial actualitzat i plenament compatible amb Billing Library 7, les opcions passen per: implementar el teu propi binding a la Billing Library nativa, fer servir un servei de tercers o replantejar la manera com integres les compres dins del projecte MAUI. En qualsevol cas, convé no deixar la decisió per al darrer moment, perquè les dates límit de Play no es mouen.
En conjunt, l'actualització a Google Play Billing Library v7 suposa revisar dependències, netejar API obsoletes, reforçar la lògica de backend amb verificació de compres i RTDN, i aprofitar eines de prova com Play Billing Lab per treure a la llum tots els errors abans d'arribar a producció; qui es prengui el temps d'afinar aquesta migració podrà gestionar millor plans prepagats, quotes virtuals, errors de xarxa i canvis de cicle de vida de subscripció, i tindrà moltes més paperetes per mantenir uns ingressos estables i una experiència d'usuari acurada a Google Play. Comparteix la informació perquè més usuaris coneguin del tema.