Indicazioni sull'integrazione in-app per la fatturazione alternativa con scelta dell'utente

Questa guida descrive come integrare le API per offrire la fatturazione alternativa con la scelta dell'utente nella tua app.

Configurazione della Libreria Fatturazione Play

Aggiungi la dipendenza Libreria Fatturazione Play alla tua app Android. Per utilizzare le API di fatturazione alternativa, devi utilizzare la versione 5.2 o successive. Se devi eseguire la migrazione da una versione precedente, segui le istruzioni riportate nella guida alla migrazione prima di tentare di implementare la fatturazione alternativa.

Collegati a Google Play

I primi passaggi del processo di integrazione sono gli stessi descritti nella guida all'integrazione di Fatturazione Google Play, con alcune modifiche al momento dell'inizializzazione di BillingClient:

• Devi chiamare un nuovo metodo per indicare che vuoi offrire all'utente una scelta tra le opzioni di fatturazione: enableUserChoiceBilling.
• Devi registrare una UserChoiceBillingListener per la gestione dei casi in cui l'utente sceglie la fatturazione alternativa.

L'esempio seguente illustra l'inizializzazione di un elemento BillingClient con queste modifiche:

val purchasesUpdatedListener =
   PurchasesUpdatedListener { billingResult, purchases ->
       // Handle new Google Play purchase.
   }

val userChoiceBillingListener =
   UserChoiceBillingListener { userChoiceDetails ->
       // Handle alternative billing choice.
   }

var billingClient = BillingClient.newBuilder(context)
   .setListener(purchasesUpdatedListener)
   .enablePendingPurchases()
   .enableUserChoiceBilling(userChoiceBillingListener)
   .build()

private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
    @Override
    public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
        // Handle new Google Play purchase.
    }
};

private UserChoiceBillingListener userChoiceBillingListener = new UserChoiceBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
        UserChoiceDetails userChoiceDetails) {
        // Handle new Google Play purchase.
    }
};

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableUserChoiceBilling(userChoiceBillingListener)
    .build();

Dopo aver inizializzato BillingClient, devi stabilire una connessione a Google Play come descritto nella guida all'integrazione.

Mostra i prodotti disponibili

Puoi mostrare i prodotti disponibili all'utente come faresti con l'integrazione del sistema di fatturazione di Google Play. Quando l'utente ha visto i prodotti disponibili per l'acquisto e ne seleziona uno da acquistare, avvia il flusso di fatturazione scelta dall'utente come descritto nella sezione seguente.

Lancia il flusso di fatturazione scelta dall'utente

Avvia il flusso di fatturazione scelta dall'utente chiamando il numero launchBillingFlow(). Questa operazione funziona come l'avvio di un flusso di acquisto con un'integrazione del sistema di fatturazione di Google Play: devi fornire un'istanza ProductDetails e un offerToken corrispondente al prodotto e all'offerta che l'utente vuole acquisire. Se l'utente sceglie il sistema di fatturazione di Google Play, queste informazioni vengono utilizzate per continuare il flusso di acquisto.

Quando gli sviluppatori chiamano launchBillingFlow(), il sistema di fatturazione di Google Play esegue il seguente controllo:

• Il sistema controlla se il paese in Google Play dell'utente è un paese che supporta la fatturazione alternativa con scelta dell'utente (ovvero un paese supportato). Se il paese dell'utente in Google Play è supportato, Google Play controlla se la fatturazione alternativa è stata attivata in base alla configurazione di BillingClient.
  • Se è stata abilitata la fatturazione alternativa con scelta dell'utente, il flusso di acquisto mostra l'UX scelta dall'utente.
  • Se la fatturazione alternativa con scelta dell'utente non è abilitata, il flusso di acquisto mostra l'esperienza utente standard del sistema di fatturazione di Google Play, senza scelta dell'utente.
• Se il paese dell'utente in Google Play non è un paese supportato, il flusso di acquisto mostra l'esperienza utente standard del sistema di fatturazione di Google Play, senza scelta dell'utente.

Gestire la selezione degli utenti

La modalità di gestione del resto del flusso di acquisto varia a seconda che l'utente abbia selezionato il sistema di fatturazione di Google Play o un sistema di fatturazione alternativo.

Quando l'utente seleziona un sistema di fatturazione alternativo

Se l'utente sceglie il sistema di fatturazione alternativo, Google Play chiama UserChoiceBillingListener per comunicare all'app che deve avviare il flusso di acquisto nel sistema di fatturazione alternativo. In particolare, viene richiamato il metodo userSelectedAlternativeBilling().

