Orientações de integração no app para faturamento alternativo com escolha do usuário

Este guia descreve como integrar as APIs para oferecer um faturamento alternativo com escolha do usuário no seu app.

Configuração da Biblioteca Play Faturamento

Adicione a dependência da Biblioteca Play Faturamento ao seu app Android. Para usar as APIs de faturamento alternativo, você precisa usar a versão 5.2 ou mais recente. Se precisar migrar de uma versão anterior, siga as instruções no guia de migração antes de tentar implementar um faturamento alternativo.

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 você quer oferecer ao usuário várias opções de faturamento: enableUserChoiceBilling.
• É necessário registrar um UserChoiceBillingListener para processar casos em que o usuário escolhe um método de faturamento alternativo.

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

val purchasesUpdatedListener =
   PurchasesUpdatedListener { billingResult, purchases ->
       // Handle new Google Play purchase.
   }

val userChoiceBillingListener =
   UserChoiceBillingListener { userChoiceDetails ->
       // Handle alternative billing choice.
   }

var billingClient = BillingClient.newBuilder(context)
   .setListener(purchasesUpdatedListener)
   .enablePendingPurchases()
   .enableUserChoiceBilling(userChoiceBillingListener)
   .build()

private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
    @Override
    public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
        // Handle new Google Play purchase.
    }
};

private UserChoiceBillingListener userChoiceBillingListener = new UserChoiceBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
        UserChoiceDetails userChoiceDetails) {
        // Handle new Google Play purchase.
    }
};

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableUserChoiceBilling(userChoiceBillingListener)
    .build();

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

Mostrar produtos disponíveis

É possível mostrar produtos disponíveis para o usuário da mesma forma que faria com uma integração do sistema de faturamento do Google Play. Quando o usuário encontrar os produtos disponíveis e selecionar um para comprar, inicie o fluxo de escolha de faturamento do usuário, conforme descrito na próxima seção.

Iniciar o fluxo de escolha de faturamento do usuário

Inicie o fluxo de escolha de faturamento do usuário chamando launchBillingFlow(). Isso funciona da mesma forma que iniciar um fluxo de compra com uma integração do sistema de faturamento do Google Play: você fornece uma instância de ProductDetails e um offerToken correspondente ao produto e à oferta que o usuário quer adquirir. Se o usuário escolher o sistema de faturamento do Google Play, essas informações serão usadas para continuar o fluxo de compra.

Quando os desenvolvedores chamam launchBillingFlow(), o sistema de faturamento do Google Play segue esta lógica:

• O sistema verifica se o país do Google Play do usuário oferece suporte ao faturamento alternativo com escolha do usuário (ou seja, um país com suporte). Em caso positivo, o Google Play vai verificar se o faturamento alternativo foi ativado com base na configuração do BillingClient.
  • Se o faturamento alternativo com a escolha do usuário tiver sido ativado, o fluxo de compra vai mostrar a UX da escolha do usuário.
  • Se o faturamento alternativo com a escolha do usuário não estiver ativado, o fluxo de compra vai mostrar a UX padrão do sistema de faturamento do Google Play, sem a escolha do usuário.
• Se o país do Google Play do usuário não tiver suporte, o fluxo de compra vai mostrar a UX padrão do sistema de faturamento do Google Play, sem escolha do usuário.

Processar a seleção do usuário

A forma como você lida com o restante do fluxo de compra varia dependendo do usuário ter selecionado o sistema de faturamento do Google Play ou um sistema alternativo de faturamento.

Quando o usuário seleciona um sistema alternativo de faturamento

Se o usuário escolher o sistema alternativo de faturamento, o Google Play vai chamar o UserChoiceBillingListener para notificar o app de que ele precisa iniciar o fluxo de compra nesse sistema. Mais especificamente, o método userSelectedAlternativeBilling() é chamado.

O token de transação externa fornecido no objeto UserChoiceDetails representa uma assinatura para que o usuário escolha o fluxo de faturamento alternativo. Use esse token para informar qualquer transação resultante dessa opção, conforme explicado no guia de integração de back-end.

