Abbonamento con componenti aggiuntivi

L'abbonamento con componenti aggiuntivi ti consente di raggruppare più prodotti in abbonamento che possono essere acquistati, fatturati e gestiti insieme. Gli abbonamenti al catalogo prodotti esistenti possono essere offerti senza problemi come componenti aggiuntivi senza alcuna specifica iniziale o configurazione aggiuntiva. Puoi avviare un flusso di acquisto con più prodotti in abbonamento esistenti e venderli come componenti aggiuntivi.

Considerazioni

Tieni presente quanto segue quando utilizzi la funzionalità di abbonamento con componenti aggiuntivi:

• L'abbonamento con componenti aggiuntivi è supportato solo per i piani base con rinnovo automatico.

• Tutti gli articoli dell'acquisto devono avere lo stesso periodo di fatturazione ricorrente. Ad esempio, non puoi avere un abbonamento con fatturazione annuale con componenti aggiuntivi con fatturazione mensile.

• Puoi avere un massimo di 50 elementi in un abbonamento con acquisto di componenti aggiuntivi.

• Questa funzionalità non è disponibile nelle regioni India (IN) e Corea del Sud (KR).

Integrare la Libreria Fatturazione Play

Questa sezione descrive come integrare la funzionalità di abbonamento con componenti aggiuntivi con la libreria Play Billing Library (PBL). Presuppone che tu abbia familiarità con i passaggi iniziali di integrazione della Libreria Fatturazione Play, ad esempio l'aggiunta della dipendenza della Libreria Fatturazione Play alla tua app, l'inizializzazione di BillingClient e la connessione a Google Play. Questa sezione si concentra sugli aspetti dell'integrazione di PBL specifici per gli abbonamenti con componenti aggiuntivi.

Avviare un flusso di acquisto

Per avviare un flusso di acquisto per un abbonamento con componenti aggiuntivi, segui questi passaggi:

1. Recupera tutti gli elementi dell'abbonamento utilizzando il metodo BillingClient.queryProductDetailsAsync.

2. Imposta l'oggetto ProductDetailsParams per ogni elemento.

   L'elemento rappresentato dall'oggetto ProductDetailsParams specifica sia ProductDetails che indica l'elemento dell'abbonamento, sia un offerToken che seleziona un abbonamento specifico base plan o offer.

3. Specifica i dettagli dell'articolo nel metodo BillingFlowParams.Builder.setProductDetailsParamsList. La classe BillingFlowParams specifica i dettagli di un flusso di acquisto.

   Il seguente esempio mostra come avviare il flusso di fatturazione per l'acquisto di un abbonamento con più articoli:

   Java

      BillingClient billingClient = …;
   
       // ProductDetails obtained from queryProductDetailsAsync().
       ProductDetailsParams productDetails1 = ...;
       ProductDetailsParams productDetails2 = ...;
       ArrayList productDetailsList = new ArrayList<>();
       productDetailsList.add(productDetails1);
       productDetailsList.add(productDetails2);
   
       BillingFlowParams billingFlowParams =
           BillingFlowParams.newBuilder()
              .setProductDetailsParamsList(productDetailsList)
              .build();
       billingClient.launchBillingFlow(billingFlowParams);

Regole applicabili agli articoli nell'acquisto

• Per garantire che le date di rinnovo dei componenti aggiuntivi siano allineate all'elemento di base, Google Play potrebbe inserire un addebito proporzionale dopo le fasi di prova o di prezzo di lancio.
• L'idoneità all'offerta verrà valutata separatamente per ogni articolo.

Elaborare gli acquisti

L'elaborazione dell'abbonamento con componenti aggiuntivi è uguale all'elaborazione degli acquisti di un singolo articolo, come descritto in Integrare la Libreria Fatturazione Google Play nella tua app. L'unica differenza è che l'utente può ricevere più diritti con un singolo acquisto. Un acquisto di abbonamento con componenti aggiuntivi restituisce più elementi che possono essere recuperati utilizzando Purchase.getProducts() nella libreria Fatturazione Google Play e poi l'elenco lineItems in purchases.subscriptionsv2.get dell'API Google Play Developer.

Modificare gli abbonamenti con componenti aggiuntivi

Qualsiasi modifica al tuo abbonamento con componenti aggiuntivi comporta un upgrade o un downgrade. Per ulteriori informazioni, consulta la sezione Eseguire l'upgrade o il downgrade degli abbonamenti.

Per modificare o ripristinare un acquisto esistente di un abbonamento con componenti aggiuntivi nella tua app, devi chiamare l'API launchBillingFlow con parametri aggiuntivi e assicurarti che:

