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 scoprire 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 Android. Per utilizzare le API di fatturazione alternativa, devi utilizzare la versione 6.1 o successive.

Collegati a Google Play

I primi passaggi del processo di integrazione sono gli stessi descritti nella guida all'integrazione di Fatturazione Google Play, con alcune modifiche al momento dell'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 illustra l'inizializzazione di un elemento BillingClient con queste modifiche:

Kotlin


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

Java

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 della disponibilità in corso...

La tua app dovrebbe confermare che è disponibile solo la fatturazione alternativa chiamando il numero isAlternativeBillingOnlyAvailableAsync.

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

Kotlin


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

Java


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 delle informazioni 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 sarà gestita da Google Play. La schermata delle informazioni deve essere mostrata agli utenti chiamando l'API showAlternativeBillingOnlyInformationDialog prima di avviare ogni volta il flusso di fatturazione alternativo. Se l'utente ha già confermato la finestra di dialogo, utilizzando questa API in genere non viene mostrata di nuovo la finestra di dialogo. Potrebbe capitare che la finestra di dialogo venga mostrata di nuovo a un utente in situazioni ad esempio se l'utente svuota le cache sul proprio dispositivo.

Kotlin


// 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)

Java


// 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 relativa alla gestione delle risposte.

Segnalare le 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 che viene ottenuto usando l'API descritta di seguito. È necessario generare un nuovo externalTransactionToken per ogni acquisto una tantum, ogni nuova sottoscrizione e per eventuali upgrade/downgrade a un abbonamento esistente. Per scoprire come segnalare una transazione una volta ottenuto un externalTransactionToken, consulta la guida all'integrazione dei backend.

Kotlin

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

Java


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 sopra indicati isAlternativeBillingOnlyAvailableAsync(), showAlternativeBillingOnlyInformationDialog() e createAlternativeBillingOnlyReportingDetailsAsync() potrebbero restituire risposte non-BillingResponseCode.OK in caso di errori. La gestione consigliata degli errori è descritta di seguito:

  • ERROR: questo è un errore interno. Procedi con l'elaborazione della transazione tramite il sistema di fatturazione alternativo. Non è necessario segnalare la transazione a Google, inclusi eventuali rinnovi degli abbonamenti interessati.
  • FEATURE_NOT_SUPPORTED: le API di fatturazione alternativa non sono supportate dal Play Store sul dispositivo attuale. Procedi all'elaborazione della transazione tramite il sistema di fatturazione alternativo. Non è necessario segnalare la transazione a Google e gli eventuali rinnovi degli abbonamenti interessati.
  • USER_CANCELED: richiama di nuovo showAlternativeBillingOnlyInformationDialog() per mostrare la finestra di dialogo di 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 in base a 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. In quest'ultimo 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 riprovati. In caso di SERVICE_DISCONNECTED, ristabilire una connessione con Google Play prima di riprovare.

Testare la fatturazione alternativa

È consigliabile utilizzare i tester delle licenze per testare l'integrazione della fatturazione alternativa. 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.