O UserChoiceBillingListener precisa realizar as ações abaixo:

• Extrair os produtos que estão sendo comprados pelo usuário para que possam ser apresentados no fluxo de compra no sistema alternativo de faturamento.
• Coletar a string recebida como o token de transação externa e enviar ao back-end para armazenar o token. Ele será usado mais tarde para informar a transação externa ao Google Play se o usuário concluir essa compra específica.
• Iniciar o fluxo de compra alternativo do desenvolvedor.

Se o usuário concluir a compra usando o sistema alternativo de faturamento, informe a transação ao Google Play chamando a API Google Play Developer pelo back-end em até 24 horas, fornecendo o externalTransactionToken e outros detalhes da transação. Consulte o guia de integração de back-end para mais detalhes.

O exemplo abaixo demonstra como implementar o UserChoiceBillingListener:

private val userChoiceBillingListener =
    UserChoiceBillingListener { userChoiceDetails ->
        // Get the products being purchased by the user.
        val products = userChoiceDetails.products

        // Send external transaction token to developer backend server
        // this devBackend object is for demonstration purposes,
        // developers can implement this step however best fits their
        // app to backend communication.
        devBackend.sendExternalTransactionStarted(
            userChoiceDetails.externalTransactionToken,
            user
        )

        // Launch alternative billing
        // ...
        // The developer backend handles reporting the transaction
        // to Google Play's backend once the alternative billing
        // purchase is completed.
    }

private userChoiceBillingListener userChoiceBillingListener = new UserChoiceBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
           UserChoiceDetails userChoiceDetails) {
       // Get the products being purchased by the user.
       List<Product> products =
              userChoiceDetails.getProducts();

       // Send external transaction token to developer backend server
       // this devBackend object is for demonstration purposes,
       // developers can implement this step however best fits their
       // app to backend communication.
       devBackend.sendExternalTransactionStarted(
              userChoiceDetails.getExternalTransactionToken(),
              user
       );

       // Launch alternative billing
       // ...
       // The developer backend handles reporting the transaction
       // to Google Play's backend once the alternative billing
       // purchase is completed.
    }
};

Quando o usuário seleciona o sistema de faturamento do Google Play

Se o usuário escolher o sistema de faturamento do Google Play, ele vai continuar com o fluxo de compra.

• Consulte Como processar compras no guia de integração da biblioteca para mais informações sobre como processar novas compras no app usando o sistema de faturamento do Google Play.
• Consulte Novas assinaturas no guia de gerenciamento de assinatura para outras orientações sobre compras de assinaturas.

Processar mudanças na assinatura

Para desenvolvedores que usam o faturamento alternativo com escolha do usuário, as compras precisam ser processadas pelo sistema de faturamento do Google Play ou informadas com um externalTransactionId, dependendo da escolha do usuário. As mudanças em assinaturas existentes que foram processadas pelo fluxo de escolha do usuário podem ser feitas pelo mesmo sistema de faturamento até a expiração.

Esta seção descreve como lidar com alguns cenários comuns de mudança de assinatura.

Fazer upgrade e downgrade de fluxos

Mudanças no plano de assinatura, incluindo fluxos de upgrade e downgrade, precisam ser processadas de maneira diferente, dependendo se a assinatura foi comprada originalmente pelo sistema de faturamento do Google Play ou por um sistema alternativo.

Complementos que dependem de uma assinatura atual, compartilham a mesma forma de pagamento e alinham cobranças recorrentes são tratados como upgrades. Para outros complementos, os usuários precisam escolher qual sistema de faturamento querem usar. Inicie uma nova experiência de compra usando launchBillingFlow(), conforme descrito em Iniciar o fluxo de escolha de faturamento do usuário.

Assinaturas compradas usando um sistema alternativo de faturamento

Para assinaturas que foram compradas originalmente no sistema alternativo de faturamento do desenvolvedor após a escolha do usuário, aqueles que solicitarem um upgrade ou downgrade vão passar pelo mesmo sistema sem precisar passar pela experiência de escolha do usuário de novo.

