Questa guida descrive come eseguire l'integrazione con le API per supportare le offerte esterne nelle regioni e nelle app idonee. Per scoprire di più sul programma di offerte esterne, inclusi i requisiti di idoneità e l'ambito geografico, consulta i requisiti del programma.
Configurazione della Libreria Fatturazione Play
Per utilizzare le API delle offerte esterne, aggiungi la versione 6.2.1 o successive della dipendenza Libreria Fatturazione Play alla tua app Android. Se devi eseguire la migrazione da una versione precedente, segui le istruzioni nella guida alla migrazione prima di tentare di implementare le offerte esterne.
Collegati a Google Play
I primi passaggi del processo di integrazione sono gli stessi descritti nella guida all'integrazione della fatturazione, con alcune modifiche al momento dell'inizializzazione di BillingClient
:
- Devi chiamare un nuovo metodo per indicare che vuoi utilizzare le offerte
esterne:
enableExternalOffer
.
L'esempio seguente illustra l'inizializzazione di un elemento BillingClient
con queste
modifiche:
Kotlin
var billingClient = BillingClient.newBuilder(context)
.enableExternalOffer()
.build()
Java
private BillingClient billingClient = BillingClient.newBuilder(context)
.enableExternalOffer()
.build();
Dopo aver inizializzato BillingClient
, devi stabilire una connessione a Google Play come descritto nella guida all'integrazione.
Verifica disponibilità
La tua app dovrebbe confermare la disponibilità di offerte esterne chiamando il numero
isExternalOfferAvailableAsync
.
Questa API restituisce BillingResponseCode.OK
se sono disponibili offerte esterne.
Per maggiori dettagli su come la tua app deve rispondere ad altri codici di risposta, consulta Gestione delle risposte.
Kotlin
billingClient.isExternalOfferAvailableAsync(
object : ExternalOfferAvailabilityListener {
override fun onExternalOfferAvailabilityResponse(
billingResult: BillingResult) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling external offers unavailable, etc.
return
}
// External offers are available. Continue with steps in the
// guide.
})
Java
billingClient.isExternalOfferAvailableAsync(
new ExternalOfferAvailabilityListener() {
@Override
public void onExternalOfferAvailabilityResponse(
BillingResult billingResult) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling external offers being unavailable, etc.
return;
}
// External offers are available. Continue with steps in the
// guide.
}
});
Preparare un token di transazione esterno
Per segnalare una transazione esterna a Google Play, devi disporre di un token di transazione esterna generato dalla Libreria Fatturazione Play. È necessario generare un nuovo token di transazione esterna ogni volta che l'utente visita un sito web esterno tramite l'API di offerte esterne. Per farlo, puoi chiamare l'API createExternalOfferReportingDetailsAsync
. Questo token deve essere generato immediatamente prima che l'utente venga indirizzato all'esterno dell'app. Non deve mai essere memorizzato nella cache e deve essere generato un nuovo token ogni volta che l'utente viene indirizzato all'esterno dell'app.
Kotlin
billingClient.createExternalOfferReportingDetailsAsync(
object : ExternalOfferReportingDetailsListener {
override fun onExternalOfferReportingDetailsResponse(
billingResult: BillingResult,
externalOfferReportingDetails: ExternalOfferReportingDetails?) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return
}
val externalTransactionToken =
externalOfferReportingDetails?.externalTransactionToken
// Persist the transaction token locally. Pass it to the external
// website when showExternalOfferInformationDialog is called.
}
})
Java
billingClient.createExternalOfferReportingDetailsAsync(
new ExternalOfferReportingDetailsListener() {
@Override
public void onExternalOfferReportingDetailsResponse(
BillingResult billingResult,
@Nullable ExternalOfferReportingDetails
externalOfferReportingDetails) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return;
}
String transactionToken =
externalOfferReportingDetails.getExternalTransactionToken();
// Persist the external transaction token locally. Pass it to the
// external website when showExternalOfferInformationDialog is
// called.
}
});
Finestra di dialogo delle informazioni per gli utenti
Per l'integrazione con offerte esterne, la tua app idonea deve mostrare una schermata
informazioni che aiuti gli utenti a capire che stanno per essere indirizzati a un sito web esterno
all'esterno dell'app. La schermata delle informazioni deve essere mostrata agli utenti
chiamando l'API showExternalOfferInformationDialog
prima di effettuare il collegamento a
un'offerta esterna ogni volta.
Kotlin
// An activity reference from which the external offers information dialog
// will be launched.
val activity : Activity = ...;
val listener : ExternalOfferInformationDialogListener =
ExternalOfferInformationDialogListener {
override fun onExternalOfferInformationDialogResponse(
billingResult: BillingResult){
// Check billingResult
}
}
val billingResult = billingClient.showExternalOfferInformationDialog(
activity, listener)
Java
// An activity reference from which the external offers information dialog
// will be launched.
Activity activity = ...;
ExternalOfferInformationDialogListener listener =
new ExternalOfferInformationDialogListener() {
@Override
public void onExternalOfferInformationDialogResponse(
BillingResult billingResult) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
}
// Open the external website, passing along the external transaction
// token as a URL parameter. If the user purchases an item, be sure
// to report the transaction to Google Play.
}
}
BillingResult billingResult =
billingClient.showExternalOfferInformationDialog(activity, listener);
Se questo metodo restituisce BillingResponseCode.OK
, la tua app può procedere per
indirizzare l'utente al sito web esterno. Se il metodo restituisce BillingResponseCode.USER_CANCELED
, la tua app non deve continuare ad aprire il sito web.
Segnalare le transazioni a Google Play
Tutte le transazioni esterne devono essere segnalate a Google Play chiamando l'API Google Play Developer dal backend. Le transazioni esterne
devono essere segnalate fornendo un
externalTransactionToken
ottenuto utilizzando
l'API
createExternalOfferReportingDetailsAsync
. Se un utente effettua più acquisti, puoi utilizzare lo stesso externalTransactionToken
per segnalare ogni acquisto. Per informazioni su come segnalare una transazione, consulta la guida all'integrazione di backend.
Gestione delle risposte
Quando si verifica un errore, i metodi isExternalOfferAvailableAsync
,
createExternalOfferReportingDetailsAsync
e
showExternalOfferInformationDialog
potrebbero restituire risposte diverse da
BillingResponseCode.OK
. Ti consigliamo di gestire questi codici di risposta nel seguente modo:
ERROR
: questo è un errore interno. Non procedere con la transazione o non aprire il sito web esterno. Riprova chiamandoshowExternalOfferInformationDialog()
per mostrare all'utente la finestra di dialogo delle informazioni la volta successiva che tenti di indirizzare l'utente all'esterno dell'app.FEATURE_NOT_SUPPORTED
: le API delle offerte esterne non sono supportate dal Play Store sul dispositivo attuale. Non procedere con la transazione o non aprire il sito web esterno.USER_CANCELED
: non aprire il sito web esterno. Chiama di nuovoshowExternalOfferInformationDialog()
per mostrare la finestra di dialogo delle informazioni all'utente la prossima volta che tenti di indirizzarlo all'esterno dell'app.BILLING_UNAVAILABLE
: la transazione non è idonea per le offerte esterne e, pertanto, non deve procedere nell'ambito di questo programma. Il motivo è che l'utente non si trova in un paese idoneo per questo programma oppure il tuo account non è stato registrato correttamente al programma. Nel secondo caso, controlla lo stato della tua registrazione in Play Console.DEVELOPER_ERROR
: si è verificato un errore nella richiesta. Utilizza il messaggio di debug per identificare e correggere l'errore prima di procedere.NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE
: si tratta di errori temporanei che devono essere gestiti con un criterio appropriato per i nuovi tentativi. Nel caso diSERVICE_DISCONNECTED
, ristabilisci una connessione con Google Play prima di riprovare.
Testare le offerte esterne
Ti consigliamo di utilizzare i tester delle licenze per testare l'integrazione delle tue offerte esterne. 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.