Il sistema di fatturazione di Google Play è un servizio che ti consente di vendere contenuti e prodotti 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 tuo backend. Se esegui l'integrazione con la fatturazione di Google Play per la prima volta, puoi iniziare leggendo la sezione Preparativi.
Se vendevi abbonamenti con la fatturazione di Google Play prima di maggio 2022, è importante capire come adottare le nuove funzionalità mantenendo i tuoi abbonamenti esistenti.
La prima cosa da sapere è che tutti gli abbonamenti, le app e le integrazioni di backend esistenti funzioneranno come prima del rilascio di maggio 2022. Non è necessario apportare modifiche immediate e puoi adottare queste nuove funzionalità 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 continueranno a funzionare come prima.
Ecco una panoramica degli aggiornamenti di maggio 2022:
- La nuova Google Play Console consente di creare e gestire abbonamenti, piani base e offerte. Sono inclusi gli abbonamenti nuovi e di cui è stata eseguita la migrazione.
- L'API Google Play Developer contiene aggiornamenti per supportare la nuova funzionalità dell'interfaccia utente di Google Play Console in formato API. In particolare, è disponibile una nuova versione dell'API Subscription Purchases. Utilizza questa API per controllare lo stato degli abbonamenti e gestire gli acquisti di abbonamenti.
- La nuova versione 5 di Libreria Fatturazione Play consente alla tua app di usufruire di tutte le nuove funzionalità di abbonamento. Quando è tutto pronto per eseguire l'upgrade alla versione 5, segui le indicazioni riportate nella guida alla migrazione.
Configurazione degli abbonamenti
Gestione degli abbonamenti tramite Google Play Console
A partire da maggio 2022, noterai alcune differenze in Google Play Console.
Ora un singolo abbonamento può avere più piani base e offerte. Gli SKU degli abbonamenti 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 Modifiche recenti agli abbonamenti in Play Console per le descrizioni dei nuovi oggetti, incluse le relative funzionalità e configurazione. Tutti i tuoi prodotti in abbonamento esistenti vengono visualizzati in questo nuovo formato in Google Play Console. Ora ogni SKU è rappresentato da un oggetto abbonamento contenente 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'unica offerta o un unico piano base compatibile con le versioni precedenti.
L'offerta o il piano base compatibile con le versioni precedenti viene restituito nell'ambito di uno SKU per le app che utilizzano il metodo querySkuDetailsAsync() ora deprecato.
Per ulteriori informazioni sulla configurazione e sulla gestione delle offerte compatibili con le versioni precedenti, consulta Informazioni sugli abbonamenti. Una volta che la tua app utilizza solo queryProductDetailsAsync() e non esistono più versioni precedenti che effettuano acquisti, non è più necessario utilizzare un'offerta compatibile con le versioni precedenti.
Gestione degli abbonamenti tramite l'API Subscriptions Publishing
L'API Play Console 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 prodotti e abbonamenti con acquisto una tantum, quindi non è necessario
apportare modifiche immediate 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 in 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,
gli abbonamenti esistenti ora vengono visualizzati come di 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 per 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 tabella seguente:
| 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
contrassegnandoglie come compatibili con le versioni precedenti.
Oltre a mantenere i metodi precedenti, la versione 5 della Libreria Fatturazione Play 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) 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 può 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 senza abbonamento. Per gli acquisti una tantum, puoi utilizzare
getOneTimePurchaseOfferDetails().
Play Billing Library 5 include anche metodi nuovi ed esistenti 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, tra cui ProductDetails e un
String che rappresenta il token dell'offerta specifica 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 passare un valore BillingClient.SkuType, come nelle versioni precedenti, o 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 il prima possibile per iniziare a usufruire di queste nuove funzionalità degli abbonamenti.
Gestione dello stato dell'abbonamento
Questa sezione descrive le modifiche principali ai componenti di backend di un'integrazione del sistema di fatturazione di 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ù subscriptionId. Se ti basi su questo campo per identificare il prodotto in abbonamento, devi aggiornarlo per ottenere queste informazioni dallo stato dell'abbonamento utilizzando purchases.subscriptionv2:get una volta ricevuta la notifica. Ogni elemento SubscriptionPurchaseLineItem
nella raccolta lineItems restituito nell'ambito dello stato di acquisto includerà il productId corrispondente.
API Subscriptions Purchases: recupero dello stato dell'abbonamento
Nelle versioni precedenti dell'API Purchases.subscriptions, potevi eseguire query sullo 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 Purchases.subscriptions, utilizza
purchases.subscriptionsv2:get
per ottenere lo stato dell'acquisto dell'abbonamento. Questa API è compatibile con gli abbonamenti sottoposti a migrazione, i nuovi abbonamenti (sia prepagati che con rinnovo automatico) e gli acquisti di tutti i tipi. Puoi utilizzare questo endpoint per verificare lo stato dell'iscrizione quando ricevi le notifiche. L'oggetto restituito, SubscriptionPurchaseV2, contiene nuovi campi, ma include ancora i dati precedenti 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 per gli 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, poiché un utente può avere una sola ricarica non utilizzata alla volta.
- [Nuovo campo] SubscriptionState: specifica lo stato dell'oggetto dell'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, poiché 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 di abbonamento. La tabella seguente mostra come i campi dell'endpoint dell'abbonamento precedente vengono mappati ai campi corrispondenti in purchases.subscriptionv2.
| SubscriptionPurchase | SubscriptionPurchaseV2 |
|---|---|
countryCode |
regionCode |
orderId |
latestOrderId |
| (nessun campo equivalente) | lineItems (elenco di
SubscriptionPurchaseLineItem)
che rappresenta i prodotti acquistati 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 |
(nessun campo equivalente) Queste informazioni sono disponibili in offer per ciascuno degli abbonamenti acquistati. |
| developerPayload | (Nessun campo equivalente) Il payload sviluppatore è stato ritirato |
| paymentState | (nessun campo equivalente) Puoi dedurre lo stato del pagamento da subscriptionState:
|
cancelReason,
userCancellationTimeMillis,
cancelSurveyResult |
canceledStateContext |
linkedPurchaseToken |
linkedPurchaseToken (nessuna modifica) |
purchaseType |
Test: tramite 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 è stato eseguito l'upgrade di
purchases.subscriptions:get
a
purchases.subscriptionsv2:get,
per il momento il resto delle funzioni di gestione degli abbonamenti degli sviluppatori rimane immutato nell'endpoint purchases.subscriptions,
pertanto puoi continuare a utilizzare
purchases.subscriptions:acknowledge,
purchases.subscriptions:cancel,
purchases.subscriptions:defer,
purchases.subscriptions:refund,
e
purchases.subscriptions:revoke
come prima.
API Pricing
Utilizza l'endpoint
monetization.convertRegionPrices
per calcolare i prezzi regionali come faresti tramite
Play Console. Questo metodo accetta un singolo prezzo in qualsiasi valuta supportata da Google 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.