Orientações de integração no app para links de conteúdo externo

Este documento descreve como integrar as APIs da Biblioteca Play Faturamento para oferecer links de conteúdo externo em apps qualificados. Isso inclui a capacidade de vincular usuários nos EUA fora do seu app do Google Play para oferecer conteúdo digital no app e downloads de apps. Para saber mais sobre esse programa, consulte os requisitos do programa.

Configuração da Biblioteca Play Faturamento

Adicione a dependência da Biblioteca Play Faturamento ao seu app Android. Para usar as APIs de links externos, você precisa usar a versão 8.2 ou mais recente. Se precisar migrar de uma versão anterior, siga as instruções no guia de migração antes de adicionar os links de conteúdo externo.

Inicializar o cliente de faturamento

Para inicializar o cliente de faturamento, siga as mesmas etapas descritas em Inicializar um BillingClient com as seguintes modificações:

  • Não ative o PurchasesUpdatedListener. Esse listener não é necessário para links de conteúdo externo.
  • Chame enableBillingProgram() com BillingProgram.EXTERNAL_CONTENT_LINK para indicar que seu app usa links de conteúdo externo.

O exemplo abaixo mostra a inicialização de um BillingClient com estas modificações:

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();

Conectar ao Google Play

Depois de inicializar o BillingClient, conecte-se ao Google Play conforme descrito em Conectar ao Google Play.

Verificar a qualificação do usuário

Depois de se conectar ao Google Play, verifique se o usuário está qualificado para o programa de links para conteúdo externo chamando o método isBillingProgramAvailableAsync(). Esse método retorna BillingResponseCode.OK se o usuário estiver qualificado para o programa de links de conteúdo externo. A amostra a seguir mostra como verificar a qualificação do usuário para links de conteúdo externo:

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

    });

Consulte a seção Processamento de respostas para mais detalhes sobre como seu app precisa responder a outros códigos de resposta. Se você usa extensões Kotlin, pode usar corrotinas Kotlin para não precisar definir um listener separado.

Preparar um token de transação externa

Em seguida, gere um token de transação externa na Biblioteca do Faturamento do Google Play. Um novo token de transação externa precisa ser gerado sempre que o usuário acessa um site externo pela API External Links. Isso pode ser feito chamando a API createBillingProgramReportingDetailsAsync. O token precisa ser gerado imediatamente antes de o usuário ser vinculado.

Observação: o token de transação externa nunca deve ser armazenado em cache. Gere um novo token sempre que o usuário for vinculado.

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 você usa extensões Kotlin, pode usar corrotinas Kotlin para não precisar definir um listener separado.

Abrir o link externo

Depois que o token de transação externa estiver pronto, o usuário poderá ser vinculado fora do app a uma oferta de conteúdo digital ou ao download de um app chamando o método launchExternalLink. O Google Play pode renderizar caixas de diálogo de informações adicionais para o usuário, dependendo das configurações dele, quando você chama essa API.

Ao chamar o método launchExternalLink, os detalhes do link externo precisam ser fornecidos por LaunchExternalLinkParams. Essa classe contém os seguintes parâmetros:

  • URI do link: o link para o site externo em que o conteúdo digital ou o download do app é oferecido. Para downloads de apps, esse link precisa ser registrado e aprovado no Play Console.
  • Tipo de link: o tipo de conteúdo oferecido ao usuário.
  • Modo de inicialização: especifica como o link é aberto. Para downloads de apps, defina como LAUNCH_IN_EXTERNAL_BROWSER_OR_APP.

  • Programa de faturamento: defina como 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);

Processamento de respostas

Quando ocorre um erro, os métodos isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync() e onLaunchExternalLinkResponse() podem fornecer um BillingResponseCode diferente de BillingResponseCode.OK. Considere processar estes códigos de resposta da seguinte forma:

  • ERROR: este é um erro interno. Não prossiga com a transação nem abra o site externo. Tente de novo chamando a API ou launchExternalLink() na próxima vez que tentar direcionar o usuário para fora do app.
  • FEATURE_NOT_SUPPORTED: as APIs de link de conteúdo externo não são compatíveis com a Play Store no dispositivo atual. Não prossiga com a transação nem abra o site externo.
  • USER_CANCELED: não abra o site externo. Chame launchExternalLink() novamente na próxima vez que tentar direcionar o usuário para fora do app.
  • BILLING_UNAVAILABLE: a transação não está qualificada para links de conteúdo externo e, portanto, não pode continuar neste programa. Isso ocorre porque o usuário não está em um país qualificado para o programa ou sua conta não foi inscrita no programa. No último caso, verifique o status de registro no Google Play Console.
  • DEVELOPER_ERROR: há um erro na solicitação. Use a mensagem de depuração para identificar e corrigir o erro antes de continuar.
  • NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE: são erros temporários que precisam ser tratados com uma política de novas tentativas adequada. No caso de SERVICE_DISCONNECTED, restabeleça uma conexão com o Google Play antes de tentar de novo.

Testar links de conteúdo externo

Os testadores de licença devem ser usados para testar a integração de promoções externas. Você não vai receber faturas pelas transações iniciadas por contas de testador de licença. Consulte Testar o faturamento em apps com o licenciamento de apps para mais informações sobre como configurar testadores de licença.

Próximas etapas

Depois de concluir a integração no app, estará tudo pronto para integrar seu back-end.