Orientações de integração no app para faturamento alternativo (somente na Coreia do Sul)

Neste guia, descrevemos como integrar as APIs de faturamento alternativo ao 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: enableAlternativeBilling.
  • É necessário registrar um AlternativeBillingListener 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:

Kotlin

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

val alternativeBillingListener =
   AlternativeBillingListener { alternateChoiceDetails ->
       // Handle alternative billing choice.
   }

var billingClient = BillingClient.newBuilder(context)
   .setListener(purchasesUpdatedListener)
   .enablePendingPurchases()
   .enableAlternativeBilling(alternativeBillingListener)
   .build()

Java

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

private AlternativeBillingListener alternativeBillingListener = new AlternativeBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
        AlternativeChoiceDetails alternateChoiceDetails) {
        // Handle new Google Play purchase.
    }
};

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableAlternativeBilling(alternativeBillingListener)
    .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 para 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 é a Coreia do Sul. Em caso positivo, o Google Play vai verificar se o faturamento alternativo foi ativado com base na configuração de BillingClient.

    • Se o faturamento alternativo tiver sido ativado, o fluxo de compra vai mostrar a nova UX.
    • Se o faturamento alternativo não estiver ativado, o fluxo de compra vai mostrar a UX padrão do sistema de faturamento do Google Play, sem escolha do usuário.

  • Se o país do Google Play do usuário não for a Coreia do Sul, o fluxo de compra mostrará a UX padrão do sistema de faturamento, sem escolha do usuário.

O país do Google Play do usuário é a Coreia do Sul O país do Google Play do usuário não é a Coreia do Sul
enableAlternativeBilling é chamado durante a configuração do BillingClient A nova UX aparece para o usuário A UX padrão do sistema de faturamento do Google Play aparece para o usuário
enableAlternativeBilling não é chamado durante a configuração do BillingClient A UX padrão do sistema de faturamento do Google Play aparece para o usuário A UX padrão do sistema de faturamento do Google Play aparece para o 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 AlternativeBillingListener 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 AlternativeChoiceDetails 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 AlternativeBillingListener 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 do desenvolvedor, você precisará informar a transação ao Google Play chamando a API Google Play Developer pelo back-end, 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 AlternativeBillingListener:

Kotlin

private val alternativeBillingListener =
    AlternativeBillingListener { alternativeChoiceDetails ->
        // Get the products being purchased by the user.
        val products = alternativeChoiceDetails.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(
            alternativeChoiceDetails.externalTransactionToken,
            user
        )

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

Java

private AlternativeBillingListener alternativeBillingListener = new AlternativeBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
           AlternativeChoiceDetails alternateChoiceDetails) {
       // Get the products being purchased by the user.
       List<Product> products =
              alternativeChoiceDetails.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(
              alternateChoiceDetails.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 um sistema alternativo de faturamento, as compras precisam ser processadas pelo sistema 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.

Fluxos de upgrade e downgrade

Os fluxos de upgrade e downgrade precisam ser tratados de maneira diferente, dependendo da assinatura ter sido comprada originalmente pelo sistema de faturamento do Google Play ou por um sistema alternativo.

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.

Kotlin

// 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 AlternativeBillingListener is triggered.

Java

// 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 AlternativeBillingListener is triggered.

Quando o upgrade ou downgrade for concluído no sistema alternativo de faturamento, você vai 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:

    Kotlin

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

    Java

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

  2. 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:

    Kotlin

    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)

    Java

    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 foi bem-sucedida, o método onPurchaseUpdated também recebe as novas informações de compra e seu back-end recebe uma Notificação do desenvolvedor em tempo real SUBSCRIPTION_PURCHASED. Ao receber o status da nova compra, um atributo linkedPurchaseToken é vinculado à compra da assinatura antiga para que você possa aposentá-la conforme recomendado.

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 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 vai 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.

Próximas etapas

Depois de concluir a integração no app, estará tudo pronto para integrar seu back-end.