Para fazer isso, chame launchBillingFlow() quando o usuário solicitar um upgrade ou downgrade. Em vez de especificar um objeto SubscriptionUpdateParams nos parâmetros, use setOriginalExternalTransactionId, fornecendo o ID da transação externa para a compra original. Isso não mostra a tela de escolha do usuário, já que a escolha original é preservada para upgrades e downgrades. Nesse caso, a chamada para launchBillingFlow() gera um novo token de transação externa, que pode ser extraído do callback.

// The external transaction ID from the current
// alternative billing subscription.
val externalTransactionId = //... ;

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                // Fetched via queryProductDetailsAsync.
                .setProductDetails(productDetailsNewPlan)
                // offerIdToken can be found in
                // ProductDetails=>SubscriptionOfferDetails.
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOriginalExternalTransactionId(externalTransactionId)
            .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

// When the user selects the alternative billing flow,
// the UserChoiceBillingListener is triggered.

// The external transaction ID from the current
// alternative billing subscription.
String externalTransactionId = //... ;

BillingFlowParams billingFlowParams =
        BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(
                ImmutableList.of(
                    ProductDetailsParams.newBuilder()
                        // Fetched via queryProductDetailsAsync.
                        .setProductDetails(productDetailsNewPlan)
                        // offerIdToken can be found in
                        // ProductDetails=>SubscriptionOfferDetails
                        .setOfferToken(offerTokenNewPlan)
                    .build()
                )
            )
            .setSubscriptionUpdateParams(
                SubscriptionUpdateParams.newBuilder()
                    .setOriginalExternalTransactionId(externalTransactionId)
                    .build()
            )
            .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

// When the user selects the alternative billing flow,
// the UserChoiceBillingListener is triggered.

Quando o upgrade ou downgrade for concluído no sistema alternativo de faturamento, você precisará informar uma nova transação usando o token de transação externa recebido na chamada anterior para a nova compra da assinatura.

Assinaturas compradas usando o sistema de faturamento do Google Play

Da mesma forma, é preciso mostrar o fluxo de upgrade ou downgrade no sistema de faturamento do Google Play aos usuários que compraram a assinatura atual pelo sistema de faturamento do Google Play após a escolha do usuário. As instruções abaixo descrevem como iniciar o fluxo de compra para um upgrade ou downgrade pelo sistema de faturamento do Google Play:

1. Identifique o offerToken da oferta selecionada para o novo plano:

val offerTokenNewPlan = productDetailsNewPlan
             .getSubscriptionOfferDetails(selectedOfferIndex)
             .getOfferToken()

String offerTokenNewPlan = productDetailsNewPlan
                     .getSubscriptionOfferDetails(selectedOfferIndex)
                     .getOfferToken();

1. Envie as informações corretas ao sistema de faturamento do Google Play para processar a nova compra, incluindo o token de compra da assinatura atual:

val billingFlowParams =
    BillingFlowParams.newBuilder().setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                .setProductDetails(productDetailsNewPlan)
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOldPurchaseToken(oldToken)
            .setReplaceProrationMode(BillingFlowParams.ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
            .build()
        )
        .build()

BillingClient.launchBillingFlow(activity, billingFlowParams)

