Ciclo di vita dell'abbonamento

Gli acquisti di abbonamenti possono passare attraverso diversi stati durante il loro ciclo di vita, a seconda di molti fattori, tra cui il comportamento di rinnovo automatico, le situazioni di rifiuto del pagamento e le azioni di gestione degli sviluppatori.

Gestire il ciclo di vita degli abbonamenti con rinnovo automatico

Quando lo stato dell'abbonamento di un utente cambia, il server di backend riceve un messaggio SubscriptionNotification.

Per aggiornare lo stato nel backend, chiama l'API purchases.subscriptionsv2.get con il token di acquisto incluso nella notifica. Questo endpoint fornisce l'ultimo stato dell'abbonamento dato un token di acquisto ed è considerato la fonte di riferimento per la gestione degli abbonamenti.

Il token di acquisto è valido dalla registrazione dell'abbonamento fino a 60 giorni dopo la scadenza. Dopo questa data, il token di acquisto non è più valido per chiamare l'API Google Play Developer.

Nuovi acquisti di abbonamenti con rinnovo automatico

Quando un utente acquista un abbonamento, al tuo client RTDN viene inviato un messaggio SubscriptionNotification con tipo SUBSCRIPTION_PURCHASED. Che tu riceva questa notifica o registri un nuovo acquisto in-app tramite PurchasesUpdatedListener o recuperando manualmente gli acquisti nel metodo onResume() della tua app, devi elaborare il nuovo acquisto nel tuo backend sicuro. A tale scopo, procedi nel seguente modo:

1. Esegui una query sull'endpoint purchases.subscriptionsv2.get per ottenere una risorsa subscription che contiene lo stato più recente dell'abbonamento.
2. Assicurati che il valore del campo subscriptionState sia SUBSCRIPTION_STATE_ACTIVE.
3. Verifica l'acquisto.
4. Concedi all'utente l'accesso ai contenuti. L'account utente associato all'acquisto può essere identificato con l'oggetto ExternalAccountIdentifiers della risorsa di abbonamento se gli identificatori sono stati impostati al momento dell'acquisto utilizzando setObfuscatedAccountId e setObfuscatedProfileId.

La libreria Play Billing include anche un metodo per confermare un abbonamento, acknowledgePurchase(), e un metodo per controllare lo stato della conferma, isAcknowledged(). Tuttavia, ti consigliamo di gestire l'elaborazione degli acquisti nel backend per una maggiore sicurezza.

La risorsa di abbonamento per i nuovi acquisti è simile al seguente esempio:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  "startTime": "2022-04-22T18:39:58.270Z",
  "regionCode": "US",
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  "latestOrderId": "GPA.3333-4137-0319-36762",
  "acknowledgementState": "ACKNOWLEDGEMENT_STATE_PENDING", // need to acknowledge new purchases
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": next_renewal_date,
      "autoRenewingPlan": {
        "autoRenewEnabled": true
      }
    }
  ],
}

Rinnovare l'abbonamento

Per gli abbonamenti non rateali con rinnovo automatico, viene inviata una notifica SUBSCRIPTION_RENEWED al momento del rinnovo dell'abbonamento. Per gli abbonamenti a rate, viene inviata una notifica SUBSCRIPTION_RENEWED ogni volta che l'abbonamento viene addebitato alla data di fatturazione. Assicurati che l'utente abbia ancora diritto all'abbonamento, quindi aggiorna lo stato dell'abbonamento con il nuovo expiryTime fornito nella risorsa abbonamento restituita dall'API Google Play Developer. La risorsa di abbonamento è simile al seguente esempio:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  "startTime": "2022-04-22T18:39:58.270Z",
  "regionCode": "US",
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  "latestOrderId": "GPA.3333-4137-0319-36762",
  "acknowledgementState": "ACKNOWLEDGEMENT_STATE_ACKNOWLEDGED",
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": next_renewal_date,
      "autoRenewingPlan": {
        "autoRenewEnabled": true
      }
    }
  ]
}

Non è necessario confermare i rinnovi degli abbonamenti.

Periodo di tolleranza

Se si verificano problemi di pagamento con il rinnovo di un abbonamento, Google invia una notifica all'utente e tenta periodicamente di rinnovare l'abbonamento per un certo periodo di tempo prima della scadenza. Questo periodo di recupero può consistere in un periodo di tolleranza seguito da un periodo di sospensione dell'account. Durante un periodo di tolleranza, l'utente dovrebbe avere ancora accesso al proprio diritto di abbonamento.

