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 scelta dell'utente nella tua app.

Configurazione della Libreria Fatturazione Play

Aggiungi la dipendenza Libreria Fatturazione Play alla tua app per Android. Per utilizzare le API per la 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.

Connessione a Google Play

I primi passaggi della procedura di integrazione sono uguali a quelli descritti nella guida all'integrazione di Fatturazione Google Play, con alcune modifiche durante l'inizializzazione di BillingClient:

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

L'esempio seguente mostra l'inizializzazione di BillingClient con queste modifiche:

Kotlin

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

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

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

Java

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.

Mostrare i prodotti disponibili

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

Avviare il flusso della fatturazione scelta dall'utente

Avvia il flusso della fatturazione scelta dall'utente chiamando launchBillingFlow(). Questa operazione funziona come l'avvio di un flusso di acquisto con un'integrazione del sistema di fatturazione di Google Play: fornisci un'istanza ProductDetails e un elemento offerToken corrispondente al prodotto e all'offerta che l'utente vuole acquistare. 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 impostato dall'utente è un paese che supporta la fatturazione alternativa con scelta dell'utente (ovvero un paese supportato). Se il paese impostato dall'utente in Google Play è supportato, Google Play verifica se la fatturazione alternativa è stata attivata in base alla configurazione di BillingClient.
    • Se è stata attivata la fatturazione alternativa con scelta dell'utente, il flusso di acquisto mostra l'esperienza utente di scelta dell'utente.
    • Se la fatturazione alternativa con scelta dell'utente non è attivata, il flusso di acquisto mostra l'esperienza utente standard del sistema di fatturazione di Google Play, senza scelta dell'utente.
  • Se il paese impostato dall'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.

Il paese dell'utente in Play è un paese supportato

Il paese dell'utente in Play non è un paese supportato

Metodo enableUserChoiceBilling chiamato durante la configurazione di BillingClient

L'utente vede la UX di scelta dell'utente

L'utente vede la UX standard del sistema di fatturazione di Google Play

Metodo enableUserChoiceBilling non chiamato durante la configurazione di BillingClient

L'utente vede la UX standard del sistema di fatturazione di Google Play

L'utente vede la UX standard del sistema di fatturazione di Google Play

Gestire la selezione effettuata dall'utente

Il modo in cui gestisci il resto del flusso di acquisto varia a seconda del fatto che l'utente abbia selezionato il sistema di fatturazione di Google Play o un sistema di fatturazione alternativo.

Se 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 del sistema di fatturazione alternativo. In particolare, viene chiamato il metodo userSelectedAlternativeBilling().

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

UserChoiceBillingListener deve eseguire le seguenti azioni:

  • Recuperare il prodotto o i prodotti acquistati dall'utente in modo che possano essere presentati nel flusso di acquisto del sistema di fatturazione alternativo.
  • Raccogliere la stringa ricevuta come token di transazione esterno e inviarla al backend per mantenerla. Viene utilizzata in un secondo momento per registrare la transazione esterna su Google Play se l'utente completa questo acquisto specifico.
  • Avviare il flusso di acquisto alternativo dello sviluppatore.

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

L'esempio seguente mostra come implementare UserChoiceBillingListener:

Kotlin

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.
    }

Java

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.
    }
};

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

Se l'utente sceglie il sistema di fatturazione di Google Play, continua con l'acquisto tramite Google Play.

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

Gestire le modifiche agli abbonamenti

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 registrati con 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 all'abbonamento.

Flussi di upgrade e downgrade

Le modifiche ai piani di abbonamento, inclusi i flussi di upgrade e downgrade, devono essere gestite in modo diverso a seconda del fatto che l'abbonamento sia stato acquistato originariamente 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 gli addebiti ricorrenti di allineamento vengono gestiti come upgrade. Per gli altri componenti aggiuntivi, gli utenti devono poter scegliere il sistema di fatturazione che vogliono utilizzare. Avvia una nuova esperienza di acquisto utilizzando launchBillingFlow(), come descritto in Avviare il flusso della fatturazione scelta 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 di scelta dell'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 dell'acquisto originale. In questo modo, 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 esterno per la transazione che puoi recuperare dal callback.

