Indicazioni per l'integrazione in-app solo per la fatturazione alternativa

Questa guida descrive come integrare le API per offrire solo la fatturazione alternativa (ovvero senza scelta dell'utente) nelle app idonee. Per saperne di più su questi programmi, inclusi i requisiti di idoneità e l'ambito geografico, consulta Informazioni sulla fatturazione alternativa.

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 6.1 o successive.

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 la tua app utilizza solo un sistema di fatturazione alternativo: enableAlternativeBillingOnly.

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

var billingClient = BillingClient.newBuilder(context)
    .enableAlternativeBillingOnly()
    .build()

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableAlternativeBillingOnly()
    .build();

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

Verifica disponibilità

La tua app deve confermare che è disponibile solo la fatturazione alternativa chiamando isAlternativeBillingOnlyAvailableAsync.

Questa API restituirà BillingResponseCode.OK se è disponibile solo la fatturazione alternativa. Per informazioni dettagliate su come la tua app deve rispondere ad altri codici di risposta, consulta la sezione Gestione delle risposte.

billingClient.isAlternativeBillingOnlyAvailableAsync(object:
    AlternativeBillingOnlyAvailabilityListener {
        override fun onAlternativeBillingOnlyAvailabilityResponse(
            billingResult: BillingResult) {
            if (billingResult.responseCode !=  BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors,
                // handling alternative billing only being unavailable, etc.
                return
            }

            // Alternative billing only is available. Continue with steps in
            // the guide.
        }
    });

billingClient.isAlternativeBillingOnlyAvailable(
    new AlternativeBillingOnlyAvailabilityListener() {
        @Override
        public void onAlternativeBillingOnlyAvailabilityResponse(
            BillingResult billingResult) {
            if (billingResult.getResponseCode() != BillingResponseCode.OK) {
                 // Handle failures such as retrying due to network errors,
                 // handling alternative billing only being unavailable,
                 // etc.
                return;
            }

            // Alternative billing only is available. Continue with steps in
            // the guide.
        }
    });

Finestra di dialogo informativa per gli utenti

Per l'integrazione solo con la fatturazione alternativa, la tua app idonea deve mostrare una schermata informativa che aiuti gli utenti a capire che la fatturazione non verrà gestita da Google Play. La schermata informativa deve essere mostrata agli utenti chiamando l'API showAlternativeBillingOnlyInformationDialog prima di avviare il flusso di fatturazione alternativa ogni volta. Se l'utente ha già confermato la finestra di dialogo, l'utilizzo di questa API in genere non comporta la visualizzazione di nuovo della finestra di dialogo. A volte la finestra di dialogo viene mostrata di nuovo a un utente in situazioni come quando l'utente svuota le cache sul proprio dispositivo.

// An activity reference from which the alternative billing only information
// dialog will be launched.
val activity : Activity = ...;

val listener : AlternativeBillingOnlyInformationDialogListener =
    AlternativeBillingOnlyInformationDialogListener { 
        override fun onAlternativeBillingOnlyInformationDialogResponse(
            billingResult: BillingResult) {
            // check billingResult
        }
}

val billingResult =
    billingClient.showAlternativeBillingOnlyInformationDialog(activity,
        listener)

// An activity reference from which the alternative billing only information
// dialog will be launched.
Activity activity = ...;

AlternativeBillingOnlyInformationDialogListener listener =
    new AlternativeBillingOnlyInformationDialogListener() {
        @Override
        public void onAlternativeBillingOnlyInformationDialogResponse(
            BillingResult billingResult) {
                // check billingResult
            }
    };

BillingResult billingResult =
    billingClient.showAlternativeBillingOnlyInformationDialog(activity,
        listener);

Se questo metodo restituisce BillingResponseCode.OK, la tua app può procedere con la transazione. Nel caso di BillingResponseCode.USER_CANCELED, la tua app deve chiamare showAlternativeBillingOnlyInformationDialog per mostrare di nuovo la finestra di dialogo all'utente. Per altri codici di risposta, consulta la sezione Gestione delle risposte.

Segnalazione delle transazioni a Google Play

Tutte le transazioni effettuate tramite un sistema di fatturazione alternativo devono essere segnalate a Google Play chiamando l'API Google Play Developer dal tuo backend entro 24 ore, fornendo un externalTransactionToken ottenuto utilizzando l'API descritta di seguito. Un nuovo externalTransactionToken deve essere generato per ogni acquisto una tantum, ogni nuovo abbonamento e per qualsiasi upgrade/downgrade di un abbonamento esistente. Per scoprire come segnalare una transazione una volta ottenuto un externalTransactionToken, consulta la guida all'integrazione del backend.

billingClient.createAlternativeBillingOnlyReportingDetailsAsync(object:
    AlternativeBillingOnlyReportingDetailsListener {
        override fun onAlternativeBillingOnlyTokenResponse(
            billingResult: BillingResult,
            alternativeBillingOnlyReportingDetails:
                AlternativeBillingOnlyReportingDetails?) {
            if (billingResult.responseCode !=  BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors.
                return
            }

            val externalTransactionToken =
                alternativeBillingOnlyReportingDetails?
                    .externalTransactionToken

            // Send transaction token to backend and report to Google Play.
        }
    });

billingClient.createAlternativeBillingOnlyReportingDetailsAsync(
    new AlternativeBillingOnlyReportingDetailsListener() {
        @Override
        public void onAlternativeBillingOnlyTokenResponse(
            BillingResult billingResult,
            @Nullable AlternativeBillingOnlyReportingDetails
                alternativeBillingOnlyReportingDetails) {
            if (billingResult.getResponseCode() != BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors.
                return;
            }

            String transactionToken =
                alternativeBillingOnlyReportingDetails
                .getExternalTransactionToken();

            // Send transaction token to backend and report to Google Play.
        }
    });

Gestione delle risposte

I metodi precedenti isAlternativeBillingOnlyAvailableAsync(), showAlternativeBillingOnlyInformationDialog() e createAlternativeBillingOnlyReportingDetailsAsync() potrebbero restituire risposte non BillingResponseCode.OK in caso di errori. Di seguito è descritta la gestione consigliata degli errori:

• ERROR: si è verificato un errore interno. Non procedere con la transazione. Riprova chiamando showAlternativeBillingOnlyInformationDialog() per visualizzare la finestra di dialogo con le informazioni per l'utente al successivo tentativo di acquisto.
• FEATURE_NOT_SUPPORTED: Le API di fatturazione alternativa non sono supportate da Play Store sul dispositivo attuale. Non procedere con la transazione.
• USER_CANCELED: non procedere con la transazione. Chiama showAlternativeBillingOnlyInformationDialog() di nuovo per mostrare la finestra di dialogo delle informazioni all'utente la prossima volta che tenta di effettuare un acquisto.
• BILLING_UNAVAILABLE: La transazione non è idonea solo per la fatturazione alternativa e pertanto non deve procedere nell'ambito di questo programma. Ciò è dovuto al fatto che l'utente non si trova in un paese idoneo per questo programma o il tuo account non è stato registrato correttamente al programma. In questo caso, controlla lo stato della registrazione in Play Console.
• DEVELOPER_ERROR: si è verificato un errore con la 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 riprovati. Nel caso di SERVICE_DISCONNECTED, ristabilisci una connessione con Google Play prima di riprovare.

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.