Il metodo queryPurchasesAsync() continua a restituire gli acquisti che rientrano nel periodo di tolleranza. Se la tua app si basa esclusivamente su queryPurchasesAsync per verificare se un utente ha diritto a un abbonamento, l'app deve gestire automaticamente i periodi di tolleranza, perché questi abbonamenti vengono visualizzati come attivi tramite la libreria Fatturazione Play.

La sincronizzazione dello stato dell'abbonamento con il backend ti consente di essere più consapevole dei pagamenti rifiutati e ti fornisce maggiori informazioni contestuali mentre cerchi di ridurre il churn involontario. Ascolta i messaggi SubscriptionNotification di tipo SUBSCRIPTION_IN_GRACE_PERIOD per ricevere una notifica quando l'utente entra in un periodo di tolleranza. Mentre l'utente si trova in un periodo di tolleranza, la risorsa abbonamento contiene autoRenewEnabled = true. Google Play estende dinamicamente il valore di expiryTime fino alla scadenza del periodo di tolleranza, perché il diritto deve durare fino all'annullamento da parte dell'utente o fino al raggiungimento della durata massima del periodo di tolleranza. Il valore del campo subscriptionState durante questo periodo è SUBSCRIPTION_STATE_IN_GRACE_PERIOD. La risorsa di abbonamento è simile al seguente esempio:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_IN_GRACE_PERIOD",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": timestamp_in_future,
      "autoRenewingPlan": {
        "autoRenewEnabled": true
      }
    }
  ],
}

Play informa gli utenti che si trovano in un periodo di tolleranza che il pagamento è stato rifiutato e li invita a risolvere i problemi relativi al metodo di pagamento nel Play Store. Quando un utente entra in un periodo di tolleranza, devi anche incoraggiarlo a correggere il suo metodo di pagamento nel caso in cui il mancato pagamento sia involontario. Un modo semplice per farlo è utilizzare l'API In-app Messaging. Se chiami questa API quando l'utente apre la tua app, viene visualizzato un messaggio di Play in una snackbar temporanea che informa l'utente che il pagamento è stato rifiutato. Questo messaggio include anche un link diretto che consente all'utente di correggere il metodo di pagamento su Google Play.

Non appena l'utente corregge il metodo di pagamento, l'abbonamento si rinnova con la data di rinnovo originale e puoi gestire il rinnovo come descritto in Rinnovi.

Se l'utente non corregge il metodo di pagamento durante il periodo di tolleranza, l'abbonamento viene sospeso e l'utente perde il diritto.

Accesso e recupero durante il periodo di tolleranza

La figura 2 mostra la cronologia di un abbonamento che entra in un periodo di tolleranza e poi viene ripristinato quando l'utente risolve il problema con il metodo di pagamento. Al termine del periodo di tolleranza, l'utente non potrà più usufruire dei vantaggi dell'abbonamento e l'account verrà sospeso.

È importante ricordare quanto segue:

• Durante un periodo di tolleranza, l'utente deve mantenere l'accesso ai vantaggi dell'abbonamento.
• Quando un abbonamento viene recuperato durante un periodo di tolleranza, la data di rinnovo non viene reimpostata.
• Se aumenti il periodo di tolleranza, ad esempio da 7 a 14 giorni, gli utenti che si trovano in un periodo di tolleranza ottengono un accesso esteso ai vantaggi dell'abbonamento.
• Se riduci il periodo di tolleranza, gli utenti che hanno usufruito del vecchio periodo di tolleranza per un periodo di tempo sufficiente a superare il nuovo periodo di tolleranza vedranno revocati immediatamente i vantaggi dell'abbonamento. Ad esempio, se riduci il periodo di tolleranza da 14 giorni a 7 giorni, i vantaggi dell'abbonamento degli utenti che si trovano tra l'8° e il 14° giorno del vecchio periodo di tolleranza vengono revocati immediatamente.
• L'abbonamento rimane attivo e non riceverai una notifica RTDN del periodo di tolleranza finché non termina il periodo di tolleranza silenzioso

Periodo di tolleranza silenzioso

Puoi impostare un periodo di tolleranza di 0 giorni, ma Google Play attenderà almeno 1 giorno per garantire un tempo sufficiente per i tentativi di pagamento. Questo periodo di tolleranza silenzioso offre una rete di sicurezza per l'elaborazione dei pagamenti. Durante questo periodo di 24 ore, l'abbonamento rimane nello stato ACTIVE.