Il token di transazione esterno fornito nell'oggetto UserChoiceDetails rappresenta una firma per la scelta dell'utente di accedere al flusso di fatturazione alternativa. Utilizza questo token per segnalare qualsiasi transazione derivante da questa scelta, come spiegato nella guida all'integrazione di backend.

UserChoiceBillingListener deve eseguire le seguenti azioni:

• Ottieni il prodotto o i prodotti acquistati dall'utente in modo che possano essere presentati nel flusso di acquisto nel sistema di fatturazione alternativo.
• Raccogli la stringa ricevuta come token della transazione esterna e inviala al tuo backend per mantenerla. Viene utilizzato in un secondo momento per segnalare la transazione esterna a Google Play se l'utente completa questo acquisto specifico.
• Avvia il flusso di acquisto alternativo dello sviluppatore.

Se l'utente completa l'acquisto utilizzando il sistema di fatturazione alternativo, devi segnalare la transazione a Google Play chiamando l'API Google Play Developer dal tuo backend entro 24 ore, fornendo l'externalTransactionToken e ulteriori dettagli sulla transazione. Per ulteriori dettagli, consulta la guida all'integrazione dei backend.

L'esempio seguente mostra come implementare UserChoiceBillingListener:

private val userChoiceBillingListener =
    UserChoiceBillingListener { userChoiceDetails ->
        // Get the products being purchased by the user.
        val products = userChoiceDetails.products

        // Send external transaction token to developer backend server
        // this devBackend object is for demonstration purposes,
        // developers can implement this step however best fits their
        // app to backend communication.
        devBackend.sendExternalTransactionStarted(
            userChoiceDetails.externalTransactionToken,
            user
        )

        // Launch alternative billing
        // ...
        // The developer backend handles reporting the transaction
        // to Google Play's backend once the alternative billing
        // purchase is completed.
    }

private userChoiceBillingListener userChoiceBillingListener = new UserChoiceBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
           UserChoiceDetails userChoiceDetails) {
       // Get the products being purchased by the user.
       List<Product> products =
              userChoiceDetails.getProducts();

       // Send external transaction token to developer backend server
       // this devBackend object is for demonstration purposes,
       // developers can implement this step however best fits their
       // app to backend communication.
       devBackend.sendExternalTransactionStarted(
              userChoiceDetails.getExternalTransactionToken(),
              user
       );

       // Launch alternative billing
       // ...
       // The developer backend handles reporting the transaction
       // to Google Play's backend once the alternative billing
       // purchase is completed.
    }
};

Quando l'utente seleziona il sistema di fatturazione di Google Play

Se l'utente sceglie il sistema di fatturazione di Google Play, continuerà l'acquisto tramite Google Play.

• Consulta la sezione Elaborazione degli acquisti nella guida all'integrazione delle raccolte per ulteriori informazioni su come gestire i nuovi acquisti in-app tramite il sistema di fatturazione di Google Play.
• Per ulteriori indicazioni per gli acquisti degli abbonamenti, consulta la sezione Nuovi abbonamenti nella guida alla gestione degli abbonamenti.

Gestire le modifiche all'abbonamento

Per gli sviluppatori che utilizzano la fatturazione alternativa con scelta dell'utente, gli acquisti devono essere elaborati tramite il sistema di fatturazione di Google Play o segnalati con un externalTransactionId, a seconda della scelta dell'utente. Le modifiche agli abbonamenti esistenti elaborati tramite il flusso di scelta dell'utente possono essere apportate tramite lo stesso sistema di fatturazione fino alla scadenza.

Questa sezione descrive come gestire alcuni scenari comuni di modifica degli abbonamenti.

Flussi di upgrade e downgrade

Le modifiche al piano di abbonamento, inclusi i flussi di upgrade e downgrade, devono essere gestite in modo diverso a seconda che l'abbonamento sia stato originariamente acquistato tramite il sistema di fatturazione di Google Play o tramite un sistema di fatturazione alternativo.

I componenti aggiuntivi che dipendono da un abbonamento esistente, condividono lo stesso metodo di pagamento e allineano gli addebiti ricorrenti vengono gestiti come upgrade. Per gli altri componenti aggiuntivi, gli utenti devono essere in grado di scegliere il sistema di fatturazione da utilizzare. Avvia una nuova esperienza di acquisto utilizzando launchBillingFlow(), come descritto in Avviare il flusso di fatturazione scelto dall'utente.

Abbonamenti acquistati tramite un sistema di fatturazione alternativo

Per gli abbonamenti originariamente acquistati tramite il sistema di fatturazione alternativo dello sviluppatore dopo la scelta dell'utente, gli utenti che richiedono un upgrade o un downgrade devono procedere tramite il sistema di fatturazione alternativo dello sviluppatore senza dover ripetere l'esperienza scelta dall'utente.

