Il sistema di fatturazione di Google Play è un servizio che ti consente di vendere prodotti e contenuti digitali nella tua app per Android. Con la release di maggio 2022, abbiamo modificato la definizione dei prodotti in abbonamento, il che influisce sul modo in cui vengono venduti in-app e gestiti nel backend. Se esegui l'integrazione con Fatturazione Google Play per la prima volta, puoi iniziare leggendo la sezione Prepararsi.
Se vendevi abbonamenti con Google Play Billing prima di maggio 2022, è importante capire come adottare nuove funzionalità mantenendo gli abbonamenti esistenti.
La prima cosa da sapere è che tutti gli abbonamenti, le app e le integrazioni di backend esistenti funzionano esattamente come prima della release di maggio 2022. Non devi apportare modifiche immediate e puoi adottare queste nuove funzionalità nel tempo. Ogni release principale della libreria Google Play Billing è 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 quelli migrati.
- L'API Play Developer contiene aggiornamenti per supportare la nuova funzionalità dell'UI di Google Play Console in formato API. In particolare, è disponibile una nuova versione dell'API Subscription Purchases. Utilizza questa API per controllare lo stato dell'abbonamento e gestire gli acquisti di abbonamenti.
- La nuova Libreria Fatturazione Play versione 5 consente alla tua app di usufruire di tutte le nuove funzionalità di abbonamento. Quando è tutto pronto per 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 come nuovi oggetti di abbonamento, piano base e offerta. Se non l'hai ancora fatto, consulta l'articolo Modifiche recenti agli abbonamenti in Play Console per le descrizioni dei nuovi oggetti, incluse funzionalità e configurazione. Tutti i tuoi 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 offerta compatibile con le versioni precedenti.
Il piano base o l'offerta compatibile con le versioni precedenti viene restituito come parte di uno SKU
per le app che utilizzano il metodo querySkuDetailsAsync() ora deprecato.
Per maggiori informazioni sulla configurazione e sulla gestione delle offerte compatibili con le versioni precedenti,
vedi
Informazioni sugli abbonamenti.
Una volta che la tua app utilizza solo queryProductDetailsAsync() e non ci sono più versioni precedenti dell'app che effettuano acquisti, non è più necessario utilizzare un'offerta compatibile con le versioni precedenti.
Gestire gli abbonamenti tramite l'API Subscriptions Publishing
L'API Play Developer
contiene nuove funzionalità per gli acquisti di abbonamenti. L'API
inappproducts
per la gestione degli SKU continua a funzionare come prima, inclusa la gestione
di abbonamenti e prodotti acquistabili una sola volta, quindi non devi
apportare modifiche immediate per mantenere l'integrazione.
Tuttavia, è importante notare che Google Play Console utilizza solo le nuove
entità abbonamento. Una volta che inizi a modificare gli abbonamenti nella console, l'API inappproducts non può più essere utilizzata per gli abbonamenti.
Se hai utilizzato 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 questa limitazione. 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. Nella tabella seguente puoi vedere
come vengono mappati i diversi campi dall'entità InAppProduct ai
nuovi oggetti in monetization.subscriptions:
| InAppProduct | 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 SKU).
Modifiche alla Libreria Fatturazione Play
Per supportare la migrazione graduale, la libreria Fatturazione Play include tutti i
metodi e gli oggetti disponibili nelle versioni precedenti.
Gli oggetti e le funzioni SkuDetails come querySkuDetailsAsync() esistono ancora, quindi puoi eseguire l'upgrade per utilizzare le nuove funzionalità senza dover aggiornare immediatamente anche il codice degli abbonamenti esistenti.
Puoi anche controllare quali offerte sono disponibili tramite questi metodi
contrassegnandole come compatibili con le versioni precedenti.
Oltre a mantenere i metodi legacy, la libreria Fatturazione Google 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 singoli e consumabili) ora sono supportati anche da
ProductDetails.
Per un abbonamento, ProductDetails.getSubscriptionOfferDetails()
restituisce un elenco di tutti i piani base e le offerte che l'utente è idoneo ad acquistare.
Ciò significa che puoi accedere a tutti i piani base e le offerte idonei
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().
La libreria Fatturazione Google Play 5 include anche metodi nuovi e precedenti per
avviare il flusso di acquisto. Se l'oggetto BillingFlowParams passato a
BillingClient.launchBillingFlow()
è configurato utilizzando un oggetto SkuDetails, il sistema estrae le informazioni
sull'offerta da vendere dal piano base o dall'offerta compatibile con le versioni precedenti
corrispondente allo SKU. Se l'oggetto BillingFlowParams passato a
BillingClient.launchBillingFlow() è configurato utilizzando
oggetti ProductDetailsParams, che includono ProductDetails e un
String che rappresenta il token dell'offerta specifica per l'offerta in fase di
acquisto, 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 passare
un valore BillingClient.SkuType, come nelle versioni precedenti, o un
oggetto QueryPurchasesParams che contiene un
valore BillingClient.ProductType che rappresenta le nuove entità
di abbonamento.
Ti consigliamo di aggiornare le tue app alla versione 5 della libreria il prima possibile per iniziare a usufruire di queste nuove funzionalità di 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 fai affidamento su
questo campo per identificare il prodotto in abbonamento, devi eseguire l'aggiornamento
per ottenere queste informazioni dallo stato dell'abbonamento utilizzando
purchases.subscriptionv2:get
una volta ricevuta la notifica. Ogni elemento SubscriptionPurchaseLineItem nella raccolta lineItems restituita come parte dello stato dell'acquisto includerà il productId corrispondente.
API Subscriptions Purchases: recupero dello stato dell'abbonamento
Nelle versioni precedenti dell'API Purchases.subscriptions, potevi
interrogare lo stato dell'abbonamento utilizzando
purchases.subscriptions:get.
Questo endpoint rimane invariato e continua a funzionare per gli acquisti di abbonamenti
compatibili con le versioni precedenti. Questo endpoint non supporta le nuove
funzionalità rilasciate a maggio 2022.
Nella nuova versione dell'API Subscriptions Purchases, utilizza
purchases.subscriptionsv2:get
per ottenere lo stato dell'acquisto dell'abbonamento. Questa API è compatibile con
abbonamenti migrati, nuovi abbonamenti (sia prepagati che
con rinnovo automatico) e acquisti di tutti i tipi. Puoi utilizzare questo endpoint
per verificare lo stato dell'abbonamento quando ricevi notifiche. L'oggetto restituito, SubscriptionPurchaseV2, contiene nuovi campi, ma include ancora i dati legacy necessari per continuare a supportare gli abbonamenti esistenti.
Campi SubscriptionPurchaseV2 per i piani prepagati
Sono stati aggiunti nuovi campi per supportare i piani prepagati, che vengono estesi dall'utente anziché rinnovarsi automaticamente. Tutti i campi si applicano ai piani prepagati come agli abbonamenti con rinnovo automatico, con le seguenti eccezioni:
- [Nuovo campo] lineItems[0].prepaid_plan.allowExtendAfterTime: indica quando un utente potrà acquistare un'altra ricarica per estendere il proprio piano prepagato, in quanto un utente può avere una sola ricarica non consumata alla volta.
- [Nuovo campo] SubscriptionState: specifica lo stato dell'oggetto di 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, in quanto 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 gli abbonamenti ricorrenti
purchases.subscriptionv2 contiene nuovi campi che forniscono maggiori dettagli
sui nuovi oggetti abbonamento. La tabella seguente mostra come i campi dell'endpoint di abbonamento legacy vengono mappati ai campi corrispondenti in purchases.subscriptionv2.
| SubscriptionPurchase | SubscriptionPurchaseV2 |
|---|---|
countryCode |
regionCode |
orderId |
latestOrderId |
| (nessun campo equivalente) | lineItems.offerPhase (identifica la fase attuale: prova senza costi, prezzo di lancio, ripartizione proporzionale, prezzo base) |
| (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 dei tester con licenza) |
autoRenewing |
lineItems.autoRenewingPlan.autoRenewEnabled |
priceCurrenceCode,
priceAmountMicros |
lineItems.autoRenewingPlan.recurringPrice |
introductoryPriceInfo |
lineItems.offerPhase.introductoryPriceQueste informazioni sono disponibili anche nel offer per
ciascuno degli abbonamenti acquistati. |
| developerPayload | Il payload sviluppatore (nessun campo equivalente) è stato ritirato |
| paymentState | (nessun campo equivalente) Puoi dedurre lo stato del pagamento da subscriptionState:
|
cancelReason,
userCancellationTimeMillis,
cancelSurveyResult |
canceledStateContext |
linkedPurchaseToken |
linkedPurchaseToken (nessuna modifica) |
purchaseType |
Test: fino al giorno testPurchasePromozione: signupPromotion |
priceChange |
lineItems.autoRenewingPlan.priceChangeDetails |
profileName,
emailAddress,
givenName,
familyName,
profileId |
subscribeWithGoogleInfo |
acknowledgementState |
acknowledgementState (no change) |
promotionType,
promotionCode |
signupPromotion |
externalAccountId,
obfuscatedExternalAccountId,
obfuscatedExteranlProfileId |
externalAccountIdentifiers |
Altre funzioni di gestione degli abbonamenti
Anche se
purchases.subscriptions:get
è stato aggiornato 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
come facevi prima.
API Pricing
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 Play e restituisce i prezzi convertiti (inclusa l'aliquota predefinita
dell'imposta, se applicabile) per tutte le regioni in cui Google Play supporta gli acquisti.