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

Neste guia, descrevemos como fazer a integração com as APIs para oferecer suporte a ofertas externas em apps e regiões qualificados. Para saber mais sobre o programa de ofertas 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 ofertas externas, adicione a versão 6.2.1 ou mais recente da dependência da Biblioteca Play Faturamento ao seu app Android. Se você precisar migrar de uma versão anterior, siga as instruções no guia de migração antes de tentar implementar ofertas externas.

Conectar ao Google Play

As primeiras etapas do processo de integração são as mesmas descritas no guia de integração de faturamento, com algumas modificações ao inicializar o BillingClient:

• É necessário chamar um novo método para indicar que você quer usar ofertas externas: enableExternalOffer.

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

var billingClient = BillingClient.newBuilder(context)
  .enableExternalOffer()
  .build()

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableExternalOffer()
    .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

Seu app precisa confirmar se as ofertas externas estão disponíveis chamando isExternalOfferAvailableAsync.

Essa API vai retornar BillingResponseCode.OK se houver ofertas externas disponíveis. Consulte o processamento de respostas para mais detalhes sobre como seu app precisa responder a outros códigos de resposta.

billingClient.isExternalOfferAvailableAsync(
  object : ExternalOfferAvailabilityListener {
    override fun onExternalOfferAvailabilityResponse(
      billingResult: BillingResult) {
        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.
})

billingClient.isExternalOfferAvailableAsync(
  new ExternalOfferAvailabilityListener() {
    @Override
    public void onExternalOfferAvailabilityResponse(
      BillingResult billingResult) {
        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. Um novo token de transação externa precisa ser gerado sempre que o usuário visita um site externo pela API de ofertas externas. Para fazer isso, chame a API createExternalOfferReportingDetailsAsync. É preciso gerar esse token imediatamente antes de o usuário ser direcionado para fora do app. Ele nunca pode ser armazenado em cache e um novo precisa ser gerado sempre que o usuário for direcionado para fora do app.

billingClient.createExternalOfferReportingDetailsAsync(
  object : ExternalOfferReportingDetailsListener {
    override fun onExternalOfferReportingDetailsResponse(
      billingResult: BillingResult,
      externalOfferReportingDetails: ExternalOfferReportingDetails?) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            externalOfferReportingDetails?.externalTransactionToken
        // Persist the transaction token locally. Pass it to the external
        // website when showExternalOfferInformationDialog is called.
    }
})

billingClient.createExternalOfferReportingDetailsAsync(
  new ExternalOfferReportingDetailsListener() {
    @Override
    public void onExternalOfferReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable ExternalOfferReportingDetails
        externalOfferReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          externalOfferReportingDetails.getExternalTransactionToken();

        // Persist the external transaction token locally. Pass it to the
        // external website when showExternalOfferInformationDialog is
        // called.
      }
});

Caixa de diálogo de informações para os usuários

Para fazer a integração com ofertas externas, o app qualificado precisa mostrar uma tela de informações que ajude os usuários a entender que estão prestes a ser direcionados para um site externo. A tela de informações precisa ser mostrada aos usuários chamando a API showExternalOfferInformationDialog antes da vinculação a uma oferta externa todas as vezes.

// An activity reference from which the external offers information dialog
// will be launched.
val activity : Activity = ...;

val listener : ExternalOfferInformationDialogListener =
  ExternalOfferInformationDialogListener {
      override fun onExternalOfferInformationDialogResponse(
        billingResult: BillingResult){
        // Check billingResult
    }
}

val billingResult = billingClient.showExternalOfferInformationDialog(
  activity, listener)

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

ExternalOfferInformationDialogListener listener =
  new ExternalOfferInformationDialogListener() {
    @Override
    public void onExternalOfferInformationDialogResponse(
      BillingResult billingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
          // Handle failures such as retrying due to network errors.
        }
        // Open the external website, passing along the external transaction
        // token as a URL parameter. If the user purchases an item, be sure
        // to report the transaction to Google Play.
      }
}

BillingResult billingResult =
  billingClient.showExternalOfferInformationDialog(activity, listener);

Se esse método retornar BillingResponseCode.OK, o app poderá direcionar o usuário para o site externo. Se o método retornar BillingResponseCode.USER_CANCELED, o app não poderá continuar abrindo o site.

Informar transações ao Google Play

Todas as transações externas precisam ser informadas ao Google Play chamando a API Google Play Developer do back-end. Transações externas precisam ser informadas ao fornecer um externalTransactionToken recebido usando a API createExternalOfferReportingDetailsAsync. 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 isExternalOfferAvailableAsync, createExternalOfferReportingDetailsAsync e showExternalOfferInformationDialog 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 abra o site externo. Tente novamente chamando showExternalOfferInformationDialog() para mostrar a caixa de diálogo de informações para o usuário na próxima vez que você tentar direcionar o usuário para fora do app.
• FEATURE_NOT_SUPPORTED: as APIs de ofertas externas não têm suporte da Play Store no dispositivo atual. Não prossiga com a transação ou abra o site externo.
• USER_CANCELED: não continua abrindo o site externo. Chame showExternalOfferInformationDialog() novamente para mostrar a caixa de diálogo de informações para o 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 ofertas 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 segundo caso, verifique o status de registro no 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 novamente.

Testar ofertas externas

Os testadores de licença precisam ser usados para testar a integração de ofertas externas. Você não vai receber cobranças por transações iniciadas por contas de testadores 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.