Per farlo, chiama launchBillingFlow() quando l'utente richiede un upgrade o un downgrade. Anziché specificare un oggetto SubscriptionUpdateParams nei parametri, utilizza setOriginalExternalTransactionId, fornendo l'ID transazione esterno per l'acquisto originale. Non viene visualizzata la schermata di scelta dell'utente, dato che la scelta dell'utente per l'acquisto originale viene mantenuta per gli upgrade e i downgrade. La chiamata a launchBillingFlow() in questo caso genera un nuovo token di transazione esterna per la transazione che puoi recuperare dal callback.

// The external transaction ID from the current
// alternative billing subscription.
val externalTransactionId = //... ;

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                // Fetched via queryProductDetailsAsync.
                .setProductDetails(productDetailsNewPlan)
                // offerIdToken can be found in
                // ProductDetails=>SubscriptionOfferDetails.
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOriginalExternalTransactionId(externalTransactionId)
            .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

// When the user selects the alternative billing flow,
// the UserChoiceBillingListener is triggered.

// The external transaction ID from the current
// alternative billing subscription.
String externalTransactionId = //... ;

BillingFlowParams billingFlowParams =
        BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(
                ImmutableList.of(
                    ProductDetailsParams.newBuilder()
                        // Fetched via queryProductDetailsAsync.
                        .setProductDetails(productDetailsNewPlan)
                        // offerIdToken can be found in
                        // ProductDetails=>SubscriptionOfferDetails
                        .setOfferToken(offerTokenNewPlan)
                    .build()
                )
            )
            .setSubscriptionUpdateParams(
                SubscriptionUpdateParams.newBuilder()
                    .setOriginalExternalTransactionId(externalTransactionId)
                    .build()
            )
            .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

// When the user selects the alternative billing flow,
// the UserChoiceBillingListener is triggered.

Una volta completato l'upgrade o il downgrade nel sistema di fatturazione alternativo, devi segnalare una nuova transazione utilizzando il token di transazione esterna ottenuto tramite la chiamata precedente per l'acquisto del nuovo abbonamento.

Abbonamenti acquistati tramite il sistema di fatturazione di Google Play

Analogamente, agli utenti che hanno acquistato il proprio abbonamento attuale tramite il sistema di fatturazione di Google Play dopo la scelta dell'utente dovrebbe essere mostrato il flusso di upgrade o downgrade nel sistema di fatturazione di Google Play. Le seguenti istruzioni descrivono come avviare il flusso di acquisto per un upgrade o un downgrade tramite il sistema di fatturazione di Google Play:

1. Identifica offerToken dell'offerta selezionata per il nuovo piano:

val offerTokenNewPlan = productDetailsNewPlan
             .getSubscriptionOfferDetails(selectedOfferIndex)
             .getOfferToken()

String offerTokenNewPlan = productDetailsNewPlan
                     .getSubscriptionOfferDetails(selectedOfferIndex)
                     .getOfferToken();

1. Invia le informazioni corrette al sistema di fatturazione di Google Play per l'elaborazione del nuovo acquisto, incluso il token di acquisto dell'abbonamento esistente:

val billingFlowParams =
    BillingFlowParams.newBuilder().setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                .setProductDetails(productDetailsNewPlan)
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOldPurchaseToken(oldToken)
            .setReplaceProrationMode(BillingFlowParams.ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
            .build()
        )
        .build()

BillingClient.launchBillingFlow(activity, billingFlowParams)

