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 dar 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 requisitos do programa.

Configuração da Biblioteca Play Faturamento

Para usar as APIs de promoções externas, adicionar a versão 6.2.1 ou mais recente da dependência da Biblioteca Play Faturamento ao seu app Android. Se precisar migrar de uma versão anterior, siga siga as instruções do 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 o guia de integração de faturamento, com algumas modificações na inicializando o BillingClient:

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

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

Kotlin

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

Java

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 promoções externas estão disponíveis ligando para isExternalOfferAvailableAsync

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

Kotlin

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

Java

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 denunciar uma transação externa ao Google Play, você precisa ter um token de transação gerado na Biblioteca Play Faturamento. Um novo link externo token de transação deverá ser gerado sempre que o usuário acessar uma do site pela API de promoções externas. Para isso, chame o método API createExternalOfferReportingDetailsAsync. Esse token deve ser gerados imediatamente antes de o usuário ser direcionado para fora do aplicativo. Ele deveria nunca serão armazenados em cache, e um novo deverá ser gerado sempre que o usuário for direcionado fora do app.

Kotlin

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

Java

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 integração com promoções externas, seu app qualificado precisa mostrar uma informação que ajuda os usuários a entender que estão prestes a ser direcionados para fora o app a um site externo. A tela de informações precisa ser mostrada aos usuários chamar a API showExternalOfferInformationDialog antes de vincular a um oferta externa.

Kotlin

// 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)

Java

// 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 o método retornar BillingResponseCode.OK, o app poderá prosseguir para direcionar o usuário para um site externo. Se o método retornar BillingResponseCode.USER_CANCELED, o app não pode continuar abrindo o site.

Informar transações ao Google Play

Observação: consulte Como se inscrever no programa de promoções externas para ver transações. requisitos de relatórios.

Todas as transações externas precisam ser informadas ao Google Play chame a API Google Play Developer do back-end. Transações externas precisa ser informada, fornecendo uma externalTransactionToken recebido usando o API createExternalOfferReportingDetailsAsync. Se um usuário fizer vários é possível usar a mesma externalTransactionToken para registrar cada compra. Para saber como denunciar um 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 pode 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; abrir o site externo. Tente de novo chamando showExternalOfferInformationDialog() para mostrar as informações. para o usuário na próxima vez que tentar direcioná-lo para fora da app.
• FEATURE_NOT_SUPPORTED: as APIs de promoções externas não são compatíveis com Play Store no dispositivo atual. não prossiga com a transação; abrir o site externo.
• USER_CANCELED: não continua abrindo o site externo. Ligação showExternalOfferInformationDialog() novamente para mostrar as informações para o usuário na próxima vez que tentar direcioná-lo para fora do o app.
• BILLING_UNAVAILABLE: a transação não está qualificada para promoções externas e, portanto, não devem continuar neste programa. Isso ocorre porque o usuário não está em um país qualificado para este programa ou sua conta tem não foi inscrito no programa. Se for o último caso, verifique seu status de inscrição 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 devem ser tratados com uma política de nova tentativa apropriada. No caso de SERVICE_DISCONNECTED, restabeleça uma conexão com Google Play antes de tentar novamente.

Testar promoções externas

Os testadores de licença precisam ser usados para testar a integração de promoções externas. Você não serão faturadas por transações iniciadas pelo testador de licença contas de serviço. Consulte Testar o faturamento no app com o licenciamento de apps para mais informações. 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.