Indicazioni sull'integrazione in-app per il programma di offerte esterne

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

Nota: consulta la pagina Registrazione al programma di offerte esterne per i requisiti per i report sulle transazioni.

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 chiamando showExternalOfferInformationDialog() 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 nuovo showExternalOfferInformationDialog() 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 di SERVICE_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.