Il modo migliore per rimanere al passo con le modifiche dello stato dell'abbonamento è ascoltare e reagire alle notifiche in tempo reale per lo sviluppatore (RTDN). Chiama il metodo purchases.subscriptionsv2.get() all'ora di RTDN anziché all'ora di scadenza per ottenere uno stato più preciso dell'abbonamento.

A seconda dello stato dell'abbonamento dopo il periodo di tolleranza silenziosa di 24 ore, dovresti ricevere una delle seguenti notifiche:

• SUBSCRIPTION_ON_HOLD (se attivato)
• SUBSCRIPTION_CANCELED (se annullato)
• SUBSCRIPTION_EXPIRED (se scaduto)
• SUBSCRIPTION_RENEWED (se il rinnovo è andato a buon fine)

Puoi anche chiamare il metodo subscriptionV2.get() in qualsiasi momento dopo il periodo di tolleranza silenzioso di 24 ore per ottenere lo stato più recente dell'abbonamento.

Sospensione dell'account

Se si verificano problemi di pagamento con il rinnovo di un abbonamento, al termine del periodo di tolleranza inizia un periodo di sospensione dell'account. Quando un abbonamento entra nello stato di sospensione dell'account, devi bloccare l'accesso al diritto dell'abbonamento.

Durante la sospensione dell'account, devi continuare a gestire eventuali annullamenti, ripristini o riacquisti degli abbonamenti in base alle necessità, perché è possibile che l'utente apporti queste modifiche mentre l'abbonamento è in sospensione.

Le notifiche in tempo reale ti avvisano quando l'utente entra nel periodo di sospensione dell'account, in modo che tu possa informarlo il prima possibile del motivo per cui il suo accesso all'abbonamento è stato sospeso. Un modo semplice per farlo è utilizzare l'API In-App Messaging. Se chiami questa API quando l'utente apre l'app, visualizzerà un messaggio in una snackbar temporanea che lo informa che il pagamento è stato rifiutato. Questo messaggio include anche un link diretto che consente all'utente di risolvere il problema con il metodo di pagamento su Google Play.

Se i tuoi utenti possono accedere ai contenuti in abbonamento al di fuori della tua app, potrebbero scoprire di aver perso l'accesso su piattaforme diverse. Potresti inviare una notifica push o un'email all'utente per informarlo che il suo abbonamento non è più attivo a causa del rifiuto del pagamento.

L'abbonamento non viene restituito dal metodo queryPurchasesAsync() durante la sospensione dell'account, quindi se la tua app si basa su questo metodo per visualizzare gli acquisti esistenti, devi supportare la sospensione dell'account per impostazione predefinita.

Con le notifiche in tempo reale per lo sviluppatore, ricevi un messaggio SubscriptionNotification di tipo SUBSCRIPTION_ON_HOLD quando un abbonamento entra in sospensione dell'account. Chiama il metodo purchases.subscriptionsv2.get dal server di backend sicuro per recuperare le nuove informazioni sull'abbonamento. Durante la sospensione dell'account, il campo expiryTime della risorsa subscription è impostato su un timestamp passato e il campo subscriptionState è impostato su SUBSCRIPTION_STATE_ON_HOLD:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_ON_HOLD",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": timestamp_in_past,
      ...
    }
  ],
}

Per ripristinare l'accesso, gli utenti devono risolvere il problema con il metodo di pagamento. Google Play informa gli utenti con l'account in sospensione del rifiuto del pagamento e ti consigliamo di invitarli a correggere il metodo di pagamento.

Dopo che l'utente avrà risolto il problema con il metodo di pagamento, l'abbonamento tornerà allo stato attivo e dovrai ripristinare l'accesso ai contenuti dell'abbonamento. In questo caso, il token di acquisto è lo stesso di prima dell'inizio della sospensione dell'account perché lo stesso acquisto viene recuperato e ricevi una notifica in tempo reale con tipo SUBSCRIPTION_RECOVERED.

Per gli abbonamenti a rate, i rifiuti e i recuperi dei pagamenti potrebbero verificarsi per qualsiasi tentativo di pagamento individuale.

Dopo il recupero, la Libreria Fatturazione Play restituisce nuovamente l'abbonamento tramite il metodo queryPurchasesAsync(). Se utilizzi questo metodo per determinare se un utente ha diritto a un abbonamento, la tua app deve gestire automaticamente il recupero dell'abbonamento dopo la sospensione dell'account.

Ascolta un messaggio SubscriptionNotification di tipo SUBSCRIPTION_RECOVERED per ricevere una notifica quando un abbonamento viene recuperato e l'utente deve riacquistare l'accesso. Se esegui una query per un abbonamento dopo aver ricevuto questa notifica, il campo expiryTime viene impostato su un timestamp futuro e il campo subscriptionState viene impostato di nuovo su SUBSCRIPTION_STATE_ACTIVE:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": next_renewal_date,
      ...
    }
  ],
}

