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.1 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 os links de conteúdo externo.

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

Kotlin

val billingClient = BillingClient.newBuilder(context)
    .enableBillingProgram(
        EnableBillingProgramParams.newBuilder()
            .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
            .build()
    )
    .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, chame o método isBillingProgramAvailableAsync() para verificar se o usuário está qualificado para o Programa de Link com Conteúdo Externo. Esse método retorna BillingResponseCode.OK se o usuário estiver qualificado para o programa de links de conteúdo externo. O exemplo 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(
            billingResult: BillingResult,
            billingProgramAvailabilityDetails: BillingProgramAvailabilityDetails
        ) {
            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ê estiver usando extensões Kotlin, poderá usar as corrotinas do 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 Play Faturamento. Um novo token de transação externa precisa ser gerado sempre que o usuário acessar um site externo pela API de links externos. Isso pode ser feito chamando a createBillingProgramReportingDetailsAsync API. 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ê estiver usando extensões Kotlin, poderá usar as corrotinas do Kotlin para não precisar definir um listener separado.

Iniciar o link externo

Quando 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 download do app chamando launchExternalLink método. O Google Play poderá renderizar caixas de diálogo com informações adicionais para o usuário, dependendo das configurações dele, quando você chamar 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 Google Play Console.
  • Tipo de link : o tipo de conteúdo oferecido ao usuário.
  • Modo de inicialização : especifica como o link é iniciado. Para downloads de apps, defina esse valor como LAUNCH_IN_EXTERNAL_BROWSER_OR_APP.

  • Programa de faturamento : defina esse valor 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(), e createBillingProgramReportingDetailsAsync(), e onLaunchExternalLinkResponse() podem fornecer um BillingResponseCode diferente de BillingResponseCode.OK. Considere processar esses códigos de resposta da seguinte maneira:

  • ERROR: este é um erro interno. Não prossiga com a transação ou a abertura do 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 ou a abertura do site externo.
  • USER_CANCELED: não prossiga com a abertura do 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 nova tentativa 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 licenciados precisam ser usados para testar a integração de ofertas externas. Você não vai receber uma fatura pelas transações iniciadas por contas de testadores licenciados. Consulte Testar o faturamento em apps com o licenciamento para mais informações sobre como configurar testadores licenciados.

Próximas etapas

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