Ciclo di vita dell'abbonamento

Gli acquisti di abbonamenti possono attraversare 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 dello sviluppatore.

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 tuo backend, chiama l'API purchases.subscriptionsv2.get con il token di acquisto incluso nella notifica. Questo endpoint fornisce lo stato più recente dell'abbonamento in base a 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. Indipendentemente dal fatto che tu riceva questa notifica o registri un nuovo acquisto in-app tramite PurchasesUpdatedListener o recuperi 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 dell'abbonamento se gli identificatori sono stati impostati al momento dell'acquisto utilizzando setObfuscatedAccountId e setObfuscatedProfileId.

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

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 con rinnovo automatico senza rateizzazione, viene inviata una SUBSCRIPTION_RENEWED notifica al momento del rinnovo. Per gli abbonamenti con pagamento rateizzato, viene inviata una notifica SUBSCRIPTION_RENEWED ogni volta che viene addebitato l'abbonamento alla relativa 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 subscription restituita dall'API Google Play Developer. La risorsa dell'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 dell'abbonamento.

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 po' 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 diritto di abbonamento.

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

La sincronizzazione dello stato dell'abbonamento con il tuo backend ti consente di essere più consapevole dei rifiuti di pagamento e ti offre più contesto quando cerchi di ridurre il tasso di abbandono 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 è in un periodo di tolleranza, la risorsa dell'abbonamento contiene autoRenewEnabled = true. Google Play estende dinamicamente il valore expiryTime fino alla scadenza del periodo di tolleranza perché il diritto deve durare fino all'annullamento da parte dell'utente o fino alla durata massima del periodo di tolleranza. Il valore del campo subscriptionState durante questo periodo è SUBSCRIPTION_STATE_IN_GRACE_PERIOD. La risorsa dell'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
      }
    }
  ],
}

Google Play informa gli utenti 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 l'errore sia stato 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 Google Play in uno snackbar temporaneo che lo informa 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 viene rinnovato 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 sequenza temporale di un abbonamento che entra in un periodo di tolleranza e poi viene recuperato quando l'utente corregge il metodo di pagamento. Al termine del periodo di tolleranza, l'utente dovrebbe perdere i vantaggi dell'abbonamento e l'account verrà sospeso.

È importante ricordare quanto segue:

• Durante un periodo di tolleranza, l'utente dovrebbe 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 questo periodo avranno accesso esteso ai vantaggi dell'abbonamento.
• Se riduci il periodo di tolleranza, i vantaggi dell'abbonamento degli utenti che hanno già usufruito di un periodo di tolleranza sufficientemente lungo da superare il nuovo periodo di tolleranza vengono revocati immediatamente. Ad esempio, se riduci il periodo di tolleranza da 14 giorni a 7 giorni, i vantaggi dell'abbonamento degli utenti che si trovano nei giorni 8-14 del vecchio periodo di tolleranza vengono revocati immediatamente.
• L'abbonamento rimane in uno stato attivo e non riceverai un RTDN per il periodo di tolleranza silenzioso fino al termine del 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 assicurarsi che il tempo per i tentativi di pagamento sia sufficiente. 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() al momento dell'RTDN anziché alla data di scadenza per ottenere un stato più preciso dell'abbonamento.

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

• SUBSCRIPTION_ON_HOLD (se abilitato)
• SUBSCRIPTION_CANCELED (se annullato)
• SUBSCRIPTION_EXPIRED (se scaduto)
• SUBSCRIPTION_RENEWED (se rinnovato correttamente)

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 di abbonamento.

Durante la sospensione dell'account, devi continuare a gestire eventuali annullamento, ripristini o riacquisto dei tuoi abbonamenti, se necessario, perché l'utente può apportare queste modifiche mentre l'abbonamento è in sospeso.

Le RTDN ti avvisano quando l'utente entra nel periodo di blocco dell'account, in modo da potergli comunicare il prima possibile il motivo della sospensione dell'accesso all'abbonamento. Un modo semplice per farlo è utilizzare l'API In-App Messaging. Se chiami questa API quando il tuo utente apre l'app, gli verrà mostrato un messaggio in una barra di notifica temporanea che lo informa 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.