Se l'utente non corregge il metodo di pagamento prima della fine del periodo di sospensione dell'account, riceverai una notifica RTDN di tipo SUBSCRIPTION_CANCELED. Per istruzioni sulla gestione di un annullamento, vedi Annullamenti. Quando esegui una query per un abbonamento annullato in questo modo, il campo expiryTime restituito è impostato su un timestamp passato:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_CANCELED",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": timestamp_in_past,
      ...
    }
  ],
}

Subito dopo aver ricevuto la notifica dell'annullamento durante la sospensione dell'account, riceverai anche una notifica in tempo reale con tipo SUBSCRIPTION_EXPIRED perché l'utente non ha più diritti a pagamento e l'abbonamento è stato annullato. Puoi gestire questa scadenza come faresti normalmente.

L'utente può riacquistare l'accesso acquistando lo stesso piano di abbonamento o qualsiasi altro piano che offri tramite l'app durante il periodo di sospensione dell'account dall'acquisto originale. In questo caso, viene emesso un nuovo token di acquisto e il nuovo valore viene restituito come parte di un evento SUBSCRIPTION_PURCHASED che rappresenta questa nuova istanza.

Accesso e recupero dell'account sospeso

La figura 3 mostra una cronologia per un abbonamento che viene sospeso e poi recuperato quando l'utente risolve il problema relativo al metodo di pagamento.

Analogamente all'esempio precedente, la Figura 4 mostra una cronologia per un abbonamento che prima entra in un periodo di tolleranza prima di entrare in sospensione dell'account e poi viene recuperato durante la sospensione.

È importante ricordare quanto segue:

• Prima che un abbonamento venga sospeso, Google Play effettua ulteriori tentativi di addebito sul metodo di pagamento fino a 48 ore. L'utente mantiene i vantaggi dell'abbonamento durante questo periodo. Al termine di questo periodo di nuovi tentativi, l'abbonamento viene sospeso e l'utente perde l'accesso ai vantaggi dell'abbonamento.
• L'abbonamento entra direttamente nello stato di sospensione dell'account quando riprende da uno stato di pausa con una forma di pagamento non valida.
• Quando un abbonamento viene riattivato dopo la sospensione dell'account, la data di rinnovo viene reimpostata.

Scadenze

Una volta scaduto un abbonamento, l'utente dovrebbe perdere l'accesso. In questo caso, viene inviato un messaggio SubscriptionNotification di tipo SUBSCRIPTION_EXPIRED. Quando ricevi questa notifica, esegui una query sull'API Google Play Developer per ottenere la risorsa subscription più recente. Dopo aver verificato che subscriptionState è SUBSCRIPTION_STATE_EXPIRED, rimuovi il diritto e registra lo stato dell'acquisto come non valido nel backend. La risorsa di abbonamento è simile al seguente esempio:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_EXPIRED",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": expiration_time_in_past,
      ...
    }
  ],
}

Annullamenti

Un utente può annullare volontariamente un abbonamento dal Centro abbonamenti Google Play o il suo abbonamento può essere annullato automaticamente se non viene recuperato dopo essere stato in sospensione dell'account. Gli sviluppatori possono anche attivare un annullamento con purchases.subscriptions.cancel. Quando un abbonamento viene annullato, l'utente mantiene l'accesso ai contenuti fino alla fine del ciclo di fatturazione corrente. Al termine del ciclo di fatturazione, l'accesso dovrebbe essere revocato.

L'annullamento di un abbonamento con rinnovo automatico non rateale attiva una notifica SUBSCRIPTION_CANCELED. Quando ricevi questa notifica, la risorsa abbonamento restituita dall'API Google Play Developer ha il campo subscriptionState impostato su SUBSCRIPTION_STATE_CANCELED e il campo expiryTime contiene la data in cui l'utente deve perdere l'accesso all'abbonamento. Se la data è nel passato, l'utente deve perdere immediatamente il diritto. Ciò potrebbe accadere, ad esempio, se un utente annulla un abbonamento mentre l'account è in attesa a causa di un rifiuto del pagamento.

La risorsa di abbonamento per un acquisto annullato è simile al seguente esempio:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_CANCELED",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": expiration_time,
      ...
    }
  ],
}

