Il sistema di fatturazione di Google Play è un servizio che ti consente di vendere prodotti e contenuti digitali nella tua app Android. Con la release di maggio 2022, abbiamo cambiato il modo in cui vengono definiti i prodotti in abbonamento e questo influisce sul modo in cui vengono venduti in-app e gestiti nel backend. Se è la prima volta che esegui l'integrazione con Fatturazione Google Play, puoi avviarla consultando la pagina Preparazione.
Se vendevi abbonamenti con Fatturazione Google Play prima di maggio 2022, è importante capire come adottare le nuove funzionalità mantenendo gli abbonamenti esistenti.
La prima cosa da sapere è che tutti gli abbonamenti, le app e le integrazioni di backend esistenti funzionano come prima della release di maggio 2022. Non devi apportare alcuna modifica immediata e potrai adottare queste nuove funzioni nel tempo. Ogni release principale della Libreria Fatturazione Google Play è supportata per due anni dopo il rilascio. Le integrazioni esistenti con l'API Google Play Developer continuano a funzionare come prima.
Ecco una panoramica degli aggiornamenti di maggio 2022:
- La nuova Google Play Console ti consente di creare e gestire abbonamenti, piani base e offerte. Sono inclusi gli abbonamenti nuovi e di cui è stata eseguita la migrazione.
- L'API Play Developer contiene aggiornamenti per supportare le nuove funzionalità dell'interfaccia utente di Google Play Console sotto forma di API. In particolare, è disponibile una nuova versione dell'API Subscription Purchases. Utilizza questa API per controllare lo stato degli abbonamenti e gestire gli acquisti degli abbonamenti.
- La nuova Libreria Fatturazione Play versione 5 consente alla tua app di usufruire di tutte le nuove funzionalità dell'abbonamento. Quando sarà tutto pronto per eseguire l'upgrade alla versione 5, segui le indicazioni riportate nella guida alla migrazione.
Configurazione degli abbonamenti
Gestire gli abbonamenti tramite Google Play Console
A partire da maggio 2022, noterai alcune differenze in Google Play Console.
Un singolo abbonamento ora può avere più piani base e offerte. Gli SKU di abbonamento creati in precedenza ora vengono visualizzati in Play Console sotto forma di nuovi oggetti relativi ad abbonamenti, piani base e offerte. Se non l'hai ancora fatto, consulta la pagina Modifiche recenti agli abbonamenti in Play Console per le descrizioni dei nuovi oggetti, incluse le funzionalità e la configurazione. Tutti i prodotti in abbonamento preesistenti vengono visualizzati in Google Play Console in questo nuovo formato. Ogni SKU è ora rappresentato da un oggetto abbonamento che contiene un singolo piano base e un'offerta compatibile con le versioni precedenti, se applicabile.
Poiché le integrazioni precedenti prevedevano che ogni abbonamento includesse una singola offerta, rappresentata da un oggetto SkuDetails, ogni abbonamento può avere un singolo piano base o un'unica offerta compatibile con le versioni precedenti.
Il piano base o l'offerta compatibile con le versioni precedenti vengono restituiti come parte di uno SKU per le app che utilizzano il metodo querySkuDetailsAsync(), ora deprecato.
Per ulteriori informazioni sulla configurazione e sulla gestione di offerte compatibili con le versioni precedenti, consulta Informazioni sugli abbonamenti. Se la tua app utilizza solo queryProductDetailsAsync() e, quando non sono ancora disponibili versioni precedenti della tua app, non è più necessario utilizzare un'offerta compatibile con le versioni precedenti.
Gestione degli abbonamenti tramite l'API Subscriptions Publishing
L'API Play Developer
contiene nuove funzionalità per l'acquisto di abbonamenti. L'API inappproducts per la gestione degli SKU continua a funzionare come prima, inclusa la gestione di abbonamenti e prodotti acquistati una tantum, quindi non devi apportare alcuna modifica immediata per mantenere l'integrazione.
Tuttavia, è importante notare che Google Play Console utilizza solo le nuove entità
di abbonamento. Una volta che inizi a modificare gli abbonamenti nella console, l'API inappproducts non può più essere utilizzata per gli abbonamenti.
Se hai usato l'API Publishing prima di maggio 2022, per evitare problemi,
tutti gli abbonamenti esistenti ora vengono visualizzati in sola lettura
in Google Play Console. Se provi ad apportare modifiche, potresti ricevere un avviso che spiega
questo limite. Prima di modificare ulteriormente gli abbonamenti nella console, devi aggiornare l'integrazione del backend in modo da utilizzare i nuovi endpoint di pubblicazione degli abbonamenti. I nuovi endpoint monetization.subscriptions, monetization.subscriptions.baseplans e monetization.subscriptions.offers ti consentono di gestire tutti i piani base e le offerte disponibili. Puoi vedere come i diversi campi vengono mappati dall'entità InAppProduct ai nuovi oggetti in monetization.subscriptions nella seguente tabella:
| Prodotto in-app | Abbonamento |
|---|---|
packageName |
packageName |
sku |
productId |
status |
basePlans[0].state |
prices |
basePlans[0].regionalConfigs.price |
listings |
schede |
defaultPrice |
Nessuna equivalenza |
subscriptionPeriod |
basePlans[0].autoRenewingBasePlanType.billingPeriodDuration |
trialPeriod |
basePlans[0].offers[0].phases[0].regionalConfigs[0].free |
gracePeriod |
basePlans[0].autoRenewingBasePlanType.gracePeriodDuration |
subscriptionTaxesAndComplianceSettings |
taxAndComplianceSettings |
Questo aggiornamento dell'API obbligatorio si applica solo all'API Publishing (gestione degli SKU).
Modifiche alla Libreria Fatturazione Play
Per supportare una migrazione graduale, la Libreria Fatturazione Play include tutti i metodi e gli oggetti disponibili nelle versioni precedenti.
Gli oggetti e le funzioni di SkuDetails come querySkuDetailsAsync() esistono ancora, quindi puoi eseguire l'upgrade per utilizzare nuove funzionalità senza dover aggiornare immediatamente il codice degli abbonamenti esistenti.
Puoi anche controllare quali offerte sono disponibili con questi metodi contrassegnandole come compatibili con le versioni precedenti.
Oltre a mantenere i metodi precedenti, Libreria Fatturazione Play 5 ora include un nuovo oggetto ProductDetails e un metodo queryProductDetailsAsync() corrispondente per gestire nuove entità e funzionalità. I prodotti in-app esistenti (acquisti una tantum e di consumo) sono ora supportati anche da ProductDetails.
Per un abbonamento, ProductDetails.getSubscriptionOfferDetails()
restituisce un elenco di tutti i piani base e le offerte che l'utente può acquistare.
Ciò significa che puoi accedere a tutti i piani base e le offerte idonee per l'utente, indipendentemente dalla compatibilità con le versioni precedenti.
getSubscriptionOfferDetails() restituisce null per i prodotti
non in abbonamento. Per gli acquisti una tantum, puoi utilizzare
getOneTimePurchaseOfferDetails().
Libreria Fatturazione Play 5 include anche metodi nuovi e precedenti per avviare il flusso di acquisto. Se l'oggetto BillingFlowParams passato a
BillingClient.launchBillingFlow()
viene configurato utilizzando un oggetto SkuDetails, il sistema estrae le informazioni
sull'offerta per venderle dal piano base o dall'offerta compatibile con le versioni precedenti
corrispondente allo SKU. Se l'oggetto BillingFlowParams passato a BillingClient.launchBillingFlow() viene configurato utilizzando oggetti ProductDetailsParams, che includono ProductDetails e un String che rappresenta il token di offerta specifico per l'offerta acquistata, il sistema utilizza queste informazioni per identificare il prodotto acquisito dall'utente.
queryPurchasesAsync() restituisce tutti gli acquisti di proprietà
dell'utente. Per indicare il tipo di prodotto richiesto, puoi trasmettere un valore BillingClient.SkuType, come nelle versioni precedenti, oppure un oggetto QueryPurchasesParams contenente un valore BillingClient.ProductType che rappresenta le nuove entità di abbonamento.
Ti consigliamo di aggiornare le tue app alla versione 5 della libreria quanto prima per poter iniziare a sfruttare le nuove funzionalità dell'abbonamento.
Gestione dello stato dell'abbonamento
Questa sezione descrive le modifiche principali ai componenti di backend di un'integrazione del sistema di fatturazione Google Play che devono essere implementate per la migrazione alla versione 5.
Notifiche in tempo reale per lo sviluppatore
A breve l'oggetto SubscriptionNotification non conterrà più un subscriptionId. Se utilizzi questo campo per identificare il prodotto in abbonamento, dopo aver ricevuto la notifica devi eseguire l'aggiornamento per ottenere queste informazioni dallo stato dell'abbonamento utilizzando purchases.subscriptionv2:get. Ogni elemento SubscriptionPurchaseLineItem
nella raccolta lineItems che viene restituito come parte dello stato di acquisto
includerà il corrispondente productId.
API Subscriptions Purchases: recupero dello stato dell'abbonamento
Nelle versioni precedenti dell'API Subscriptions Purchases, potevi eseguire query sullo stato degli abbonamenti utilizzando purchases.subscriptions:get.
Questo endpoint non è stato modificato e continua a funzionare per gli acquisti di abbonamenti compatibili con le versioni precedenti. Questo endpoint non supporta nessuna nuova funzionalità rilasciata a maggio 2022.
Nella nuova versione dell'API Subscriptions Purchases, utilizza purchases.subscriptionsv2:get per ottenere lo stato di acquisto degli abbonamenti. Questa API è compatibile con gli abbonamenti sottoposti a migrazione, i nuovi abbonamenti (prepagati e con rinnovo automatico) e gli acquisti di tutti i tipi. Puoi utilizzare questo endpoint per verificare lo stato degli abbonamenti quando ricevi notifiche. L'oggetto restituito, SubscriptionPurchaseV2, contiene nuovi campi, ma include ancora dati precedenti necessari per continuare a supportare gli abbonamenti esistenti.
Campi SubscriptionPurchaseV2 per piani prepagati
Sono stati aggiunti nuovi campi per supportare i piani prepagati, che vengono estesi dall'utente anziché essere rinnovati automaticamente. Tutti i campi si applicano ai piani prepagati come per gli abbonamenti con rinnovo automatico, con le seguenti eccezioni:
- [New field] lineItems[0].prepaid_plan.allowExtendAfterTime: indica quando un utente può acquistare un'altra ricarica per estendere il piano prepagato, in quanto un utente può avere una sola ricarica non consumata alla volta.
- [Nuovo campo] SubscriptionState: specifica lo stato dell'oggetto abbonamento.
Per i piani prepagati, questo valore è sempre
ACTIVE,PENDINGoCANCELED. - lineItems[0].expiryTime: questo campo è sempre presente per i piani prepagati.
- paused_state_context: questo campo non è mai presente perché i piani prepagati non possono essere messi in pausa.
- lineItems[0].auto_renewing_plan: non presente per i piani prepagati.
- canceled_state_context: non presente per i piani prepagati, in quanto questo campo si applica solo agli utenti che annullano attivamente un abbonamento.
- lineItems[0].productId: questo campo sostituisce
subscriptionIddelle versioni precedenti.
Campi SubscriptionPurchaseV2 per abbonamenti ricorrenti
purchases.subscriptionv2 contiene nuovi campi che forniscono maggiori dettagli
sui nuovi oggetti abbonamento. La tabella seguente mostra in che modo i campi dell'endpoint dell'abbonamento precedente vengono mappati ai campi corrispondenti in purchases.subscriptionv2.
| AcquistoAbbonamento | AcquistoAbbonamentoV2 |
|---|---|
countryCode |
regionCode |
orderId |
latestOrderId |
| (nessun campo equivalente) | lineItems (elenco di
SubscriptionPurchaseLineItem) che rappresenta i prodotti acquisiti con l'acquisto |
| (nessun campo equivalente) | lineItems.offerDetails.basePlanId |
| (nessun campo equivalente) | lineItems.offerDetails.offerId |
| (nessun campo equivalente) | lineItems.offerDetails.offerTags |
startTimeMillis |
startTime |
expiryTimeMillis |
lineItems.expiryTime (ogni abbonamento acquisito
nell'acquisto ha il proprio expiryTime) |
| (nessun campo equivalente) | subscriptionState (indica lo
stato dell'abbonamento) |
| (nessun campo equivalente) | pausedStateContext (presente solo se lo stato
dell'abbonamento è SUBSCRIPTION_STATE_PAUSED) |
autoResumeTimeMillis |
pausedStateContext.autoResumeTime |
| (nessun campo equivalente) | canceledStateContext (presente solo se lo
stato dell'abbonamento è SUBSCRIPTION_STATE_CANCELED) |
| (nessun campo equivalente) | testPurchase (presente solo negli acquisti di tester autorizzati) |
autoRenewing |
lineItems.autoRenewingPlan.autoRenewEnabled |
priceCurrenceCode, priceAmountMicros e introductoryPriceInfo |
(nessun campo equivalente) Queste informazioni sono disponibili in basePlan/offer per
ciascuno degli abbonamenti acquistati. |
| Payload sviluppatore | Il payload per gli sviluppatori (nessun campo equivalente) è stato deprecato |
| statopagamento | (nessun campo equivalente) Puoi dedurre lo stato del pagamento da subscriptionState:
|
cancelReason, userCancellationTimeMillis e cancelSurveyResult |
canceledStateContext |
linkedPurchaseToken |
linkedPurchaseToken (nessuna variazione) |
purchaseType |
Test: fino al giorno testPurchasePromozione (nessun campo equivalente); disponibile a breve |
priceChange |
lineItems.autoRenewingPlan.priceChangeDetails |
profileName, emailAddress, givenName, familyName e profileId |
subscribeWithGoogleInfo |
acknowledgementState |
acknowledgementState (no change) |
promotionType,
promotionCode |
(nessun campo equivalente); disponibile a breve |
externalAccountId, obfuscatedExternalAccountId e obfuscatedExteranlProfileId |
externalAccountIdentifiers |
Altre funzioni di gestione degli abbonamenti
Anche se è stato eseguito l'upgrade di purchases.subscriptions:get a purchases.subscriptionsv2:get, per il momento le altre funzioni di gestione degli abbonamenti per sviluppatori rimangono invariate nell'endpoint purchases.subscriptions, quindi puoi continuare a utilizzare purchases.subscriptions:acknowledge, purchases.subscriptions:cancel, purchases.subscriptions:defer, purchases.subscriptions:refund e purchases.subscriptions:revoke
API dei prezzi
Utilizza l'endpoint
monetization.convertRegionPrices
per calcolare i prezzi regionali come faresti tramite
Play Console. Questo metodo accetta un unico prezzo in qualsiasi valuta supportata da Google Play e restituisce i prezzi convertiti (inclusa l'aliquota fiscale predefinita, se applicabile) per tutte le regioni in cui Google Play supporta gli acquisti.