Orientações de integração no app para o programa de ofertas externas

Este guia descreve como integrar as APIs para oferecer suporte a promoções externas em apps e regiões qualificados. Para saber mais sobre o Programa de Promoções Externas incluindo os requisitos de qualificação e o escopo geográfico, consulte os requisitos do programa.

Configuração da Biblioteca Play Faturamento

Para usar as APIs de promoções externas, adicione a dependência da Biblioteca Play Faturamento versão 8.2.1 ou mais recente ao seu app Android. Se precisar migrar de uma versão anterior, siga as instruções no guia de migração antes de tentar implementar promoções externas.

Conectar ao Google Play

As primeiras etapas do processo de integração são as mesmas descritas em o guia de integração do faturamento, exceto que você precisa chamar enableBillingProgram para indicar que quer usar promoções externas ao inicializar seu BillingClient:

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

Kotlin

val billingClient = BillingClient.newBuilder(context)
    .enableBillingProgram(
        EnableBillingProgramParams.newBuilder()
            .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
            .build()
    )
    .build()

Java

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

Depois de inicializar o BillingClient, você precisa estabelecer uma conexão com o Google Play, conforme descrito no guia de integração.

Ver disponibilidade

Para confirmar se as promoções externas estão disponíveis para o usuário atual, chame isBillingProgramAvailableAsync.

Essa API retorna BillingResponseCode.OK se as promoções externas estiverem disponíveis. Consulte o processamento de respostas para mais detalhes sobre como seu app precisa responder a outros códigos de resposta.

Kotlin

billingClient.isBillingProgramAvailableAsync(
    BillingProgram.EXTERNAL_OFFER,
    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 offers unavailable, etc.
                return
            }

            // External offers are available. Continue with steps in the
            // guide.
        }
    }
)

Java


billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_OFFER,
  new BillingProgramAvailabilityListener() {
    @Override
    public void onBillingProgramAvailabilityResponse(
      BillingResult billingResult,
      BillingProgramAvailabilityDetails billingProgramAvailabilityDetails) {
        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.
      }
  });

Preparar um token de transação externa

Para informar uma transação externa ao Google Play, você precisa ter um token de transação externa gerado pela Biblioteca Play Faturamento. É possível receber esse token chamando a createBillingProgramReportingDetailsAsync API. Um novo token precisa ser gerado imediatamente antes de direcionar o usuário para fora do app para cada promoção externa. Os tokens não podem ser armazenados em cache entre transações.

Kotlin

val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
        .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 transaction token in your backend. You may pass it
            // to the external website when calling the launchExternalLink API.
        }
    }
)

Java

BillingProgramReportingDetailsParams params =
  BillingProgramReportingDetailsParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
    .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 transaction token in your backend. You may pass it
        // to the external website when calling the launchExternalLink API.
      }
});

Também é possível consultar a função de suspensão createBillingProgramReportingDetailsAsync com extensões Kotlin para não precisar definir um listener:

val createBillingProgramReportingDetailsResult =
    withContext(coroutineContext) {
        billingClient
            .createBillingProgramReportingDetails(params)
    }
// Process the result

Iniciar o fluxo de promoções externas

Para iniciar um fluxo de promoções externas, seu app qualificado precisa chamar a launchExternalLink() API na linha de execução principal. Essa API recebe uma entrada de um LaunchExternalLinkParams objeto. Para criar um LaunchExternalLinkParams objeto, use a LaunchExternalLinkParams.Builder classe. Essa classe contém os seguintes parâmetros:

  • linkUri : 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.
  • linkType : o tipo de conteúdo oferecido ao usuário.
  • launchMode : especifica como o link é iniciado. Para downloads de apps, defina esse parâmetro como LAUNCH_IN_EXTERNAL_BROWSER_OR_APP.
  • billingProgram : defina como BillingProgram.EXTERNAL_OFFER.

Ao chamar launchExternalLink(), caixas de diálogo com informações adicionais podem ser mostradas ao usuário com base nas configurações dele. Dependendo do parâmetro launchMode, o Google Play inicia o URI do link em um navegador externo ou retorna o fluxo ao seu app para iniciar o URI. Na maioria dos casos, é possível usar o LAUNCH_IN_EXTERNAL_BROWSER_OR_APP modo, em que o Google Play inicia o URI para você. Se você quiser um comportamento mais personalizado, como iniciar o URI em uma WebView ou abrir o URI em um navegador específico, use o CALLER_WILL_LAUNCH_LINK modo. Para proteger a privacidade do usuário, verifique se nenhuma informação de identificação pessoal (PII) é transmitida no URI.

Kotlin

// An activity reference from which the external offers flow will be launched.
val activity = this.activity

val params =
    LaunchExternalLinkParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
        // You can pass along the external transaction token from
        // BillingProgramReportingDetails as a URL parameter in the URI
        .setLinkUri(yourLinkUri)
        .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
        .setLaunchMode(
            LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP
        )
        .build()

val listener: LaunchExternalLinkResponseListener =
    LaunchExternalLinkResponseListener { billingResult ->
        if (billingResult.responseCode == BillingResponseCode.OK) {
            // Proceed with the rest of the external offer flow. If the user
            // purchases an item, be sure to report the transaction to Google Play.
        } else {
            // Handle failures such as retrying due to network errors.
        }
    }

billingClient.launchExternalLink(activity, params, listener)

Java


// An activity reference from which the external offers flow will be launched.
Activity activity = ...;

LaunchExternalLinkParams params = LaunchExternalLinkParams.newBuilder()
  .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
  // You can pass along the external transaction token from  
  // BillingProgramReportingDetails as a URL parameter in the URI
  .setLinkUri(yourLinkUri)
  .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.responseCode == BillingResponseCode.OK) {
        // Proceed with the rest of the external offer flow. If the user
        // purchases an item, be sure to report the transaction to Google
        // Play.
      } else {
        // Handle failures such as retrying due to network errors.
      }
    }
  }

billingClient.launchExternalLink(activity, params, listener);

Se você definir LaunchMode como CALLER_WILL_LAUNCH_LINK, direcione o usuário para fora do app somente se onLaunchExternalLinkResponse fornecer BillingResponseCode.OK.

Informar transações ao Google Play

Você precisa informar todas as transações externas ao Google Play chamando a API Google Play Developer pelo back-end. Ao informar uma transação, você precisa fornecer um externalTransactionToken recebido da createBillingProgramReportingDetailsAsync API. Se um usuário fizer várias compras, você poderá usar o mesmo externalTransactionToken para informar cada compra. Para saber como informar uma transação, consulte o guia de integração de back-end.

Processamento de respostas

Quando ocorre um erro, os métodos isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync() e launchExternalLink() podem retornar respostas diferentes 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 launchExternalLink() para mostrar a caixa de diálogo de informações ao usuário na próxima vez que tentar direcioná-lo para fora do app.
  • FEATURE_NOT_SUPPORTED: as APIs de promoções externas não oferecem suporte à 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() de novo para mostrar a caixa de diálogo de informações ao usuário na próxima vez que tentar direcioná-lo para fora do app.
  • BILLING_UNAVAILABLE: a transação não está qualificada para promoções externas 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 promoções externas

Os testadores licenciados precisam ser usados para testar a integração de promoções 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.