Per gli abbonamenti a rate, viene inviata una notifica SUBSCRIPTION_CANCELLATION_SCHEDULED in caso di annullamento avviato dall'utente quando rimangono pagamenti per il periodo di impegno. L'annullamento è in attesa e diventerà effettivo al termine del periodo di impegno corrente. Quando ricevi questa notifica, la risorsa di abbonamento restituita dall'API Google Play Developer ha il campo subscriptionState impostato su SUBSCRIPTION_STATE_ACTIVE perché l'abbonamento a rate è ancora attivo fino al termine del periodo di impegno. Tuttavia, è presente un oggetto pendingCancellation vuoto. Viene inviata una notifica SUBSCRIPTION_CANCELED seguita da una SUBSCRIPTION_EXPIRED al termine del periodo di impegno.

La risorsa di abbonamento per un acquisto di abbonamento a rate in attesa di annullamento è simile al seguente esempio:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  ...
  "lineItems": [
    {
      "productId": "sub_plan01",
      "expiryTime": expiration_time,
      "autoRenewingPlan": {
        "autoRenewEnabled": true,
        "recurringPrice": {
          "currencyCode": "USD",
          "units": "1",
          "nanos": 990000000
        },
        "installmentDetails": {
          "initialCommittedPaymentsCount": 6,
          "remainingCommittedPaymentsCount": 5,
          "pendingCancellation": {}
      ...
        }
      }
    }
  ],
}

Puoi esaminare il campo canceledStateContext nella risorsa di abbonamento per scoprire perché l'abbonamento è stato annullato (ad esempio, se l'abbonamento è stato annullato dall'utente, dal sistema o da te). Se l'abbonamento è stato annullato dall'utente, puoi esaminare il campo userInitiatedCancellation per scoprire il motivo dell'annullamento. Queste informazioni possono aiutarti a definire le strategie di comunicazione.

Quando un abbonamento viene annullato, ma non è ancora scaduto, viene comunque restituito da queryPurchasesAsync(). Potresti voler visualizzare un messaggio nella tua app per informare l'utente che il suo abbonamento è stato annullato e indicare la data di scadenza.

Revoche

Un abbonamento può essere revocato per vari motivi, tra cui la revoca dell'abbonamento da parte del backend tramite purchases.subscriptionsv2.revoke o il chargeback dell'acquisto. In questo caso, revoca immediatamente il diritto dell'utente. Quando si verifica questa situazione, viene inviato un messaggio SubscriptionNotification di tipo SUBSCRIPTION_REVOKED. Quando ricevi questa notifica, la risorsa abbonamento restituita dall'API Google Play Developer ha il campo subscriptionState impostato su SUBSCRIPTION_STATE_EXPIRED.

La risorsa di abbonamento per un acquisto revocato è simile al seguente esempio:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_EXPIRED",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": expiration_time,
      ...
    }
  ]
}

Abbonamenti differiti

Esistono diversi motivi per cui potresti voler estendere il diritto di un utente. Ad esempio, potresti voler offrire agli utenti l'accesso senza costi come promozione speciale, ad esempio una settimana senza costi per l'acquisto di un film o l'accesso senza costi ai clienti come gesto di buona volontà. Puoi utilizzare il metodo purchases.subscriptions.defer dell'API Play Developer per anticipare la prossima data di fatturazione di un abbonamento con rinnovo automatico. Quando lo fai, viene inviato un messaggio SubscriptionNotification di tipo SUBSCRIPTION_DEFERRED. Durante il periodo di differimento, l'utente è abbonato ai tuoi contenuti con accesso completo, ma non viene effettuato alcun addebito. La data di rinnovo dell'abbonamento viene aggiornata in modo da riflettere la nuova data.

Per i piani prepagati, puoi utilizzare l'API di posticipo della fatturazione per posticipare la data di scadenza.

La risorsa di abbonamento per un abbonamento posticipato è simile al seguente esempio:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": timestamp_in_future,
      ...
    }
  ],
}

Abbonamenti in pausa

Puoi ridurre il tasso di abbandono volontario consentendo agli utenti di mettere in pausa l'abbonamento. Se attivi la funzionalità di sospensione, gli utenti possono scegliere di mettere in pausa l'abbonamento per un periodo di tempo compreso tra una settimana e tre mesi, a seconda del periodo ricorrente.

La sospensione di un abbonamento ha effetto solo al termine dell'attuale periodo di fatturazione. Mentre l'abbonamento è in pausa, l'utente non ha accesso all'abbonamento e non paga il prezzo del rinnovo. Al termine del periodo di pausa, l'abbonamento riprende e Google tenta di rinnovarlo. Se la ripresa dell'abbonamento va a buon fine, l'abbonamento torna di nuovo attivo. Se la riattivazione non va a buon fine a causa di un problema di pagamento, l'utente entra nello stato di sospensione dell'account come mostrato nelle figure 5 e 6:

Un utente può anche scegliere di riattivare manualmente un abbonamento in qualsiasi momento durante il periodo di pausa, come mostrato nella figura 6. Quando un utente riattiva manualmente l'abbonamento, la data di fatturazione viene modificata in base alla data di riattivazione manuale.

Quando l'abbonamento di un utente viene messo in pausa, la libreria Play Billing non restituisce l'abbonamento tramite il metodo queryPurchasesAsync(). Se l'abbonamento viene ripristinato, il metodo queryPurchasesAsync() lo restituisce di nuovo.

Ascolta le notifiche in tempo reale per sapere quando un utente mette in pausa il suo abbonamento. Queste notifiche ti consentono anche di comunicare agli utenti della tua app che hanno sospeso l'abbonamento e non possono accedervi. Devi anche fornire un modo per consentire all'utente di riattivare manualmente l'abbonamento in qualsiasi momento utilizzando un link diretto a Google Play.

Un messaggio SubscriptionNotification di tipo SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED viene inviato quando l'utente avvia la sospensione dell'abbonamento. In questo momento, l'utente deve mantenere l'accesso al suo abbonamento fino alla successiva data di rinnovo e la risorsa abbonamento contiene autoRenewEnabled = true. Il valore del campo subscriptionState è SUBSCRIPTION_STATE_ACTIVE a questo punto.

Quando la sospensione entra in vigore, viene inviato un messaggio SubscriptionNotification di tipo SUBSCRIPTION_PAUSED. In questo caso, l'utente dovrebbe perdere l'accesso al proprio abbonamento e la risorsa di abbonamento contiene autoRenewEnabled = true, mentre il campo subscriptionState è impostato su SUBSCRIPTION_STATE_PAUSED. Puoi vedere quando è previsto il rinnovo dell'abbonamento controllando l'oggetto PausedStateContext.

Viene inviato un messaggio SubscriptionNotification di tipo SUBSCRIPTION_RENEWED se l'abbonamento viene riattivato automaticamente al termine del periodo di pausa o se l'utente ha scelto di riattivarlo manualmente. Questa operazione deve essere gestita come descritto in Rinnovi.

Viene inviato un messaggio SubscriptionNotification di tipo SUBSCRIPTION_ON_HOLD se si è verificato un errore di pagamento durante il tentativo di riattivazione dell'abbonamento dopo la pausa. Questa situazione deve essere gestita come descritto in Sospensione dell'account.

Riabbonati

Per i piani base degli abbonamenti con rinnovo automatico, il Google Play Store potrebbe mostrare un pulsante Riabbonati. Questo pulsante consente agli utenti di riacquistare l'accesso a un abbonamento. Potrebbe non essere visualizzato per vari motivi, ad esempio quando un abbonamento è scaduto molto tempo fa.

Sebbene il pulsante sia sempre etichettato Rinnova abbonamento, la sua funzionalità dipende dallo stato dell'abbonamento.

Mentre un abbonamento è annullato ma non ancora scaduto, l'utente è ancora abbonato e riceve i vantaggi dell'abbonamento. Se l'utente tocca Abbonati di nuovo, l'annullamento viene effettivamente annullato e l'abbonamento continua a rinnovarsi. Questa azione è nota come ripristino nella documentazione per gli sviluppatori e nelle API di Google Play.

Una volta scaduto un abbonamento con rinnovo automatico, puoi consentire agli utenti di acquistare lo stesso piano base dell'abbonamento. Questa azione è nota come riabbonamento nella documentazione e nelle API per sviluppatori di Google Play. Puoi configurare questa opzione per ogni piano base in Play Console o utilizzando l'API.

Ripristinare prima della scadenza

Se la tua app si basa esclusivamente sul metodo queryPurchasesAsync() per determinare se un utente ha diritto a un abbonamento, l'app deve gestire automaticamente i ripristini perché il metodo queryPurchasesAsync() continua a restituire gli acquisti annullati prima delle date di scadenza. Un abbonamento ripristinato continua a rinnovarsi come se non fosse stato annullato.

Se la tua app sincronizza lo stato dell'abbonamento con un backend, devi ascoltare un messaggio SubscriptionNotification con il tipo SUBSCRIPTION_RESTARTED. Dopo aver ricevuto questa notifica in tempo reale, la tua app può rispondere alla notifica, registrare che l'abbonamento è ora impostato per il rinnovo e interrompere la visualizzazione dei messaggi di ripristino nell'app. La risorsa di abbonamento è simile al seguente esempio:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": next_renewal_date
      ...
    }
  ],
}

