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 all'app per Android. Per utilizzare le API di fatturazione alternativa devi usare la versione 5.2 o successive. Per eseguire la migrazione da una versione precedente, segui le istruzioni in prima di tentare di implementare la fatturazione alternativa.
Connettersi a Google Play
I primi passaggi del processo di integrazione sono gli stessi descritti in la guida all'integrazione di Fatturazione Google Play, apportando alcune modifiche quando inizializzazione di BillingClient:
- Devi chiamare un nuovo metodo per indicare che vuoi offrire all'utente un
scelta delle opzioni di fatturazione:
enableUserChoiceBilling. - Devi registrare una
UserChoiceBillingListenerper la gestione delle richieste in cui l'utente sceglie la fatturazione alternativa.
L'esempio seguente mostra l'inizializzazione di un BillingClient con questi
modifiche:
Kotlin
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()
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 con
Google Play come descritto nella guida all'integrazione.
Mostra i prodotti disponibili
Puoi mostrare i prodotti disponibili all'utente come faresti con una Integrazione del sistema di fatturazione di Google Play. Quando l'utente ha visto i prodotti disponibile per l'acquisto e ne seleziona uno da acquistare, avvia la 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 il numero launchBillingFlow(). Funziona
equivale ad avviare un flusso di acquisto con un sistema di fatturazione di Google Play.
integrazione: fornisci un'istanza ProductDetails e un'istanza offerToken
corrispondenti 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
continua 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 (ad es. un
paese). Se il paese dell'utente in Google Play è supportato, Google Play controlla
se è stata abilitata la fatturazione alternativa in base alla configurazione
BillingClient.- Se è stata abilitata la fatturazione alternativa con la scelta dell'utente, l'acquisto che mostra l'esperienza utente scelta dall'utente.
- Se la fatturazione alternativa con la scelta dell'utente non è abilitata, l'acquisto che mostra la UX standard del sistema di fatturazione di Google Play, senza utente scelta.
- Se il paese dell'utente in Google Play non è supportato, i il flusso di acquisto mostra la UX standard del sistema di fatturazione di Google Play, senza utente scelta.
Il paese di Google Play dell'utente è supportato |
Il paese dell'utente in Google Play non è supportato |
|
|---|---|---|
EnableUserChoiceBilling è stato chiamato durante la configurazione di BillingClient |
L'utente vede l'esperienza utente scelta dall'utente |
L'utente vede l'esperienza utente standard del sistema di fatturazione di Google Play |
EnableUserChoiceBilling non viene 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 dell'utente
La modalità di gestione del resto del flusso di acquisto varia a seconda che le l'utente ha 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 notificare all'app che deve avviare l'app
flusso di acquisto nel sistema di fatturazione alternativo. In particolare,
Viene chiamato il metodo userSelectedAlternativeBilling().
Il token della transazione esterna fornito nell'oggetto UserChoiceDetails
rappresenta una firma per la scelta dell'utente di inserire la fatturazione alternativa
flusso di lavoro. Utilizza questo token per segnalare eventuali transazioni derivanti da questa scelta come
spiegata nella guida all'integrazione del backend.
UserChoiceBillingListener dovrebbe eseguire le seguenti azioni:
- Ottieni il prodotto o i prodotti acquistati dall'utente in modo che possano presentati nel flusso di acquisto nel sistema di fatturazione alternativo.
- Raccogli la stringa ricevuta come token della transazione esterna e inviala a al tuo backend per eseguirne il salvataggio. Questo viene utilizzato in seguito per segnalare il traffico esterno transazione a Google Play se l'utente completa questo acquisto specifico.
- Lancia il flusso di acquisto alternativo dello sviluppatore.
Se l'utente completa l'acquisto utilizzando il sistema di fatturazione alternativo, tu
Devi segnalare la transazione a Google Play chiamando lo sviluppatore Google Play
all'API dal backend entro 24 ore, fornendo
externalTransactionToken e dettagli aggiuntivi sulla transazione. Consulta le
guida all'integrazione del backend per ulteriori dettagli.
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 le effettuare un acquisto tramite Google Play.
- Per saperne di più, consulta Elaborazione degli acquisti nella guida all'integrazione delle raccolte informazioni su come gestire i nuovi acquisti in-app tramite il di fatturazione.
- Consulta Nuovi abbonamenti nella guida alla gestione degli abbonamenti per indicazioni aggiuntive per gli acquisti di abbonamenti.
Gestire le modifiche nell'abbonamento
Per gli sviluppatori che usano la fatturazione alternativa con scelta dell'utente, gli acquisti devono:
elaborati tramite il sistema di fatturazione di Google Play o segnalati con un
externalTransactionId, a seconda della scelta dell'utente. Modifiche a esistenti
È possibile sottoscrivere abbonamenti elaborati tramite il flusso di scelta dell'utente
attraverso 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 al piano di abbonamento, inclusi i flussi di upgrade e downgrade devono essere gestiti in modo diverso a seconda che l'abbonamento sia stato acquistato o meno in origine tramite il sistema di fatturazione di Google Play o un sistema di fatturazione alternativo.
I componenti aggiuntivi che dipendono da un abbonamento esistente, condividono lo stesso metodo di pagamento
e allineare gli addebiti ricorrenti
sono gestiti come upgrade. Per gli altri componenti aggiuntivi, gli utenti
dovrebbe essere in grado di scegliere il sistema di fatturazione da utilizzare. Avvia una nuova
esperienza di acquisto utilizzando launchBillingFlow(), come descritto nella sezione Lanciare
flusso di fatturazione scelta dall'utente.
Abbonamenti acquistati tramite un sistema di fatturazione alternativo
Per gli abbonamenti originariamente acquistati tramite la un sistema di fatturazione alternativo dopo la scelta dell'utente, gli utenti che richiedono un upgrade o il downgrade deve procedere tramite il sistema di fatturazione alternativo dello sviluppatore senza dover ripetere l'esperienza di scelta dell'utente.
A questo scopo, chiama launchBillingFlow() quando l'utente richiede un upgrade o un
eseguire il downgrade. Anziché specificare un oggetto SubscriptionUpdateParams nel tag
utilizzare i parametri setOriginalExternalTransactionId, fornendo il parametro esterno
l'ID transazione dell'acquisto originale. In questo modo non viene visualizzato
schermata di scelta, 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 della transazione esterna per la transazione che puoi
recupera 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 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.
Java
// 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 della transazione esterna ottenuti tramite la precedente chiamata per l'acquisto del nuovo abbonamento.
Abbonamenti acquistati tramite il sistema di fatturazione di Google Play
Analogamente, gli utenti che hanno acquistato il proprio abbonamento attuale tramite il di fatturazione del sistema, dopo la scelta dell'utente, deve essere visualizzato il flusso di upgrade o downgrade nel sistema di fatturazione di Google Play. Le seguenti istruzioni descrivono come avvierai il flusso di acquisto per un upgrade o un downgrade tramite Google Il sistema di fatturazione di Google Play:
- Identifica i
offerTokendell'offerta selezionata per il nuovo piano:
val offerTokenNewPlan = productDetailsNewPlan
.getSubscriptionOfferDetails(selectedOfferIndex)
.getOfferToken()
String offerTokenNewPlan = productDetailsNewPlan
.getSubscriptionOfferDetails(selectedOfferIndex)
.getOfferToken();
- Invia le informazioni corrette al sistema di fatturazione di Google Play per l'elaborazione nuovo acquisto, incluso il token di acquisto per l'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 avviene nel sistema di fatturazione di Google Play e la tua app riceve
la chiamata PurchasesUpdatedListener.onPurchaseUpdated con il risultato
acquisto. Se l'acquisto è andato a buon fine, anche il metodo onPurchaseUpdated()
riceve le informazioni sul nuovo acquisto e il backend riceve un
SUBSCRIPTION_PURCHASED Notifica in tempo reale per lo sviluppatore. Quando estrai il parametro
stato del nuovo acquisto, un attributo linkedPurchaseToken si collega al vecchio
abbonamento acquistato per poterlo ritirare
consigliato.
Annullamenti e ripristini degli abbonamenti
Gli utenti devono essere in grado di annullare l'abbonamento in qualsiasi momento. Quando un utente annulla un abbonamento, la risoluzione del diritto può essere differita fino al termina il periodo di pagamento. Ad esempio, se un utente annulla un abbonamento mensile. a metà mese, potrebbero continuare ad accedere al servizio per circa 2 settimane rimanenti prima della rimozione dell'accesso. Durante questo periodo, è ancora tecnicamente attivo, quindi l'utente può utilizzare il servizio.
Non è raro che gli utenti decidano di annullare l'annullamento durante questo periodo. periodo attivo. In questa guida, questo è chiamato ripristino. Le seguenti le sezioni descrivono come gestire scenari di ripristino nella tua alternativa l'integrazione dell'API di fatturazione.
Abbonamenti acquistati tramite un sistema di fatturazione alternativo
Se disponi di un ID transazione esterna 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 la propria
mentre è ancora attivo il periodo di un abbonamento annullato, non
transazione avviene in quel momento; puoi continuare a segnalare i rinnovi quando
scade il ciclo corrente e avrà luogo 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 sul sistema di fatturazione di Google Play. Per
abbonamenti annullati che sono stati originariamente acquistati con la fatturazione di Google Play
sistema, l'utente può scegliere di annullare l'annullamento mentre l'abbonamento
attivi tramite la funzionalità Riabbonati di Google Play. In questo caso,
ricevi una notifica in tempo reale per lo sviluppatore SUBSCRIPTION_RESTARTED nel tuo
e non viene emesso un nuovo token di acquisto: viene utilizzato il token originale
per continuare l'abbonamento. Per scoprire come gestire il ripristino in Google
Nel sistema di fatturazione di Google Play, vedi Ripristino nella gestione degli abbonamenti.
guida.
Puoi anche attivare un ripristino nel sistema di fatturazione di Google Play dall'app
chiamando il numero launchBillingFlow(). Vedi Prima della scadenza dell'abbonamento -
in-app per avere una spiegazione su come fare. Nel caso di utenti che hanno
tramite il flusso di scelta dell'utente per l'acquisto originale (che è stato annullato,
è ancora attivo), il sistema rileva automaticamente la sua scelta e mostra
utente per il ripristino di questi acquisti. Agli studenti viene chiesto di confermare
riacquistare l'abbonamento tramite Google Play, ma non è necessario effettuare
tramite il flusso di scelta dell'utente. Viene emesso un nuovo token di acquisto per l'utente
in questo caso. Il tuo backend riceve un avviso in tempo reale SUBSCRIPTION_PURCHASED
Notifica sviluppatore e il valore linkedPurchaseToken per il nuovo acquisto
è impostato come nel caso di un upgrade o un downgrade, con il vecchio acquisto
token per l'abbonamento che è stato annullato.
Nuovi abbonamenti
Se un abbonamento scade completamente, a causa di un annullamento o un pagamento rifiutato senza recupero (una sospensione dell'account scaduta), l'utente deve riabbonati se vuole riattivare il diritto.
La nuova sottoscrizione può essere attivata 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 preferiscono
per l'utilizzo. In questo caso è possibile chiamare launchBillingFlow(), come descritto
Avvia il flusso di fatturazione scelta dall'utente.
Testa la fatturazione alternativa
I tester delle licenze devono essere usati per testare l'integrazione della fatturazione alternativa. Tu non verranno addebitate le transazioni avviate dal tester delle licenze . Per saperne di più, consulta l'articolo Testare la fatturazione in-app con le licenze dell'applicazione. informazioni sulla configurazione dei tester delle licenze.
Passaggi successivi
Al termine dell'integrazione in-app, puoi integrare le tue di backend.