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 per 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 della procedura di integrazione sono gli stessi descritti nella guida all'integrazione di Google Play Billing, 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 un UserChoiceBillingListener per la gestione dei casi in cui l'utente sceglie la fatturazione alternativa.

L'esempio seguente mostra l'inizializzazione di un 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.

Visualizzare i prodotti disponibili

Puoi mostrare i prodotti disponibili all'utente nello stesso modo in cui avviene 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 di fatturazione scelta dall'utente come descritto nella sezione seguente.

Avviare il flusso di fatturazione scelta dall'utente

Avvia il flusso di 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 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 Google Play dell'utente è un paese che supporta la fatturazione alternativa con scelta dell'utente (ovvero un paese supportato). Se il paese Google Play dell'utente è 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 Google Play dell'utente 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 di Google Play dell'utente è un paese supportato

Il paese Play dell'utente non è un paese supportato

enableUserChoiceBilling chiamato durante la configurazione di BillingClient

L'utente vede l'esperienza utente della scelta degli utenti

L'utente vede l'esperienza utente standard del sistema di fatturazione di Google Play

enableUserChoiceBilling non chiamato durante la configurazione di BillingClient

L'utente vede l'esperienza utente standard del sistema di fatturazione di Google Play

L'utente vede l'esperienza utente standard del sistema di fatturazione di Google Play

Gestire la selezione degli utenti

Il modo in cui gestisci il 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 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 di fatturazione alternativa. Utilizza questo token per segnalare qualsiasi transazione risultante da questa scelta come spiegato nella guida all'integrazione del backend.

UserChoiceBillingListener deve eseguire le seguenti azioni:

  • Recupera 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 di transazione esterna e inviala al backend per salvarla. 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 externalTransactionToken e ulteriori dettagli sulla 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.
    }
};

Quando 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.
  • Consulta la sezione Nuovi abbonamenti nella guida alla gestione degli abbonamenti per ulteriori indicazioni sugli acquisti di abbonamenti.

Gestire le modifiche all'abbonamento

Per gli sviluppatori che utilizzano la fatturazione alternativa con la 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 dell'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 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 allineano gli addebiti ricorrenti 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 Avvia il flusso di 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 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 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 segnalare 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 il 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 una 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 annullare l'annullamento durante questo periodo attivo. In questa guida, questa operazione è 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 segnalare i rinnovi quando scade il ciclo corrente e si verifica il 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 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 annullare l'annullamento mentre l'abbonamento è attivo tramite la funzionalità Rinnova abbonamento 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 hanno 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 di confermare il riacquisto dell'abbonamento tramite Google Play, ma non è necessario ripetere il flusso di scelta dell'utente. In questo caso, per l'utente viene emesso un nuovo token di acquisto. 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 annullato.

Rinnovi degli abbonamenti

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.

La riattivazione dell'abbonamento può essere abilitata anche tramite l'app, elaborandola in modo simile a una registrazione standard. Gli utenti devono poter scegliere il sistema di fatturazione che vogliono utilizzare. launchBillingFlow() può essere chiamato in questo caso, come descritto in Avviare il flusso di 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 di test 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.