• Chiama sempre setOldPurchaseToken con il token di acquisto dell'acquisto dell'abbonamento attuale.
• Per eseguire l'upgrade, il downgrade o il crossgrade di un articolo, chiama il numero SubscriptionProductReplacementParams.setReplacementMode per specificare come deve essere gestita la modifica del piano tra l'articolo di acquisto precedente e quello nuovo. In caso contrario, non è necessario impostare questo parametro.
• Quando l'elemento di base non viene modificato, puoi comunque chiamare SubscriptionProductReplacementParams.setSubscriptionReplacementMode per applicare un comportamento di sostituzione specifico. Per le regole applicabili in questo caso, consulta Rinnovo dell'abbonamento o cambio di piano all'interno dello stesso abbonamento.
• I nuovi componenti aggiuntivi verranno applicati immediatamente con un addebito proporzionale per allineare la data di rinnovo successiva all'elemento base dell'abbonamento.
• I componenti aggiuntivi rimossi scadranno al termine dei periodi di fatturazione correnti.
• Quando avvii il flusso di fatturazione, devi specificare tutti gli elementi attivi nell'abbonamento con componenti aggiuntivi, esclusi quelli da rimuovere, insieme a eventuali nuovi componenti aggiuntivi.

L'esempio seguente mostra come chiamare l'API launchBillingFlow quando si modifica un acquisto esistente di un abbonamento con componenti aggiuntivi:

BillingClient billingClient = …;

int replacementMode =…;

// ProductDetails obtained from queryProductDetailsAsync().
ProductDetailsParams productDetails1 = ...;
ProductDetailsParams productDetails2 = ...;
ProductDetailsParams productDetails3 = ...;

ArrayList newProductDetailsList = new ArrayList<>();
newProductDetailsList.add(productDetails1);
newProductDetailsList.add(productDetails1);
newProductDetailsList.add(productDetails1);

BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setSubscriptionUpdateParams(
          SubscriptionUpdateParams.newBuilder()
              .setOldPurchaseToken(purchaseTokenOfExistingSubscription)
              // No need to set if change does not affect the base item.
             .setSubscriptionReplacementMode(replacementMode)
             .build())
        .setProductDetailsParamsList(productDetailsList)
        .build();

billingClient.launchBillingFlow(billingFlowParams);

Scenari di modifica degli abbonamenti

La tabella seguente elenca i vari scenari di modifica dell'abbonamento con componenti aggiuntivi e il comportamento corrispondente.

Quando utilizzi SubscriptionProductReplacementParams

Quando utilizzi SubscriptionUpdateParams

Notifiche in tempo reale per lo sviluppatore

Il campo subscriptionId non viene fornito in RTDN per gli acquisti di abbonamenti con componenti aggiuntivi, che contengono più diritti per gli articoli. In alternativa, puoi utilizzare le API Play Developer per ottenere l'acquisto e visualizzare i diritti associati all'articolo.

Variazioni di prezzo per gli abbonati esistenti

La modifica dei prezzi degli abbonamenti per gli abbonati esistenti di un abbonamento con acquisto di componenti aggiuntivi è simile alla modifica dei prezzi degli abbonamenti con un solo articolo, come descritto in Modificare i prezzi degli abbonamenti. Tuttavia, esistono alcune limitazioni e differenze funzionali, come descritto in questa sezione.

Terminare una coorte di prezzi precedenti

La fine di una coorte precedente influisce anche sugli abbonamenti con acquisti di componenti aggiuntivi. Si applicano le seguenti regole:

• Tutti gli aumenti taciti di prezzo in sospeso devono avere lo stesso periodo di rinnovo con il nuovo prezzo. Se un articolo in un acquisto di abbonamento con componenti aggiuntivi ha un aumento di prezzo con attivazione non ancora confermato dall'utente, qualsiasi nuovo aumento di prezzo con attivazione per altri articoli nell'acquisto verrà ignorato a meno che non comporti lo stesso tempo di rinnovo dell'applicazione del nuovo prezzo dell'aumento di prezzo esistente nello stato IN ATTESA. Una volta che l'utente conferma l'aumento di prezzo, vengono registrate le eventuali modifiche di prezzo più recenti. Inoltre, gli utenti possono accettare tutti gli aumenti espliciti di prezzo non confermati contemporaneamente.

  Esempio:

  • Prendi in considerazione un abbonamento con componenti aggiuntivi (articoli A e B), che si rinnova il 7 di ogni mese.
  • L'articolo A è in fase di migrazione del prezzo da 7 $a 10 $e l'aumento di prezzo dovrebbe essere applicabile il 7 luglio.
  • Una nuova migrazione del prezzo da 5 $a 6 $inizia per l'articolo B il 2 giugno. Poiché l'aumento di prezzo con attivazione inizia 37 giorni dopo la migrazione, l'aumento di prezzo più rapido per l'articolo B sarà il 7 agosto.

  In questo scenario, finché l'utente non accetta la variazione di prezzo per l'articolo A (finché non è nello stato CONFERMATO), la variazione di prezzo per l'articolo B non viene registrata per questo acquisto di abbonamento e SubscriptionPurchaseV2 non restituisce i dettagli della variazione di prezzo per l'articolo B. Dopo che l'utente conferma la modifica del prezzo dell'articolo A, inizia la modifica del prezzo dell'articolo B. L'utente riceve l'aumento esplicito di prezzo per l'articolo B solo dopo aver accettato l'aumento esplicito per l'articolo A.

