Orientações de integração no app somente para faturamento alternativo

Este guia descreve como integrar as APIs para oferecer o faturamento alternativo exclusivo (ou seja, sem escolha do usuário) em apps qualificados. Para saber mais sobre esses programas, incluindo os requisitos de qualificação e o escopo geográfico, consulte Sobre o faturamento alternativo.

Configuração da Biblioteca Play Faturamento

Adicione a dependência da Biblioteca Play Faturamento ao seu app Android. Para aproveitar as APIs de faturamento alternativo, você precisa usar a versão 6.1 ou mais recente.

Conectar ao Google Play

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

• É necessário chamar um novo método para indicar que seu app usa apenas o sistema alternativo de faturamento: enableAlternativeBillingOnly.

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

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

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableAlternativeBillingOnly()
    .build();

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

Como verificar a disponibilidade

Seu app precisa confirmar se apenas o faturamento alternativo está disponível chamando isAlternativeBillingOnlyAvailableAsync.

Essa API retornará BillingResponseCode.OK se apenas o faturamento alternativo estiver disponível. Consulte o processamento de respostas para mais detalhes sobre como seu app precisa responder a outros códigos de resposta.

billingClient.isAlternativeBillingOnlyAvailableAsync(object:
    AlternativeBillingOnlyAvailabilityListener {
        override fun onAlternativeBillingOnlyAvailabilityResponse(
            billingResult: BillingResult) {
            if (billingResult.responseCode !=  BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors,
                // handling alternative billing only being unavailable, etc.
                return
            }

            // Alternative billing only is available. Continue with steps in
            // the guide.
        }
    });

billingClient.isAlternativeBillingOnlyAvailable(
    new AlternativeBillingOnlyAvailabilityListener() {
        @Override
        public void onAlternativeBillingOnlyAvailabilityResponse(
            BillingResult billingResult) {
            if (billingResult.getResponseCode() != BillingResponseCode.OK) {
                 // Handle failures such as retrying due to network errors,
                 // handling alternative billing only being unavailable,
                 // etc.
                return;
            }

            // Alternative billing only is available. Continue with steps in
            // the guide.
        }
    });

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

Para integrar apenas o faturamento alternativo, o app qualificado precisa mostrar uma tela de informações que ajude os usuários a entender que o faturamento não será gerenciado pelo Google Play. A tela de informações precisa ser mostrada aos usuários chamando a API showAlternativeBillingOnlyInformationDialog antes de iniciar o fluxo de faturamento alternativo toda vez. Se o usuário já tiver confirmado a caixa de diálogo, o uso dessa API normalmente não fará com que ela seja mostrada de novo. Pode haver momentos em que a caixa de diálogo é mostrada de novo para um usuário em algumas situações, por exemplo, quando o usuário limpa os caches no dispositivo.

// An activity reference from which the alternative billing only information
// dialog will be launched.
val activity : Activity = ...;

val listener : AlternativeBillingOnlyInformationDialogListener =
    AlternativeBillingOnlyInformationDialogListener { 
        override fun onAlternativeBillingOnlyInformationDialogResponse(
            billingResult: BillingResult) {
            // check billingResult
        }
}

val billingResult =
    billingClient.showAlternativeBillingOnlyInformationDialog(activity,
        listener)

// An activity reference from which the alternative billing only information
// dialog will be launched.
Activity activity = ...;

AlternativeBillingOnlyInformationDialogListener listener =
    new AlternativeBillingOnlyInformationDialogListener() {
        @Override
        public void onAlternativeBillingOnlyInformationDialogResponse(
            BillingResult billingResult) {
                // check billingResult
            }
    };

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

Se esse método retornar BillingResponseCode.OK, seu app poderá prosseguir com a transação. No caso de BillingResponseCode.USER_CANCELED, seu app precisa chamar showAlternativeBillingOnlyInformationDialog para mostrar a caixa de diálogo ao usuário de novo. Para outros códigos de resposta, consulte a seção Processamento de respostas.

Como informar transações ao Google Play

Todas as transações feitas por um sistema alternativo de faturamento precisam ser informadas ao Google Play chamando a API Google Play Developer pelo back-end em até 24 horas, fornecendo um externalTransactionToken que é recebido usando a API descrita abaixo. Um novo externalTransactionToken precisa ser gerado para cada compra única, cada nova assinatura e para qualquer upgrade/downgrade para uma assinatura existente. Para saber como informar uma transação depois que um externalTransactionToken for recebido, consulte o guia de integração de back-end.

billingClient.createAlternativeBillingOnlyReportingDetailsAsync(object:
    AlternativeBillingOnlyReportingDetailsListener {
        override fun onAlternativeBillingOnlyTokenResponse(
            billingResult: BillingResult,
            alternativeBillingOnlyReportingDetails:
                AlternativeBillingOnlyReportingDetails?) {
            if (billingResult.responseCode !=  BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors.
                return
            }

            val externalTransactionToken =
                alternativeBillingOnlyReportingDetails?
                    .externalTransactionToken

            // Send transaction token to backend and report to Google Play.
        }
    });

billingClient.createAlternativeBillingOnlyReportingDetailsAsync(
    new AlternativeBillingOnlyReportingDetailsListener() {
        @Override
        public void onAlternativeBillingOnlyTokenResponse(
            BillingResult billingResult,
            @Nullable AlternativeBillingOnlyReportingDetails
                alternativeBillingOnlyReportingDetails) {
            if (billingResult.getResponseCode() != BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors.
                return;
            }

            String transactionToken =
                alternativeBillingOnlyReportingDetails
                .getExternalTransactionToken();

            // Send transaction token to backend and report to Google Play.
        }
    });

Processamento de respostas

Os métodos acima, isAlternativeBillingOnlyAvailableAsync(), showAlternativeBillingOnlyInformationDialog() e createAlternativeBillingOnlyReportingDetailsAsync(), podem retornar respostas que não são de BillingResponseCode.OK em caso de erros. O processamento recomendado dos erros é descrito abaixo:

• ERROR: este é um erro interno. Prossiga com o processamento da transação usando o sistema alternativo de faturamento. A transação não precisa ser informada ao Google, incluindo renovações das assinaturas afetadas.
• FEATURE_NOT_SUPPORTED: as APIs de faturamento alternativo não oferecem suporte à Play Store no dispositivo atual. Prossiga com o processamento da transação pelo sistema alternativo de faturamento. A transação não precisa ser informada ao Google nem as renovações das assinaturas afetadas.
• USER_CANCELED: chame showAlternativeBillingOnlyInformationDialog() de novo para mostrar a caixa de diálogo de informações ao usuário na próxima vez que ele tentar fazer uma compra.
• BILLING_UNAVAILABLE: a transação não está qualificada para faturamento alternativo exclusivo 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. É preciso tentar fazer a solicitação novamente. No caso de SERVICE_DISCONNECTED, restabeleça uma conexão com o Google Play antes de tentar de novo.

Testar o faturamento alternativo

Use os testadores de licença para testar a integração do faturamento alternativo. 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.