BillingFlowParams billingFlowParams =
        BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(
                ImmutableList.of(
                    ProductDetailsParams.newBuilder()
                        // Fetched via queryProductDetailsAsync
                        .setProductDetails(productDetailsNewPlan)
                        // offerIdToken can be found in
                        // ProductDetails=>SubscriptionOfferDetails.
                        .setOfferToken(offerTokenNewPlan)
                        .build()
                )
            )
            .setSubscriptionUpdateParams(
                SubscriptionUpdateParams.newBuilder()
                    // purchaseToken can be found in
                    // Purchase#getPurchaseToken
                    .setOldPurchaseToken("old_purchase_token")
                    .setReplaceProrationMode(ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
                    .build()
            )
            .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

Questo acquisto viene effettuato nel sistema di fatturazione di Google Play e la tua app riceve la chiamata PurchasesUpdatedListener.onPurchaseUpdated con il risultato dell'acquisto. Se l'acquisto va a buon fine, anche il metodo onPurchaseUpdated() riceve le nuove informazioni sull'acquisto e il backend riceve una notifica SUBSCRIPTION_PURCHASED in tempo reale per lo sviluppatore. Quando esegui il pull dello stato del nuovo acquisto, un attributo linkedPurchaseToken rimanda all'acquisto dell'abbonamento precedente in modo che tu possa ritirarlo come consigliato.

Annullamenti e ripristini degli abbonamenti

Gli utenti dovrebbero essere in grado di annullare il proprio abbonamento in qualsiasi momento. Quando un utente annulla un abbonamento, la risoluzione del diritto può essere differita fino al termine del periodo di pagamento. Ad esempio, se un utente annulla un abbonamento mensile a metà mese, può continuare ad accedere al servizio per le restanti circa 2 settimane fino alla rimozione dell'accesso. Durante questo periodo, l'abbonamento è ancora tecnicamente attivo, quindi l'utente può utilizzare il servizio.

Non è raro che gli utenti decidano di annullare la cancellazione durante questo periodo attivo. In questa guida, il processo è chiamato ripristino. Le seguenti sezioni descrivono come gestire gli scenari di ripristino nell'integrazione dell'API di fatturazione alternativa.

Abbonamenti acquistati tramite un sistema di fatturazione alternativo

Se disponi di un ID transazione esterno per un abbonamento annullato, non è necessario chiamare launchBillingFlow() per ripristinare l'abbonamento, quindi non deve essere utilizzato per questo tipo di attivazione. Se un utente ripristina l'abbonamento mentre è ancora nel periodo attivo di un abbonamento annullato, a quel punto non avverrà alcuna transazione; puoi semplicemente continuare a segnalare i rinnovi alla scadenza del ciclo corrente e al rinnovo successivo. Sono inclusi i casi in cui l'utente riceve un credito o un prezzo di rinnovo speciale nell'ambito del ripristino (ad esempio, una promozione per incoraggiare l'utente a continuare l'abbonamento).

Abbonamenti acquistati tramite il sistema di fatturazione di Google Play

In genere, gli utenti possono ripristinare gli abbonamenti sul sistema di fatturazione di Google Play. Per gli abbonamenti annullati originariamente acquistati sul sistema di fatturazione di Google Play, l'utente può scegliere di annullare l'annullamento mentre l'abbonamento è attivo tramite la funzionalità Riabbonati di Google Play. In questo caso, ricevi una notifica SUBSCRIPTION_RESTARTED in tempo reale per lo sviluppatore nel tuo backend e non viene emesso un nuovo token di acquisto, che verrà usato per proseguire l'abbonamento. Per scoprire come gestire il ripristino nel sistema di fatturazione di Google Play, consulta la sezione Ripristino nella guida alla gestione degli abbonamenti.

Puoi anche attivare un ripristino nel sistema di fatturazione di Google Play dall'app chiamando launchBillingFlow(). Per informazioni su come fare, consulta Prima della scadenza dell'abbonamento - in-app. Nel caso di utenti che hanno seguito il flusso di scelta dell'utente per l'acquisto originale (che è stato annullato, ma è ancora attivo), il sistema rileva automaticamente la loro scelta e visualizza l'interfaccia utente per ripristinare questi acquisti. Gli viene chiesto di confermare l'acquisto di un abbonamento tramite Google Play, ma non devono ripetere la procedura di scelta dell'utente. In questo caso, viene emesso un nuovo token di acquisto per l'utente. Il backend riceve una notifica in tempo reale per lo sviluppatore SUBSCRIPTION_PURCHASED e il valore linkedPurchaseToken per il nuovo stato di acquisto viene impostato come nel caso di un upgrade o un downgrade, con il token di acquisto precedente per l'abbonamento annullato.

Nuove iscrizioni

Se un abbonamento scade completamente, a causa di un annullamento o del rifiuto di un pagamento senza recupero (una sospensione dell'account scaduta), l'utente deve riabbonarsi se vuole ripristinare il diritto.

La riabbonamento può essere abilitata anche tramite l'app elaborandola in modo simile a una registrazione standard. Gli utenti devono essere in grado di scegliere il sistema di fatturazione che vogliono utilizzare. In questo caso potrebbe essere chiamato launchBillingFlow(), come descritto in Avviare il flusso di fatturazione scelta dall'utente.

Testare la fatturazione alternativa

È consigliabile utilizzare i tester delle licenze per testare l'integrazione della fatturazione alternativa. Non ti verranno fatturate le transazioni avviate dagli account tester delle licenze. Consulta Testare la fatturazione in-app con le licenze dell'applicazione per ulteriori informazioni sulla configurazione dei tester delle licenze.

Passaggi successivi

Una volta completata l'integrazione in-app, puoi integrare il tuo backend.