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 indirizzare gli utenti negli Stati Uniti al di fuori della tua app Google Play per fornire loro offerte di contenuti digitali in-app e download di app. Per saperne di più su questo programma, consulta i requisiti del programma.

Configurazione della Libreria Fatturazione Play

Aggiungi la dipendenza della Libreria Fatturazione Play alla tua app per Android. Per utilizzare le API per i link esterni, devi utilizzare la versione 8.2 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. 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();

Collegati a Google Play

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

Verificare l'idoneità dell'utente

Dopo aver effettuato la connessione a Google Play, devi verificare se l'utente è idoneo per il programma di link a contenuti esterni chiamando il metodo isBillingProgramAvailableAsync(). Questo metodo restituisce BillingResponseCode.OK se l'utente è idoneo per il programma di link a contenuti esterni. Il seguente esempio mostra come verificare l'idoneità dell'utente per i link ai 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 per non dover definire un listener separato.

Prepara un token di transazione esterno

A questo punto, devi generare un token di transazione esterna dalla libreria Play Billing. Un nuovo token di transazione esterna deve essere generato ogni volta che l'utente visita un sito web esterno tramite l'API External Links. Per farlo, chiama l'API createBillingProgramReportingDetailsAsync. Il token deve essere generato immediatamente prima che l'utente venga reindirizzato.

Nota: il token di transazione esterno non deve mai essere memorizzato nella cache e devi generarne uno nuovo ogni volta che l'utente esce dal sito.

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 per non dover definire un listener separato.

Apri il link esterno

Una volta pronto il token di transazione esterno, l'utente può essere collegato al di fuori dell'app a un'offerta di contenuti digitali o al download di un'app chiamando il metodo launchExternalLink. Google Play potrebbe visualizzare ulteriori finestre di dialogo informative per l'utente a seconda delle impostazioni utente quando chiami questa API.

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

  • URI link: il link al sito web esterno in cui vengono offerti i contenuti digitali o il download dell'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 campo 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(), createBillingProgramReportingDetailsAsync() e onLaunchExternalLinkResponse() potrebbero fornire un BillingResponseCode diverso da BillingResponseCode.OK. Prendi in considerazione la gestione di questi codici di risposta come segue:

  • ERROR: si è verificato un errore interno. Non procedere con la transazione o l'apertura del sito web esterno. Riprova chiamando di nuovo l'API o chiamando launchExternalLink() la prossima volta che tenti di indirizzare l'utente al di fuori dell'app.
  • FEATURE_NOT_SUPPORTED: Le API per i link ai contenuti esterni non sono supportate dal Play Store sul dispositivo attuale. Non procedere con la transazione o l'apertura del sito web esterno.
  • USER_CANCELED: non procedere con l'apertura del sito web esterno. Chiama launchExternalLink() di nuovo la prossima volta che tenti di indirizzare l'utente al di fuori dell'app.
  • BILLING_UNAVAILABLE: La transazione non è idonea per i link a contenuti esterni e pertanto non 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 gestiti con criteri di nuovi tentativi appropriati. Nel 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 di test 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.