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

Este guia descreve como fazer a integração com 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 versão 8.2 ou mais recente da dependência da Biblioteca Play Faturamento 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 no guia de integração do faturamento, exceto que você precisa chamar enableBillingProgram para indicar que quer usar ofertas 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(BillingProgram.EXTERNAL_OFFER)
  .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 ofertas 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 Google Play Faturamento. Para conseguir esse token, chame a API createBillingProgramReportingDetailsAsync. Um novo token precisa ser gerado imediatamente antes de direcionar o usuário para fora do app para cada oferta 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.
      }
});

Como alternativa, consulte a função de suspensão createBillingProgramReportingDetailsAsync com extensões Kotlin para não precisar definir um listener:

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

Iniciar o fluxo de promoções externas

Para iniciar um fluxo de promoção externa, o app qualificado precisa chamar a API launchExternalLink() na linha de execução principal dele. Essa API usa um objeto LaunchExternalLinkParams como entrada. Para criar um objeto LaunchExternalLinkParams, use a classe LaunchExternalLinkParams.Builder. 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 Play Console.
  • linkType: o tipo de conteúdo oferecido ao usuário.
  • launchMode: especifica como o link é aberto. Para downloads de apps, defina como LAUNCH_IN_EXTERNAL_BROWSER_OR_APP.
  • billingProgram: defina como BillingProgram.EXTERNAL_OFFER.

Ao chamar launchExternalLink(), caixas de diálogo com mais informações 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 para seu app para iniciar o URI. Na maioria dos casos, é possível usar o modo LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, em que o Google Play inicia o URI para você. Se quiser um comportamento mais personalizado, como iniciar o URI em uma WebView ou abrir o URI em um navegador específico, use o modo CALLER_WILL_LAUNCH_LINK. 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 = ...;

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 {
      override fun 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)

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

Informe 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 obtido da API createBillingProgramReportingDetailsAsync. Se um usuário fizer várias compras, use o mesmo externalTransactionToken para informar cada uma delas. 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 estes códigos de resposta da seguinte maneira:

  • ERROR: este é um erro interno. Não prossiga com a transação nem abra o 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 você tentar direcioná-lo para fora do app.
  • FEATURE_NOT_SUPPORTED: as APIs de ofertas externas 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 para mostrar a caixa de diálogo de informações ao usuário na próxima vez que você tentar direcionar o usuário 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 nele. 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 promoções externas

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.