BillingFlowParams billingFlowParams =
        BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(
                ImmutableList.of(
                    ProductDetailsParams.newBuilder()
                        // Fetched via queryProductDetailsAsync
                        .setProductDetails(productDetailsNewPlan)
                        // offerIdToken can be found in
                        // ProductDetails=>SubscriptionOfferDetails.
                        .setOfferToken(offerTokenNewPlan)
                        .build()
                )
            )
            .setSubscriptionUpdateParams(
                SubscriptionUpdateParams.newBuilder()
                    // purchaseToken can be found in
                    // Purchase#getPurchaseToken
                    .setOldPurchaseToken("old_purchase_token")
                    .setReplaceProrationMode(ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
                    .build()
            )
            .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

Essa compra é realizada no sistema de faturamento do Google Play e o app recebe a chamada PurchasesUpdatedListener.onPurchaseUpdated com o resultado da compra. Se a compra for concluída, o método onPurchaseUpdated() também receberá as novas informações de compra e seu back-end receberá uma Notificação do desenvolvedor em tempo real SUBSCRIPTION_PURCHASED. Ao receber o status da nova compra, um atributo linkedPurchaseToken será vinculado à compra da assinatura antiga para que você possa desativá-la conforme recomendado (link em inglês).

Cancelamentos e restaurações de assinaturas

Os usuários podem cancelar a assinatura quando quiserem. Quando um usuário cancela uma assinatura, a rescisão do direito de acesso pode ser adiada até o término do período pago. Por exemplo, se um usuário cancelar uma assinatura mensal na metade do mês, ele poderá continuar acessando o serviço por aproximadamente duas semanas até perder o acesso. Durante esse período, a assinatura ainda está tecnicamente ativa, ou seja, o usuário pode usar o serviço.

Várias vezes os usuários decidem reverter o cancelamento durante esse período ativo. Neste guia, isso é chamado de restauração. As próximas seções descrevem como lidar com cenários de restauração na integração da API de faturamento alternativo.

Assinaturas compradas usando um sistema alternativo de faturamento

Se você tiver um ID de transação externa para uma assinatura cancelada, não será necessário chamar o launchBillingFlow() para restaurar a assinatura. Ele não pode ser usado para esse tipo de ativação. Se o usuário restaurar a assinatura enquanto ainda estiver no período ativo de uma assinatura cancelada, nenhuma transação vai ocorrer nesse momento. Será possível continuar gerando relatórios sobre renovações quando o ciclo atual expirar e a próxima renovação ocorrer. Isso inclui casos em que o usuário recebe um crédito ou preço especial de renovação como parte da restauração (por exemplo, uma promoção para incentivar o usuário a manter a assinatura).

Assinaturas compradas usando o sistema de faturamento do Google Play

Geralmente, os usuários podem restaurar assinaturas no sistema de faturamento do Google Play. Para assinaturas canceladas que foram originalmente compradas no sistema de faturamento do Google Play, o usuário pode desfazer o cancelamento enquanto a assinatura estiver ativa usando o recurso Renovar assinatura. Nesse caso, você recebe uma Notificação do desenvolvedor em tempo real SUBSCRIPTION_RESTARTED no seu back-end e um novo token de compra não é emitido. O token original é usado para manter a assinatura. Para saber como gerenciar a restauração no sistema de faturamento do Google Play, consulte Restaurações no guia de gerenciamento de assinaturas.

Também é possível acionar uma restauração no sistema de faturamento do Google Play pelo app chamando launchBillingFlow(). Consulte Antes da expiração da assinatura: no app para conferir uma explicação sobre como fazer isso. No caso de usuários que passaram pelo fluxo de escolha do usuário para a compra original (que foi cancelada, mas ainda está ativa), o sistema detecta automaticamente a escolha e mostra a interface do usuário para restaurar essas compras. É preciso confirmar a recompra da assinatura no Google Play, mas não é necessário passar pelo fluxo de escolha do usuário de novo. Nesse caso, um novo token de compra é emitido para o usuário. Seu back-end recebe uma Notificação do desenvolvedor em tempo real de SUBSCRIPTION_PURCHASED e o valor linkedPurchaseToken do novo status de compra é definido, como no caso de upgrade ou downgrade com o token da compra antiga da assinatura que foi cancelada.

Renovações de assinatura

Se uma assinatura expirar completamente, seja por cancelamento ou pagamento recusado sem recuperação (uma suspensão de conta expirada), o usuário vai precisar renovar assinatura para recuperar o direito de acesso.

A renovação de uma assinatura também pode ser ativada pelo app, de forma semelhante a uma assinatura padrão. Os usuários precisam ser capazes de escolher qual sistema de faturamento querem usar. O launchBillingFlow() pode ser chamado nesse caso, conforme descrito em Iniciar o fluxo de escolha de faturamento do usuário.

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.