Linee guida per l'integrazione in-app per i link a contenuti esterni

Questo documento descrive come integrare le API della Libreria Fatturazione Play per offrire link a contenuti esterni nelle app idonee. Ciò include la possibilità di collegare gli utenti negli Stati Uniti al di fuori della tua app Play per fornire loro offerte di contenuti digitali in-app e download di app. Per scoprire di più su questo programma, consulta i requisiti del programma.

Configurazione della Libreria Fatturazione Play

Aggiungi la dipendenza Libreria Fatturazione Play alla tua app per Android. Per utilizzare le API per i link esterni, devi utilizzare la versione 8.2.1 o successive. Se devi eseguire la migrazione da una versione precedente, segui le istruzioni riportate nella guida alla migrazione prima di aggiungere i link a contenuti esterni.

Inizializzare il client di fatturazione

Per inizializzare il client di fatturazione, segui gli stessi passaggi descritti in Inizializzare un BillingClient con le seguenti modifiche:

  • Non attivare PurchasesUpdatedListener, perché questo listener non è necessario per i link a contenuti esterni.
  • Chiama enableBillingProgram() con BillingProgram.EXTERNAL_CONTENT_LINK per indicare che la tua app utilizza i link a contenuti esterni.

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

Kotlin

val billingClient = BillingClient.newBuilder(context)
  .enableBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
  .build()

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .build();

Connessione a Google Play

Dopo aver inizializzato il BillingClient, connettiti a Google Play come descritto in Connessione a Google Play.

Verificare l'idoneità dell'utente

Dopo aver effettuato la connessione a Google Play, devi verificare se l'utente è idoneo al programma per i link a contenuti esterni chiamando il isBillingProgramAvailableAsync() metodo. Questo metodo restituisce BillingResponseCode.OK se l'utente è idoneo al programma per i link a contenuti esterni. L'esempio seguente mostra come verificare l'idoneità dell'utente per i link a contenuti esterni:

Kotlin

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_CONTENT_LINK,
  object : BillingProgramAvailabilityListener {
    override fun onBillingProgramAvailabilityResponse(
      billingProgram: Int, billingResult: BillingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external content links unavailable, etc.
            return
        }

        // External content links are available. Prepare an external
        // transaction token.
      }
    })

Java

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_CONTENT_LINK,
  new BillingProgramAvailabilityListener() {
    @Override
    public void onBillingProgramAvailabilityResponse(
      int billingProgram, BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external content links unavailable, etc.
            return;
        }

        // External content links are available. Prepare an external
        // transaction token.
      }

    });

Per informazioni dettagliate su come la tua app deve rispondere ad altri codici di risposta, consulta la sezione Gestione delle risposte. Se utilizzi le estensioni Kotlin, puoi utilizzare le coroutine Kotlin in modo da non dover definire un listener separato.

Preparare un token di transazione esterna

A questo punto, devi generare un token di transazione esterna dalla Libreria Fatturazione Play. Ogni volta che l'utente visita un sito web esterno tramite l'API per i link esterni, deve essere generato un nuovo token di transazione esterna. Per farlo, puoi chiamare l' API createBillingProgramReportingDetailsAsync. Il token deve essere generato immediatamente prima che l'utente venga reindirizzato.

Nota: il token di transazione esterna non deve mai essere memorizzato nella cache e devi generare un nuovo token ogni volta che l'utente viene reindirizzato.

Kotlin

val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
        .build();

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  object : BillingProgramReportingDetailsListener {
    override fun onCreateBillingProgramReportingDetailsResponse(
      billingResult: BillingResult,
      billingProgramReportingDetails: BillingProgramReportingDetails?) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            billingProgramReportingDetails?.externalTransactionToken
        // Persist the external transaction token locally. Pass it to the
        // external website when launchExternalLink is called.
    }
  })

Java

BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
        .build();

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  new BillingProgramReportingDetailsListener() {
    @Override
    public void onCreateBillingProgramReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable BillingProgramReportingDetails
        billingProgramReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          billingProgramReportingDetails.getExternalTransactionToken();

        // Persist the external transaction token locally. Pass it to the
        // external website when launchExternalLink is called.
      }
  });