Riabbonarsi dopo la scadenza

Se un piano base con rinnovo automatico è configurato utilizzando Google Play Console o l'API per consentire il riabbonamento, gli utenti possono riacquistare un abbonamento scaduto nel Google Play Store.

Si tratta di nuovi acquisti. Google Play emette un nuovo token di acquisto e il tuo backend riceve una notifica in tempo reale di tipo SUBSCRIPTION_PURCHASED. Lo stato dell'acquisto per questo tipo di acquisto esterno all'app non include un linkedPurchaseToken associato all'acquisto originale in questo caso, perché l'abbonamento originale è scaduto completamente. Si tratta di nuovi acquisti che il backend deve elaborare e riconoscere come qualsiasi altro acquisto.

Upgrade, downgrade e riattivazione dell'abbonamento

Quando un utente esegue l'upgrade, il downgrade o si abbona dopo l'annullamento dalla tua app prima della scadenza dell'abbonamento, il vecchio abbonamento viene invalidato e viene creato un nuovo abbonamento con un nuovo token di acquisto.

Inoltre, la risorsa abbonamento restituita dall'API Google Play Developer contiene un campo linkedPurchaseToken che indica il vecchio acquisto da cui l'utente ha eseguito l'upgrade, il downgrade o il rinnovo dell'abbonamento. Puoi utilizzare il token di acquisto in questo campo per cercare il vecchio abbonamento e identificare l'account utente esistente in modo da poter associare il nuovo acquisto allo stesso account.

Prima di offrire a un utente nella tua app opzioni di upgrade, downgrade o riabbonamento, devi riconoscere l'abbonamento esistente. Qualsiasi modifica del piano o riabbonamento viene bloccato se l'abbonamento esistente è ancora in attesa di conferma.

Se l'utente acquista correttamente l'upgrade, il downgrade o il rinnovo dell'abbonamento, si tratta di un nuovo acquisto che devi confermare. Il modo consigliato per farlo è utilizzare l'API Google Play Developer. La risorsa di abbonamento è simile al seguente esempio:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  "linkedPurchaseToken": old_purchase_token,
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": next_renewal_date,
      "autoRenewingPlan": {
        "autoRenewEnabled": true
      }
    }
  ],
}

Modifiche dei prezzi

Consulta la guida alle best practice per le modifiche ai prezzi per scoprire come modificare i prezzi degli abbonamenti con rinnovo automatico e come avvisare gli utenti quando è opportuno.

Quando viene aggiunta una variazione di prezzo e per qualsiasi aggiornamento dello stato della variazione di prezzo, riceverai la notifica in tempo reale SUBSCRIPTION_PRICE_CHANGE_UPDATED. Puoi eseguire query sull'endpoint purchases.subscriptionsv2.get per ottenere una risorsa di abbonamento che conterrà i dettagli della variazione di prezzo per ogni elemento dell'abbonamento.

Quando le variazioni di prezzo vengono applicate agli abbonati esistenti come attivazione, riceverai una notifica RTDN se l'utente interviene per confermare o rifiutare il nuovo prezzo.

Gestire la conferma da parte dell'utente di una modifica del prezzo per l'attivazione

Quando un utente accetta l'aumento del prezzo dell'abbonamento, ricevi un messaggio SubscriptionNotification di tipo SUBSCRIPTION_PRICE_CHANGE_UPDATED.

Gestire i rinnovi dopo l'applicazione della modifica del prezzo

In caso di riduzione del prezzo o di rinnovo dell'aumento del prezzo dell'abbonamento, riceverai un messaggio SubscriptionNotification di tipo SUBSCRIPTION_RENEWED. Considera questa notifica come qualsiasi altro rinnovo.

Gestire i casi in cui un aumento esplicito di prezzo non viene accettato

Se un utente non ha accettato l'aumento di prezzo ad attivazione prima di dover rinnovare l'abbonamento al prezzo più alto, l'abbonamento viene annullato automaticamente e ricevi un messaggio SubscriptionNotification di tipo SUBSCRIPTION_CANCELED. Gestisci questo evento come descritto in Annullamenti.

Gli utenti possono anche annullare gli abbonamenti per un aumento di prezzo con disattivazione seguendo lo stesso meccanismo.

Consenso all'aumento graduale del prezzo (applicabile solo alla regione KR)