Kotlin

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

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

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

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

Java

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

BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(
            ImmutableList.of(
                ProductDetailsParams.newBuilder()
                    // Fetched using 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 registrare una nuova transazione utilizzando il token di transazione esterno ottenuto tramite la chiamata precedente per il nuovo acquisto dell'abbonamento.

Abbonamenti acquistati tramite il sistema di fatturazione di Google Play

Allo stesso modo, agli utenti che hanno acquistato l'abbonamento attuale tramite il sistema di fatturazione di Google Play dopo la scelta dell'utente deve essere mostrato il flusso di upgrade o downgrade nel sistema di fatturazione di Google Play. Le istruzioni riportate di seguito descrivono come avviare il flusso di acquisto per un upgrade o un downgrade tramite il sistema di fatturazione di Google Play:

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

    Kotlin

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

    Java

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

  2. Invia le informazioni corrette al sistema di fatturazione di Google Play per elaborare il nuovo acquisto, incluso il token di acquisto per l'abbonamento esistente:

    Kotlin

    val billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(
            listOf(
                BillingFlowParams.ProductDetailsParams.newBuilder()
                    // Fetched using queryProductDetailsAsync
                    .setProductDetails(productDetailsNewPlan)
                    // offerIdToken can be found in
                    // ProductDetails=>SubscriptionOfferDetails.
                    .setOfferToken(offerTokenNewPlan)
                    .build()
                )
        )
        .setSubscriptionUpdateParams(
            BillingFlowParams.SubscriptionUpdateParams.newBuilder()
                // purchaseToken can be found in
                // Purchase#getPurchaseToken
                .setOldPurchaseToken(oldToken)
                .setReplaceProrationMode(BillingFlowParams.ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
                .build()
        )
        .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

    Java

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

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

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

Annullamenti e ripristini degli abbonamenti

Gli utenti devono poter annullare l'abbonamento in qualsiasi momento. Quando un utente annulla un abbonamento, la cessazione del diritto può essere posticipata fino al termine del periodo a pagamento. Ad esempio, se un utente annulla un abbonamento mensile a metà mese, potrebbe continuare ad accedere al servizio per le circa 2 settimane rimanenti 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 cancellare l'annullamento durante questo periodo attivo. In questa guida, questa cancellazione è chiamata ripristino. Le sezioni seguenti descrivono come gestire gli scenari di ripristino nell'integrazione dell'API di fatturazione alternativa.

Abbonamenti acquistati tramite un sistema di fatturazione alternativo

Se hai 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 il proprio abbonamento mentre è ancora nel periodo attivo di un abbonamento annullato, in quel momento non si verifica alcuna transazione; puoi continuare a registrare i rinnovi quando scade il ciclo corrente e inizia il ciclo di 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 con l'abbonamento).

Abbonamenti acquistati tramite il sistema di fatturazione di Google Play

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

Puoi anche attivare un ripristino nel sistema di fatturazione di Google Play dall'app chiamando launchBillingFlow(). Per una spiegazione su come fare, consulta la sezione Prima della scadenza dell'abbonamento - in-app. Nel caso di utenti che avevano completato 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 il ripristino di questi acquisti. Viene chiesto loro di confermare il riacquisto dell'abbonamento tramite Google Play, ma non devono ripetere il flusso 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 dell'acquisto viene impostato come nel caso di un upgrade o downgrade, con il vecchio token di acquisto per l'abbonamento che era stato annullato.

Riabbonamenti

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

Il riabbonamento può essere abilitato anche tramite l'app, elaborandolo in modo simile a una registrazione standard. Gli utenti devono poter scegliere il sistema di fatturazione che vogliono utilizzare. In questo caso, è possibile chiamare launchBillingFlow(), come descritto in Avviare il flusso della fatturazione scelta dall'utente.

Testare la fatturazione alternativa

I tester delle licenze devono essere utilizzati per testare l'integrazione della fatturazione alternativa. Non riceverai fatture per le transazioni avviate dagli account dei tester delle licenze. Per ulteriori informazioni sulla configurazione dei tester delle licenze, consulta Testare la fatturazione in-app con le licenze dell'applicazione.

Passaggi successivi

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