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

Questa guida descrive come eseguire l'integrazione con le API per supportare offerte esterne nelle app e nelle regioni idonee. Per scoprire di più sul programma per offerte esterne inclusi i requisiti di idoneità e l'ambito geografico, consulta requisiti del programma.

Configurazione della Libreria Fatturazione Play

Per utilizzare le API per offerte esterne, aggiungi la versione 6.2.1 o successive della dipendenza Libreria Fatturazione Play alla tua app per Android. Se devi eseguire la migrazione da una versione precedente, segui segui le istruzioni riportate nella guida alla migrazione prima di tentare di implementare offerte esterne.

Connettersi a Google Play

I primi passaggi del processo di integrazione sono gli stessi descritti in la guida all'integrazione della fatturazione, con alcune modifiche inizializzazione di BillingClient:

L'esempio seguente mostra l'inizializzazione di un BillingClient con questi 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 con 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. Consulta la sezione relativa alla gestione delle risposte per i dettagli su come la tua app dovrebbe rispondere ad altri codici di risposta.

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

});

Prepara un token per la transazione esterna

Per segnalare una transazione esterna a Google Play, devi avere un esterno il token di transazione generato dalla Libreria Fatturazione Play. Una nuova risorsa il token della transazione deve essere generato ogni volta che l'utente visita un tramite l'API per offerte esterne. Questa operazione può essere eseguita richiamando API createExternalOfferReportingDetailsAsync. Questo token dovrebbe essere generati immediatamente prima che l'utente venga indirizzato all'esterno dell'app. Dovrebbe non deve mai essere memorizzata nella cache e ne dovrebbe essere generata una nuova ogni volta che l'utente viene indirizzato al di fuori 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 di informazioni per gli utenti

Per l'integrazione con le offerte esterne, la tua app idonea deve mostrare un'informazione schermata che aiuta gli utenti a capire che stanno per essere indirizzati all'esterno a un sito web esterno. La schermata informativa deve essere mostrata agli utenti tramite chiamare l'API showExternalOfferInformationDialog prima del collegamento a un un'offerta esterna.

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 a indirizzare l'utente al sito web esterno. Se il metodo restituisce BillingResponseCode.USER_CANCELED, la tua app non deve continuare ad aprire l'app sito web.

Segnala le transazioni a Google Play

Tutte le transazioni esterne devono essere segnalate a Google Play chiamando l'API Google Play Developer dal tuo backend. Transazioni esterne devono essere segnalati e fornire un externalTransactionToken ottenuto utilizzando API createExternalOfferReportingDetailsAsync. Se un utente effettua più acquisti, puoi utilizzare lo stesso externalTransactionToken per segnalare ogni acquisto. Per scoprire come segnalare un transazione, consulta la guida all'integrazione del backend.

Gestione della risposta

Quando si verifica un errore, i metodi isExternalOfferAvailableAsync, createExternalOfferReportingDetailsAsync e showExternalOfferInformationDialog potrebbe restituire risposte diverse da BillingResponseCode.OK. Ti consigliamo di gestire questi codici di risposta come segue:

  • ERROR: questo è un errore interno. Non procedere con la transazione o aprire il sito web esterno. Riprova chiamando showExternalOfferInformationDialog() per visualizzare le informazioni all'utente la volta successiva che tenti di indirizzarlo all'esterno dell'app.
  • FEATURE_NOT_SUPPORTED: le API per offerte esterne non sono supportate da dal Play Store sul dispositivo corrente. Non procedere con la transazione o aprire il sito web esterno.
  • USER_CANCELED: non procedere con l'apertura del sito web esterno. Chiama showExternalOfferInformationDialog() di nuovo per visualizzare le informazioni. all'utente la volta successiva che tenti di indirizzarlo all'esterno di l'app.
  • BILLING_UNAVAILABLE: la transazione non è idonea per le offerte esterne e pertanto non devono procedere nell'ambito di questo programma. Il motivo è che l'utente non si trova in un paese idoneo per questo programma o il tuo account ha non è stato registrato correttamente al programma. Nel secondo caso, controlla il tuo stato di registrazione in Play Console.
  • DEVELOPER_ERROR: si è verificato un errore nella richiesta. Utilizzare 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

I tester delle licenze devono essere utilizzati per testare l'integrazione delle offerte esterne. 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.