• L'email di Google Play contiene un elenco di tutti gli articoli con aumenti o riduzioni di prezzo che entrano in vigore lo stesso giorno.

Annulla l'abbonamento con componenti aggiuntivi

Gli utenti possono annullare l'intero acquisto di un abbonamento con componenti aggiuntivi nel Centro abbonamenti Google Play e tu puoi annullare l'intero acquisto di un abbonamento con componenti aggiuntivi solo utilizzando l'API Google Play Developer.

Quando un acquisto di abbonamento viene annullato senza essere revocato, nessuno degli articoli nell'acquisto verrà rinnovato automaticamente, ma l'utente continuerà ad avere accesso agli articoli a cui ha diritto fino al termine dei periodi di fatturazione corrispondenti.

Revocare e rimborsare abbonamenti con componenti aggiuntivi

Di seguito sono riportate alcune linee guida per la revoca e il rimborso degli abbonamenti:

• Utilizza Play Console per emettere un rimborso basato su un importo per un ordine specifico senza revocare l'accesso all'abbonamento.

• Chiama il numero orders.refund per rimborsare completamente i pagamenti di abbonamenti specifici effettuati dall'utente senza revocare l'accesso all'abbonamento.

• Chiama il numero purchases.subscriptionsv2.revoke per revocare immediatamente l'accesso a tutti gli elementi dell'abbonamento. Con questa API puoi:

  • Revocare l'accesso a tutti gli articoli e fornire un rimborso proporzionale.

  • Quando revochi un abbonamento con componenti aggiuntivi utilizzando rimborsi proporzionali, verrà emesso un rimborso per l'ultimo ordine di ogni articolo con un importo proporzionale in base al tempo rimanente fino al successivo rinnovo.

  • Revoca l'accesso per tutti gli articoli e fornisci un FullRefund.

  • Revoca l'accesso al singolo articolo con rimborso totale dell'articolo.

Revocare un singolo elemento in un abbonamento con componenti aggiuntivi

Per revocare singoli elementi di abbonamento in un abbonamento con componenti aggiuntivi senza revocare l'intero acquisto, chiama purchases.subscriptionsv2.revoke con il campo ItemBasedRefund impostato in RevocationContext. Il productId dell'articolo da revocare e rimborsare può essere impostato nel campo ItemBasedRefund.

Il campo ItemBasedRefund può essere impostato per gli acquisti con uno o più elementi di abbonamento con rinnovo automatico.

• Se nell'acquisto dell'abbonamento rimangono ancora articoli attivi dopo la revoca dell'articolo specificato in ItemBasedRefund, solo l'articolo verrà revocato e rimborsato integralmente senza interrompere lo stato dell'abbonamento.
• Se non rimangono articoli attivi nell'acquisto dell'abbonamento dopo la revoca dell'articolo specificato in ItemBasedRefund, l'articolo viene revocato, rimborsato completamente e l'abbonamento viene annullato.

Considerazioni

• Quando utilizzi ItemBasedRefund, puoi revocare un solo elemento alla volta. La richiesta può essere chiamata più volte se è necessario revocare elementi diversi.
• Quando l'acquisto dell'abbonamento si trova in uno degli stati di pagamento rifiutato oppure l'articolo specificato in ItemBasedRefund non è di proprietà o è scaduto, il rifiuto dell'articolo viene bloccato.
• La riduzione dell'articolo non è supportata nell'abbonamento prepagato.

Scadenza dell'articolo durante il rifiuto del pagamento

Per un acquisto di un abbonamento con componenti aggiuntivi, alcuni rinnovi potrebbero dover estendere solo un sottoinsieme di diritti sugli articoli, senza influire sugli articoli con una data di scadenza futura.

Indipendentemente dagli articoli coinvolti in un rinnovo, se il pagamento del rinnovo viene rifiutato, l'acquisto dell'abbonamento complessivo entrerà nel periodo di tolleranza e l'account verrà sospeso come descritto nella documentazione seguente.

Selezione del periodo di recupero

