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 modalità di definizione dei prodotti in abbonamento, il che influisce sulla modalità di vendita in-app e di gestione nel backend. Se stai eseguendo l'integrazione con la Fatturazione Google Play per la prima volta, puoi iniziare leggendo 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 esattamente come prima della release di maggio 2022. Non devi fare nulla nell'immediato perché puoi adottare le 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 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 sia gli abbonamenti nuovi sia quelli di cui è stata eseguita la migrazione.
- L'API Play Developer contiene aggiornamenti per supportare la nuova 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 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à degli abbonamenti. Quando è tutto pronto per eseguire l'upgrade alla versione 5, segui le istruzioni riportate nella guida alla migrazione.
Configurazione delle sottoscrizioni
Gestione degli abbonamenti con 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 degli abbonamenti creati in precedenza ora vengono visualizzati in Play Console come questi 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 le relative funzionalità e configurazioni. Tutti i tuoi prodotti in abbonamento preesistenti vengono visualizzati in Google Play Console in questo nuovo formato. Ogni SKU è ora rappresentato da un oggetto Subscription 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'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 ulteriori informazioni sulla configurazione e sulla gestione delle offerte compatibili con le versioni precedenti, consulta Informazioni sugli abbonamenti. Dopo che la tua app utilizza solo queryProductDetailsAsync() e dopo che non ci sono più versioni precedenti della tua app che effettuano acquisti, non è più necessario utilizzare un'offerta compatibile con le versioni precedenti.
Gestione degli abbonamenti utilizzando 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 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. Dopo aver iniziato a modificare gli abbonamenti in Play 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 modalità di sola lettura in Google Play Console.
Se provi ad apportare modifiche, potresti ricevere un avviso che spiega questa limitazione.
Prima di apportare ulteriori modifiche agli 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 i diversi campi vengono mappati 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 |
listings |
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 obbligatorio dell'API si applica solo all'API Publishing (gestione degli 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 la nuova 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 precedenti, la 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 prodotti di consumo) sono ora supportati anche da ProductDetails.
Per un abbonamento, ProductDetails.getSubscriptionOfferDetails()
restituisce un elenco di tutti i piani base e delle offerte che l'utente è idoneo ad acquistare.
Ciò significa che puoi accedere a tutti i piani base e alle 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 Play 5 include anche metodi nuovi e precedenti per lanciare 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 che corrisponde 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 specifico per l'offerta acquistata, il sistema utilizza queste informazioni per identificare il prodotto acquistato 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à per gli abbonamenti.
Gestione dello stato dell'abbonamento
Questa sezione descrive le principali modifiche 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, devi eseguire l'aggiornamento per ottenere queste informazioni dallo stato
dell'abbonamento utilizzando purchases.subscriptionsv2:get dopo aver ricevuto la
notifica. Ogni elemento SubscriptionPurchaseLineItem nella raccolta lineItems restituita nell'ambito dello stato dell'acquisto includerà il productId corrispondente.
API Subscriptions Purchases: recupero dello stato dell'abbonamento
Nelle versioni precedenti dell'API Subscriptions Purchases, 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 Subscriptions Purchases, utilizza
purchases.subscriptionsv2:get per ottenere lo stato di acquisto dell'abbonamento.
Questa API è compatibile con gli abbonamenti di cui è stata eseguita la 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'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 così 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, 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 è sempreACTIVE,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, poiché questo campo si applica solo agli utenti che annullano attivamente un abbonamento.lineItems[0].productId: questo campo sostituiscesubscriptionIddelle versioni precedenti.
Campi SubscriptionPurchaseV2 per gli abbonamenti ricorrenti
purchases.subscriptionsv2 contiene nuovi campi che forniscono maggiori dettagli sui nuovi oggetti di abbonamento. La tabella seguente mostra come i campi dell'endpoint di abbonamento precedente vengono mappati ai campi corrispondenti in purchases.subscriptionsv2.
| 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 nella offer per
ciascuno degli abbonamenti acquistati. |
| developerPayload | (nessun campo equivalente) il payload dello sviluppatore è stato ritirato |
| paymentState | (nessun campo equivalente) Puoi dedurre lo stato del pagamento da subscriptionState:
|
cancelReason,
userCancellationTimeMillis,
cancelSurveyResult |
canceledStateContext |
linkedPurchaseToken |
linkedPurchaseToken (nessuna variazione) |
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
Sebbene purchases.subscriptions:get sia stato aggiornato a
purchases.subscriptionsv2:get, il resto delle funzioni di gestione degli abbonamenti
per gli sviluppatori rimane invariato per ora 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 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 fiscale predefinita, se applicabile) per tutte le regioni in cui Google Play supporta gli acquisti.