A causa dei nuovi regolamenti della Corea del Sud, gli utenti con abbonamento nella regione devono acconsentire a eventuali aumenti di prezzo che si verificheranno dopo la fine della prova senza costi o del periodo promozionale.

Per aiutarti a rispettare il regolamento, Play invierà una notifica agli utenti nella regione della Corea del Sud in merito al requisito del consenso e memorizzerà anche la risposta al consenso degli utenti. Gli abbonamenti vengono annullati automaticamente per gli utenti che non forniscono il consenso prima che il prezzo più alto diventi effettivo. Oltre alle notifiche inviate da Google Play, puoi anche inviare notifiche personalizzate di aumento del prezzo ai tuoi utenti e fornire un link a una pagina di gestione specifica nelle notifiche.

Quando inizia il periodo di consenso o l'utente ha fornito il consenso, riceverai un messaggio SubscriptionNotification di tipo SUBSCRIPTION_PRICE_STEP_UP_CONSENT_UPDATED.

Differenza tra aumento graduale del prezzo e variazione di prezzo

Un price step-up si riferisce a un aumento del prezzo dell'abbonamento dovuto al passaggio da una fase dell'offerta a un'altra. Ad esempio, un abbonamento che passa da una prova senza costi a un prezzo normale.

Tuttavia, un price change si riferisce agli aggiornamenti dei prezzi avviati da te (sviluppatore) per il prezzo del piano base di un abbonamento. Ad esempio, aumento esplicito di prezzo o aumento tacito di prezzo.

Gestire il ciclo di vita dei piani prepagati

Come per gli abbonamenti con rinnovo automatico, devi riconoscere i piani prepagati dopo ogni nuovo acquisto. Nel caso dei piani prepagati, devi elaborare completamente sia l'acquisto iniziale sia le ricariche, perché l'utente deve seguire il flusso di acquisto ogni volta.

A causa della potenziale breve durata dei piani prepagati, è importante confermare l'acquisto il prima possibile. I piani prepagati con una durata di una settimana o più devono essere confermati entro 3 giorni. I piani prepagati con una durata inferiore a una settimana devono essere confermati entro la metà della durata del piano. Ad esempio, gli sviluppatori hanno 1,5 giorni di tempo per confermare l'acquisto di un piano prepagato di tre giorni.

Un messaggio SubscriptionNotification di tipo SUBSCRIPTION_PURCHASED viene inviato al client RTDN ogni volta che viene acquistato un abbonamento con piano prepagato, inclusa ogni ricarica. Chiama il metodo purchases.subscriptionsv2.get per verificare lo stato più recente dell'abbonamento al piano prepagato.

Per gli acquisti di ricarica viene emesso un nuovo token di acquisto e ricevi il token di acquisto precedente nel campo linkedPurchaseToken nell'ambito del nuovo stato di acquisto dell'abbonamento. Il token di acquisto è valido dalla registrazione dell'abbonamento fino a 60 giorni dopo la scadenza. Dopo questa data, il token di acquisto non è più valido per chiamare l'API Google Play Developer.

La risorsa di abbonamento per l'acquisto di un piano prepagato è simile all'esempio seguente:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  "startTime": "2022-04-22T18:39:58.270Z",
  "regionCode": "US",
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  "latestOrderId": "GPA.3333-4137-0319-36762",
  "acknowledgementState": "ACKNOWLEDGEMENT_STATE_ACKNOWLEDGED",
  "lineItems": [
    {
      "productId": "prepaid_plan01",
      "expiryTime": expiry_date,
      "prepaidPlan": {
        "allowExtendAfterTime": timestamp_after_which_topups_are_allowed
      }
    }
  ]
}

Puoi vedere quando termina il diritto nel campo expiryTime. Gli acquisti di ricariche aumentano il tempo di idoneità accumulandolo. Ciò significa che se l'utente effettua una ricarica prima della scadenza del diritto originale, il nuovo periodo viene aggiunto alla data di scadenza precedente.

Potresti voler mostrare un messaggio nella tua app per informare l'utente che i suoi abbonamenti prepagati possono essere estesi con una ricarica. Per sapere quando un utente potrà ricaricare, controlla il campo allowExtendAfterTime nella risorsa dell'abbonamento.

I piani prepagati non si rinnovano automaticamente, quindi non possono essere annullati. Se un utente vuole annullare un piano prepagato, può lasciarlo scadere.

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 abbonamento. Per i piani prepagati, questo valore è sempre ACTIVE, PENDING o CANCELED.
• 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 subscriptionId delle versioni precedenti.