Se gli utenti possono accedere ai contenuti in abbonamento al di fuori della tua app, potrebbero scoprire di aver perso l'accesso su piattaforme diverse. Ti consigliamo di inviare all'utente una notifica push o un'email 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, pertanto se la tua app si basa su questo metodo per mostrare 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 stato di sospensione dell'account. Chiama il metodo purchases.subscriptionsv2.get dal tuo server di backend sicuro per recuperare le informazioni sul nuovo 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 correggere il metodo di pagamento. Google Play informa gli utenti con un account in stato di blocco del rifiuto del pagamento e dovresti anche incoraggiarli a correggere il metodo di pagamento.

Dopo che l'utente ha corretto il metodo di pagamento, l'abbonamento torna attivo e devi ripristinare l'accesso ai contenuti a cui ha effettuato l'abbonamento. In questo caso, il token di acquisto è lo stesso di prima dell'inizio della sospensione dell'account perché lo stesso acquisto è in fase di recupero e ricevi un RTDN di tipo SUBSCRIPTION_RECOVERED.

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

Dopo il recupero, la Libreria Fatturazione Google Play restituisce di nuovo 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 dalla sospensione dell'account.

Ascolta un messaggio SubscriptionNotification con tipo SUBSCRIPTION_RECOVERED per ricevere una notifica quando un abbonamento viene ritrovato e l'utente deve riottenere 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 blocco dell'account, riceverai un RTDN di tipo SUBSCRIPTION_CANCELED. Per istruzioni su come gestire un annullamento, vedi Annullamenti. Quando effettui 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,
      ...
    }
  ],
}

Immediatamente dopo la notifica dell'annullamento durante la sospensione dell'account, riceverai anche un RTDN di tipo SUBSCRIPTION_EXPIRED perché l'utente non ha più diritti a pagamento e l'abbonamento è stato annullato con l'annullamento. Puoi gestire questa scadenza come faresti normalmente.

L'utente può riottenere l'accesso ricomprando lo stesso piano di abbonamento o qualsiasi altro piano che offri tramite l'app durante il periodo di blocco dell'account dal suo acquisto originale. In questo caso, viene emesso un nuovo token di acquisto e il nuovo valore viene restituito nell'ambito di un evento SUBSCRIPTION_PURCHASED che rappresenta questa nuova istanza.

Accesso e recupero dell'account in stato di sospensione

La Figura 3 mostra la sequenza temporale di un abbonamento che viene sospeso nell'account e poi recuperato quando l'utente corregge il metodo di pagamento.

Come nell'esempio precedente, la Figura 4 mostra una sequenza temporale per un abbonamento che prima entra in un periodo di tolleranza prima di essere sospeso e poi si riprende durante la sospensione.

È importante ricordare quanto segue:

• Prima che un abbonamento venga bloccato nell'account, Google Play effettua ulteriori tentativi di addebito sul metodo di pagamento per un massimo di 48 ore. L'utente mantiene i vantaggi dell'abbonamento durante questo periodo. Al termine di questo periodo di tentativi, l'abbonamento viene sospeso nell'account e l'utente dovrebbe perdere l'accesso ai vantaggi dell'abbonamento.
• L'abbonamento entra in stato di sospensione dell'account direttamente quando viene ripreso da uno stato di sospensione con una forma di pagamento non andata a buon fine.
• Quando un abbonamento viene recuperato dalla sospensione dell'account, la data di rinnovo viene reimpostata.

Scadenze

Alla scadenza di un abbonamento, l'utente dovrebbe perdere l'accesso all'abbonamento. In questo caso viene inviato un messaggio SubscriptionNotification di tipo SUBSCRIPTION_EXPIRED. Quando ricevi questa notifica, esegui una query sull'API Google Play Console per ottenere l'ultima risorsa di abbonamento. Dopo aver verificato che subscriptionState sia SUBSCRIPTION_STATE_EXPIRED, rimuovi il diritto e registra lo stato di acquisto come non valido nel backend. La risorsa dell'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 chiedere l'annullamento automatico dell'abbonamento se non si riprende dopo essere stato in sospensione dell'account. Gli sviluppatori possono anche attivare un'operazione di annullamento con purchases.subscriptions.cancel. Quando un abbonamento viene annullato, l'utente mantiene l'accesso ai contenuti fino al termine del ciclo di fatturazione corrente. Al termine del ciclo di fatturazione, l'accesso dovrebbe essere revocato.