Se utilizzi le estensioni Kotlin, puoi utilizzare le coroutine Kotlin in modo da non dover definire un listener separato.

Avviare il link esterno

Una volta pronto il token di transazione esterna, l'utente può essere collegato al di fuori dell'app a un'offerta di contenuti digitali o al download dell'app chiamando il metodo launchExternalLink. Quando chiami questa API, Google Play potrebbe mostrare all'utente ulteriori finestre di dialogo con informazioni a seconda delle impostazioni utente.

Quando chiami il metodo launchExternalLink, i dettagli del link esterno devono essere forniti tramite LaunchExternalLinkParams. Questa classe contiene i seguenti parametri:

  • URI del link : il link al sito web esterno in cui viene offerto il download di contenuti digitali o app. Per i download di app, questo link deve essere registrato e approvato in Play Console.
  • Tipo di link : il tipo di contenuti offerti all'utente.
  • Modalità di avvio : specifica come viene avviato il link. Per i download di app, devi impostare questo valore su LAUNCH_IN_EXTERNAL_BROWSER_OR_APP.

  • Programma di fatturazione : imposta questo valore su BillingProgram.EXTERNAL_CONTENT_LINK.

Kotlin

val params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .setLinkUri(Uri.parse("https://www.myapprovedsite.com"))
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
    .setLaunchMode(
      LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .build()

val listener : LaunchExternalLinkResponseListener =
    object : LaunchExternalLinkResponseListener {
      override fun onLaunchExternalLinkResponse(
        billingResult: BillingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }

        // If Launch Mode was set to LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, the
        // user was directed outside of the app by Play. This does not give
        // any information on the user's actions during the link out, such
        // as if a transaction was completed.

        // If Launch Mode was set to CALLER_WILL_LAUNCH_LINK, then your app
        // may proceed to direct the user to the external website.
    }
}

billingClient.launchExternalLink(activity, params, listener)

Java

LaunchExternalLinkParams params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .setLinkUri(Uri.parse("https://www.myapprovedsite.com"))
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
    .setLaunchMode(
      LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .build()

LaunchExternalLinkResponseListener listener =
  new LaunchExternalLinkResponseListener() {
    @Override
    public void onLaunchExternalLinkResponse(BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        // If Launch Mode was set to LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, the
        // user was directed outside of the app by Play. This does not give
        // any information on the user's actions during the link out, such
        // as if a transaction was completed.

        // If Launch Mode was set to CALLER_WILL_LAUNCH_LINK, then your app
        // may proceed to direct the user to the external website.
    }
  }

billingClient.launchExternalLink(activity, params, listener);

Gestione delle risposte

Quando si verifica un errore, i metodi isBillingProgramAvailableAsync(), e createBillingProgramReportingDetailsAsync(), e onLaunchExternalLinkResponse() potrebbero fornire un BillingResponseCode diverso da BillingResponseCode.OK. Ti consigliamo di gestire questi codici di risposta nel seguente modo:

  • ERROR: si tratta di un errore interno. Non procedere con la transazione o con l'apertura del sito web esterno. Riprova chiamando di nuovo l'API o chiamando launchExternalLink() al prossimo tentativo di reindirizzare l'utente al di fuori dell'app.
  • FEATURE_NOT_SUPPORTED: le API per i link a contenuti esterni non sono supportate dal Play Store sul dispositivo attuale. Non procedere con la transazione o con l'apertura del sito web esterno.
  • USER_CANCELED: non procedere con l'apertura del sito web esterno. Chiama di nuovo launchExternalLink() al prossimo tentativo di reindirizzare l'utente al di fuori dell'app.
  • BILLING_UNAVAILABLE: la transazione non è idonea per i link a contenuti esterni, quindi non procedere nell'ambito di questo programma. Questo perché l'utente non si trova in un paese idoneo per questo programma o perché la registrazione del tuo account al programma non è andata a buon fine. In quest'ultimo caso, controlla lo stato della 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 una policy di nuovi tentativi appropriata. In caso di SERVICE_DISCONNECTED, ristabilisci una connessione con Google Play prima di riprovare.

Testare i link a contenuti esterni

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