Poiché il periodo di tolleranza stesso concede ancora il diritto all'utente, in caso di acquisto di un abbonamento con componenti aggiuntivi, il pagamento del rinnovo viene rifiutato, l'elemento con il periodo di tolleranza minimo tra tutti gli elementi attivi viene selezionato e il suo periodo di tolleranza e il periodo di sospensione dell'account vengono applicati come periodo di recupero per questo rinnovo.

Gli elementi attivi includono quelli che erano attivi nell'acquisto di un abbonamento con componenti aggiuntivi appena prima del tentativo di rinnovo, escludono gli elementi aggiunti di recente (che non saranno idonei fino al recupero) ed escludono gli elementi che non sono più attivi a causa della rimozione o del ritiro.

Viene applicata l'impostazione di sospensione dell'account dell'elemento con il periodo di tolleranza minimo selezionato. Se sono presenti più elementi con il periodo di tolleranza minimo, ma periodi di sospensione dell'account diversi, viene applicato il periodo di sospensione dell'account più lungo.

Periodo di tolleranza

Quando un pagamento per il rinnovo di un abbonamento viene rifiutato, l'acquisto dell'abbonamento entra nello stato di periodo di tolleranza. Durante il periodo di tolleranza, l'utente continuerà ad avere accesso a tutti gli elementi attivi del periodo di rinnovo precedente. Al termine del periodo di tolleranza, se il metodo di pagamento non è stato corretto, l'intero acquisto dell'abbonamento viene sospeso. Se altri articoli raggiungono la data di rinnovo durante il periodo di tolleranza, verrà avviato un nuovo tentativo di addebito per questi articoli una volta che l'abbonamento si riprende dal rifiuto del pagamento.

Sospensione dell'account

Durante la sospensione dell'account per l'acquisto dell'abbonamento, l'accesso a tutti gli elementi dell'abbonamento viene sospeso fino al recupero del pagamento.

Se l'abbonamento in sospensione dell'account viene recuperato, l'acquisto dell'abbonamento continua a esistere così com'è. Se l'abbonamento non viene recuperato, gli articoli in rifiuto del pagamento scadranno e l'accesso agli altri articoli verrà ripristinato per il resto dei periodi di fatturazione.

Esempio:

• Un utente ha un abbonamento My Base Plan che si rinnova il 1° di ogni mese, poi il 15 agosto aggiunge un piano aggiuntivo da 10 $al mese con una prova senza costi di sette giorni. Nessuno dei due elementi ha un periodo di tolleranza impostato ed entrambi hanno un periodo di sospensione dell'account di 30 giorni.

• Il 22 agosto all'utente vengono addebitati 2,90 $ (10*9/31) per il riparto proporzionale fino al 31 agosto, ma il metodo di pagamento dell'utente scade prima e l'abbonamento viene rifiutato il 22 agosto.

Quando l'abbonamento viene sospeso a causa del rifiuto del pagamento, l'utente non ha accesso a nessuno degli elementi dell'abbonamento con componenti aggiuntivi. Il tempo rimanente per gli elementi che non vengono rinnovati verrà restituito agli utenti quando l'abbonamento esce dalla sospensione dell'account, perché il pagamento è stato recuperato o annullato.

Nell'esempio precedente, l'abbonamento entra in sospensione dell'account il 22 agosto.

• Se l'account viene recuperato il 25 agosto, prima della data di rinnovo più ampia del 1° settembre, l'utente riacquista l'accesso sia a Base Plan sia al piano aggiuntivo lo stesso giorno. La prossima data di fatturazione è stata modificata al 4 settembre.

• Se l'account non viene recuperato dopo 30 giorni, l'abbonamento viene annullato il 21 settembre e l'utente perde l'accesso al piano aggiuntivo e riprende l'accesso al piano base fino al 30 settembre.

In questo esempio, devi ottenere l'expiryTime aggiornato per TUTTI gli elementi dell'abbonamento con componenti aggiuntivi, in quanto alcuni elementi potrebbero ripristinare il proprio diritto dopo il periodo di tolleranza e la sospensione dell'account.

Report finanziari e riconciliazione

Utilizza il report Utili per riconciliare gli abbonamenti attivi con le transazioni su Play. Ogni elemento pubblicitario della transazione ha un ID ordine. Con gli acquisti che rappresentano più articoli, i report Entrate e Vendite stimate includeranno righe separate per ogni transazione, ad esempio addebito, tariffa, imposta e rimborso, per ogni articolo coinvolto.

Per le dashboard in Play Console:

• Le statistiche sulle entrate presentate nella sezione Report finanziari della console sono suddivise per articoli.

• La gestione degli ordini riflette l'acquisto dell'abbonamento con i componenti aggiuntivi e mostra elenchi dettagliati di ciò che è stato acquistato. Dalla gestione degli ordini, puoi revocare, annullare o rimborsare completamente l'acquisto di un utente.