L'annullamento di un abbonamento con rinnovo automatico senza rate comporta l'invio di una notificaSUBSCRIPTION_CANCELED. Quando ricevi questa notifica, la risorsa subscription 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 dovrebbe perdere l'accesso all'abbonamento. Se la data è nel passato, l'utente dovrebbe perdere immediatamente il diritto. Ciò potrebbe accadere, ad esempio, se un utente annulla un abbonamento mentre è in sospensione a causa del rifiuto di un pagamento.

La risorsa dell'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 in corso. Quando ricevi questa notifica, la risorsa subscription restituita dall'API Google Play Console ha il campo subscriptionState impostato su SUBSCRIPTION_STATE_ACTIVE perché l'abbonamento a rate è ancora attivo fino alla fine del periodo di impegno. Tuttavia, è presente un oggetto pendingCancellation vuoto. Viene inviata una notifica SUBSCRIPTION_CANCELED seguita da un messaggio SUBSCRIPTION_EXPIRED al termine del periodo di impegno.

La risorsa abbonamento per un acquisto di un 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 dell'abbonamento per scoprire perché l'abbonamento è stato annullato (ad esempio, se è 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. Questo può aiutarti a definire le strategie di comunicazione.

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

Revozioni

Un abbonamento può essere revocato per diversi motivi, ad esempio se il tuo backend revoca l'abbonamento utilizzando purchases.subscriptionsv2.revoke o se viene eseguito lo storno di addebito dell'acquisto. In questo caso, revoca immediatamente il diritto dell'utente. In questo caso viene inviato un messaggio SubscriptionNotification di tipo SUBSCRIPTION_REVOKED. Quando ricevi questa notifica, la risorsa dell'abbonamento restaurata dall'API Google Play Developer ha il campo subscriptionState impostato su SUBSCRIPTION_STATE_EXPIRED.

La risorsa dell'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 offrire agli utenti l'accesso senza costi come promozione speciale, ad esempio una settimana senza costi con 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. In questo modo, viene inviato un messaggio SubscriptionNotification con tipo SUBSCRIPTION_DEFERRED. Durante il periodo di differimento, l'utente ha un abbonamento ai tuoi contenuti con accesso completo, ma non gli viene addebitato alcun importo. La data di rinnovo dell'abbonamento viene aggiornata alla nuova data.

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

La risorsa subscription per un abbonamento differito è 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 di 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 ripresa non va a buon fine a causa di un problema di pagamento, l'utente entra nello stato di blocco dell'account come mostrato nelle figure 5 e 6:

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

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

Monitora gli RTDN per sapere quando un utente mette in pausa l'abbonamento. Queste notifiche ti consentono inoltre di informare gli utenti nella tua app che hanno messo in pausa l'abbonamento e che non hanno accesso. Devi anche fornire un modo per consentire all'utente di riprendere manualmente l'abbonamento in qualsiasi momento utilizzando un link diretto a Google Play.

Quando l'utente avvia la sospensione del proprio abbonamento, viene inviato un messaggio SubscriptionNotification con tipo SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED. A questo punto, l'utente dovrebbe mantenere l'accesso al suo abbonamento fino alla data di rinnovo successiva e la risorsa abbonamento dovrebbe contenere autoRenewEnabled = true. A questo punto, il valore del campo subscriptionState è SUBSCRIPTION_STATE_ACTIVE.

Quando la messa in pausa viene attivata, viene inviato un messaggio SubscriptionNotification di tipo SUBSCRIPTION_PAUSED. In questo caso, l'utente dovrebbe perdere l'accesso al suo abbonamento, la risorsa dell'abbonamento deve contenere autoRenewEnabled = true e il campo subscriptionState deve essere impostato su SUBSCRIPTION_STATE_PAUSED. Puoi vedere quando si prevede che l'abbonamento si rinnovi di nuovo controllando l'oggetto PausedStateContext.

Viene inviato un messaggio SubscriptionNotification di tipo SUBSCRIPTION_RENEWED se l'abbonamento viene ripreso automaticamente al termine del periodo di pausa o se l'utente ha scelto di riprendere manualmente l'abbonamento. Questo problema deve essere gestito come descritto nella sezione Rinnovi.

Viene inviato un messaggio SubscriptionNotification di tipo SUBSCRIPTION_ON_HOLD se si è verificato un errore di pagamento durante il tentativo di riprendere l'abbonamento dopo la sospensione. Questo problema deve essere gestito come descritto nella sezione Trattenimento 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 riottenere l'accesso a un abbonamento. Potrebbe non essere visualizzata per vari motivi, ad esempio quando un abbonamento è scaduto molto tempo fa.

Anche se il pulsante è sempre etichettato come Riabbonati, la sua funzionalità dipende stato dell'abbonamento.

Se un abbonamento è annullato, ma non è ancora scaduto, l'utente è ancora abbonato e riceve i relativi vantaggi. Se l'utente tocca Riabbonati, l'annullamento viene annullato e l'abbonamento continua a rinnovarsi. Questa azione è nota come ripristino nelle API e nella documentazione per gli sviluppatori 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 riabbonati nelle API e nella documentazione per gli sviluppatori Google Play. Puoi configurare questa opzione per ogni piano base in Play Console o utilizzando l'API.

Ripristino prima della scadenza

Se la tua app si basa esclusivamente sul metodo queryPurchasesAsync() per determinare se un utente ha diritto a un abbonamento, deve gestire automaticamente i ripristini perché il metodo queryPurchasesAsync() continua a restituire gli acquisti annullati prima delle relative 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 questo RTDN, 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 dell'abbonamento è simile all'esempio seguente:

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

Abbonarsi di nuovo dopo la scadenza

Se un piano base con rinnovo automatico è configurato utilizzando l'API o Google Play Console per consentire la funzionalità Riabbonati, 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 un RTDN di tipo SUBSCRIPTION_PURCHASED. In questo caso, lo stato di acquisto per questo tipo di acquisto fuori dall'app non include un linkedPurchaseToken associato all'acquisto originale, perché l'abbonamento originale è scaduto completamente. Si tratta di nuovi acquisti che il tuo backend deve elaborare e confermare come qualsiasi altro acquisto.

Upgrade, downgrade e abbonamento di nuovo

Quando un utente esegue l'upgrade, il downgrade o si iscrive dopo l'annullamento della 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 subscription 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 si è abbonato di nuovo. Puoi utilizzare il token di acquisto in questo campo per cercare l'abbonamento precedente e identificare l'account utente esistente in modo da associare il nuovo acquisto allo stesso account.

Prima di offrire a un utente della tua app opzioni di upgrade, downgrade o abbonamento di nuovo, devi confermare l'abbonamento esistente. Qualsiasi modifica del piano o abbonamento nuovo viene bloccata se l'abbonamento esistente è ancora in attesa di conferma.

Se l'utente acquista correttamente l'upgrade, il downgrade o l'abbonamento di nuovo, si tratta di un nuovo acquisto che devi confermare. Il modo consigliato per farlo è utilizzare l'API Google Play Developer. La risorsa dell'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 inviare notifiche agli utenti, se opportuno.

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

Gestire la conferma dell'utente di una variazione di prezzo per l'attivazione

Quando un utente accetta l'aumento del prezzo dell'abbonamento, ricevi un messaggio SubscriptionNotification di tipo SUBSCRIPTION_PRICE_CHANGED_CONFIRMED. In caso di diminuzione del prezzo per la disattivazione o quando si rinnova l'aumento del prezzo dell'abbonamento, ricevi un messaggio SubscriptionNotification di tipo SUBSCRIPTION_RENEWED. Tratta questa notifica come qualsiasi altro rinnovo.

Gestire i casi in cui un aumento di prezzo esplicito 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 in caso di aumento di prezzo con disattivazione seguendo lo stesso meccanismo.

Gestire il ciclo di vita dei piani prepagati

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

A causa della potenziale durata breve dei piani prepagati, è importante confermare l'acquisto il prima possibile. I piani prepagati con una durata di almeno una settimana 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 con tipo SUBSCRIPTION_PURCHASED viene inviato al client RTDN ogni volta che viene acquistato un abbonamento a un piano prepagato, inclusa ogni ricarica. Chiama il metodo purchases.subscriptionsv2.get per controllare lo stato più recente dell'abbonamento al piano prepagato.

Viene emesso un nuovo token di acquisto per gli acquisti di ricarica 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 Console.

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

{
  "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 ricarica aumentano il tempo del diritto accumulandolo. Ciò significa che se l'utente effettua un ricarica prima della scadenza del diritto originale, il nuovo periodo di tempo viene aggiunto alla data di scadenza precedente.

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

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