Integrar a Biblioteca Play Faturamento ao seu app

Este documento descreve como integrar a Biblioteca Play Faturamento ao seu app para começar a vender produtos.

O ciclo de uma compra

Veja um fluxo de compra típico para uma compra única ou assinatura.

1. Mostre ao usuário o que ele pode comprar.
2. Inicie o fluxo de compra para que o usuário a aceite.
3. Verifique a compra no seu servidor.
4. Forneça conteúdo ao usuário.
5. Confirme a entrega do conteúdo. Para produtos de consumo, consuma a compra para que o usuário possa comprar o item de novo.

As assinaturas são renovadas automaticamente até que sejam canceladas. Uma assinatura pode passar pelos seguintes estados:

• Ativa: o usuário está em situação regular e tem acesso à assinatura.
• Cancelada: o usuário cancelou, mas ainda tem acesso até o vencimento.
• Em período de carência: o usuário teve um problema com o pagamento, mas ainda tem acesso enquanto o Google tenta executar a forma de pagamento de novo.
• Suspensa: o usuário teve um problema com o pagamento e não tem mais acesso enquanto o Google tenta executar a forma de pagamento de novo.
• Pausada: o usuário pausou e não tem acesso até retomar.
• Vencida: o usuário cancelou a assinatura e perdeu o acesso. O usuário é considerado desligado na data do vencimento.

Inicializar uma conexão com o Google Play

A primeira etapa para fazer a integração do sistema de faturamento do Google Play é adicionar a Biblioteca Google Play Faturamento ao seu app e inicializar uma conexão.

Adicionar a dependência da Biblioteca Google Play Faturamento

Adicione a dependência da Biblioteca Google Play Faturamento ao arquivo build.gradle do seu app desta forma:

dependencies {
    def billing_version = "8.0.0"

    implementation "com.android.billingclient:billing:$billing_version"
}

dependencies {
    val billing_version = "8.0.0"

    implementation("com.android.billingclient:billing:$billing_version")
}

Se você usa o Kotlin, o módulo KTX da Biblioteca Google Play Faturamento oferece suporte a extensões e corrotinas de Kotlin que permitem escrever Kotlin idiomático ao usar a Biblioteca Google Play Faturamento. Para incluir essas extensões no projeto, adicione esta dependência ao arquivo build.gradle do app, como mostrado:

dependencies {
    def billing_version = "8.0.0"

    implementation "com.android.billingclient:billing-ktx:$billing_version"
}

dependencies {
    val billing_version = "8.0.0"

    implementation("com.android.billingclient:billing-ktx:$billing_version")
}

Inicializar um BillingClient

Depois de adicionar uma dependência à Biblioteca Google Play Faturamento, você precisa inicializar uma instância de BillingClient, BillingClient é a interface principal de comunicação entre a biblioteca do Google Play Faturamento e o restante do app. O BillingClient fornece métodos de conveniência, síncronos e assíncronos, para muitas operações de faturamento comuns. Anote o seguinte:

• É recomendável ter uma conexão BillingClient ativa aberta ao mesmo tempo para evitar vários callbacks de PurchasesUpdatedListener para um único evento.
• É recomendável iniciar uma conexão para o BillingClient quando o app for iniciado ou entrar em primeiro plano para garantir que ele processe as compras em tempo hábil. Isso pode ser feito usando ActivityLifecycleCallbacks registrado por registerActivityLifecycleCallbacks e detectando onActivityResumed para inicializar uma conexão quando você detectar uma atividade sendo retomada. Consulte a seção sobre processamento de compras para mais detalhes sobre por que essa prática recomendada precisa ser seguida. Além disso, não se esqueça de encerrar a conexão quando o app for fechado.

Para criar um BillingClient, use newBuilder. Você pode transmitir qualquer contexto para newBuilder(), e ele será usado pelo BillingClient para ter um contexto de aplicativo. Ou seja, você não precisa se preocupar com vazamentos de memória. Para receber atualizações sobre compras, chame também setListener, transmitindo uma referência para um PurchasesUpdatedListener. Esse listener recebe atualizações para todas as compras no seu app.

private val purchasesUpdatedListener =
   PurchasesUpdatedListener { billingResult, purchases ->
       // To be implemented in a later section.
   }

private var billingClient = BillingClient.newBuilder(context)
   .setListener(purchasesUpdatedListener)
   // Configure other settings.
   .build()

private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
    @Override
    public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
        // To be implemented in a later section.
    }
};

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    // Configure other settings.
    .build();

Conectar ao Google Play

Depois de criar um BillingClient, você precisa estabelecer uma conexão com o Google Play.

Para se conectar ao Google Play, chame startConnection. O processo de conexão é assíncrono, e é necessário implementar um BillingClientStateListener para receber um callback assim que a configuração do cliente for concluída e estiver pronta para fazer mais solicitações.

Também é necessário implementar a lógica de nova tentativa para gerenciar as conexões perdidas com o Google Play. Para implementar essa lógica, substitua o método de callback onBillingServiceDisconnected() e confira se o BillingClient chama o método startConnection() para se reconectar ao Google Play antes de fazer outras solicitações.

O exemplo abaixo demonstra como iniciar uma conexão e testar se ela está pronta para uso:

billingClient.startConnection(object : BillingClientStateListener {
    override fun onBillingSetupFinished(billingResult: BillingResult) {
        if (billingResult.responseCode ==  BillingResponseCode.OK) {
            // The BillingClient is ready. You can query purchases here.
        }
    }
    override fun onBillingServiceDisconnected() {
        // Try to restart the connection on the next request to
        // Google Play by calling the startConnection() method.
    }
})

billingClient.startConnection(new BillingClientStateListener() {
    @Override
    public void onBillingSetupFinished(BillingResult billingResult) {
        if (billingResult.getResponseCode() ==  BillingResponseCode.OK) {
            // The BillingClient is ready. You can query purchases here.
        }
    }
    @Override
    public void onBillingServiceDisconnected() {
        // Try to restart the connection on the next request to
        // Google Play by calling the startConnection() method.
    }
});

Restabelecer uma conexão automaticamente

Com a introdução do método enableAutoServiceReconnection() em BillingClient.Builder na versão 8.0.0, a biblioteca Play Faturamento agora pode reestabelecer automaticamente a conexão do serviço se uma chamada de API for feita enquanto o serviço estiver desconectado. Isso pode levar a uma redução nas respostas SERVICE_DISCONNECTED, já que a reconexão é processada internamente antes da chamada de API.

Como ativar a reconexão automática

Ao criar uma instância BillingClient, use o método enableAutoServiceReconnection() no BillingClient.Builder para ativar a reconexão automática.

val billingClient = BillingClient.newBuilder(context)
    .setListener(listener)
    .enablePendingPurchases()
    .enableAutoServiceReconnection() // Add this line to enable reconnection
    .build()

BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(listener)
    .enablePendingPurchases()
    .enableAutoServiceReconnection() // Add this line to enable reconnection
    .build();

Mostrar produtos disponíveis para compra

Depois de estabelecer uma conexão com o Google Play, estará tudo pronto para você consultar seus produtos disponíveis e mostrá-los aos usuários.

Consultar detalhes do produto é uma etapa importante antes de mostrar seus produtos para os usuários, já que retorna informações localizadas do produto. Para assinaturas, verifique se a exibição do produto segue todas as políticas do Google Play.

Para consultar detalhes de produtos únicos, chame o método queryProductDetailsAsync. Esse método pode retornar várias ofertas com base na configuração do produto de aquisição única. Para mais informações, consulte Várias opções de compra e ofertas para produtos únicos.

Para gerenciar o resultado da operação assíncrona, você também precisa especificar um listener que implemente a interface ProductDetailsResponseListener. Em seguida, você pode substituir onProductDetailsResponse, que notifica o listener quando a consulta é concluída, conforme mostrado neste exemplo:

val queryProductDetailsParams =
    QueryProductDetailsParams.newBuilder()
        .setProductList(
            ImmutableList.of(
                Product.newBuilder()
                    .setProductId("product_id_example")
                    .setProductType(ProductType.SUBS)
                    .build()))
        .build()

billingClient.queryProductDetailsAsync(queryProductDetailsParams) {
    billingResult,
    queryProductDetailsResult ->
      if (billingResult.getResponseCode() == BillingResponseCode.OK) {
               for (ProductDetails productDetails : queryProductDetailsResult.getProductDetailsList()) {
                 // Process successfully retrieved product details here.
               }

               for (UnfetchedProduct unfetchedProduct : queryproductDetailsResult.getUnfetchedProductList()) {
                 // Handle any unfetched products as appropriate.
               }
            }
}

QueryProductDetailsParams queryProductDetailsParams =
    QueryProductDetailsParams.newBuilder()
        .setProductList(
            ImmutableList.of(
                Product.newBuilder()
                    .setProductId("product_id_example")
                    .setProductType(ProductType.SUBS)
                    .build()))
        .build();

billingClient.queryProductDetailsAsync(
    queryProductDetailsParams,
    new ProductDetailsResponseListener() {
        public void onProductDetailsResponse(BillingResult billingResult,
                QueryProductDetailsResult queryProductDetailsResult) {
            if (billingResult.getResponseCode() == BillingResponseCode.OK) {
               for (ProductDetails productDetails : queryProductDetailsResult().getProductDetailsList()) {
                 // Process success retrieved product details here.
               }

               for (UnfetchedProduct unfetchedProduct : queryproductDetailsResult.getUnfetchedProductList()) {
                 // Handle any unfetched products as appropriate.
               }
            }
        }
    }
)

Ao consultar detalhes do produto, transmita uma instância de QueryProductDetailsParams que especifique uma lista de strings de ID do produto criadas no Google Play Console e um ProductType. O ProductType pode ser ProductType.INAPP para produtos únicos ou ProductType.SUBS para assinaturas.

Consultar com extensões do Kotlin

Se você usa as extensões do Kotlin, pode consultar os detalhes de produtos únicos chamando a função de extensão queryProductDetails().

A função queryProductDetails() usa as corrotinas do Kotlin para que você não precise definir um listener separado. Em vez disso, a função é suspensa até que a consulta seja concluída. Depois, é possível processar o resultado:

suspend fun processPurchases() {
    val productList = listOf(
        QueryProductDetailsParams.Product.newBuilder()
            .setProductId("product_id_example")
            .setProductType(BillingClient.ProductType.SUBS)
            .build()
    )
    val params = QueryProductDetailsParams.newBuilder()
    params.setProductList(productList)

    // leverage queryProductDetails Kotlin extension function
    val productDetailsResult = withContext(Dispatchers.IO) {
        billingClient.queryProductDetails(params.build())
    }

    // Process the result.
}

Em casos raros, alguns dispositivos não oferecem suporte a ProductDetails e queryProductDetailsAsync(). Isso costuma ocorrer devido a versões desatualizadas do Google Play Services. Para oferecer suporte adequado a esse cenário, aprenda a usar os recursos de compatibilidade com versões anteriores no guia de migração da Biblioteca Play Faturamento 7.

Processar o resultado

A Biblioteca Google Play Faturamento armazena os resultados da consulta em um objeto QueryProductDetailsResult. QueryProductDetailsResult contém um List de objetos ProductDetails. Depois disso, você pode chamar uma variedade de métodos em cada objeto ProductDetails da lista para conferir informações relevantes sobre um produto único buscado com sucesso, como o preço ou a descrição. Para conferir as informações de detalhes do produto disponíveis, consulte a lista de métodos na classe ProductDetails.

QueryProductDetailsResult também contém um List de objetos UnfetchedProduct. Em seguida, você pode consultar cada UnfetchedProduct para receber um código de status correspondente ao motivo da falha de busca. Para conferir as informações de produtos não buscados disponíveis, consulte a lista de métodos na classe UnfetchedProduct.

Antes de oferecer um item para venda, confira se o usuário ainda não tem o item. Se o usuário tiver um produto de consumo que ainda está na biblioteca de itens, ele precisará consumir o item antes de comprá-lo de novo.

Antes de oferecer uma assinatura, verifique se o usuário ainda não é assinante. Observe também o seguinte:

• Para assinaturas, o método queryProductDetailsAsync() retorna detalhes do produto por assinatura e um máximo de 50 ofertas qualificadas por assinatura. Se o usuário tentar comprar uma oferta não qualificada (por exemplo, se o app estiver mostrando uma lista desatualizada de ofertas qualificadas), o Google Play vai informar sobre a não qualificação e o usuário poderá comprar o plano básico.

• Para produtos únicos, o método queryProductDetailsAsync() retorna apenas as ofertas qualificadas do usuário. Se o usuário tentar comprar uma oferta para a qual não está qualificado (por exemplo, se o usuário tiver atingido o limite de quantidade de compra), o Google Play vai informar sobre a não qualificação e avisar que o usuário pode comprar a opção de compra.

Iniciar o fluxo de compra

Para iniciar um pedido de aprovação de compra no seu app, chame o método launchBillingFlow() na linha de execução principal do app. Esse método usa uma referência a um objeto BillingFlowParams que contém o objeto ProductDetails relevante recebido ao chamar queryProductDetailsAsync. Para criar um objeto BillingFlowParams, use a classe BillingFlowParams.Builder.

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...;

val productDetailsParamsList = listOf(
    BillingFlowParams.ProductDetailsParams.newBuilder()
        // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
        .setProductDetails(productDetails)
        // Get the offer token:
        // a. For one-time products, call ProductDetails.getOneTimePurchaseOfferDetailsList()
        // for a list of offers that are available to the user.
        // b. For subscriptions, call ProductDetails.subscriptionOfferDetails()
        // for a list of offers that are available to the user.
        .setOfferToken(selectedOfferToken)
        .build()
)

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(productDetailsParamsList)
    .build()

// Launch the billing flow
val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

// An activity reference from which the billing flow will be launched.
Activity activity = ...;

ImmutableList<ProductDetailsParams> productDetailsParamsList =
    ImmutableList.of(
        ProductDetailsParams.newBuilder()
             // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
            .setProductDetails(productDetails)
            // Get the offer token:
            // a. For one-time products, call ProductDetails.getOneTimePurchaseOfferDetailsList()
            // for a list of offers that are available to the user.
            // b. For subscriptions, call ProductDetails.subscriptionOfferDetails()
            // for a list of offers that are available to the user.
            .setOfferToken(selectedOfferToken)
            .build()
    );

BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(productDetailsParamsList)
    .build();

// Launch the billing flow
BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

O método launchBillingFlow() retorna um dos vários códigos de resposta listados em BillingClient.BillingResponseCode. Verifique esse resultado para garantir que não houve erros ao iniciar o fluxo de compra. O BillingResponseCode OK indica que o pedido foi bem-sucedido.

Em uma chamada bem-sucedida para launchBillingFlow(), o sistema mostra a tela de compra do Google Play. A Figura 1 mostra uma tela de compra para uma assinatura:

O Google Play chama onPurchasesUpdated() para entregar o resultado da operação de compra a um listener que implementa a interface PurchasesUpdatedListener. O listener é especificado com o método setListener() ao inicializar o cliente.

Implemente onPurchasesUpdated() para gerenciar possíveis códigos de resposta. O exemplo abaixo mostra como substituir onPurchasesUpdated():

override fun onPurchasesUpdated(billingResult: BillingResult, purchases: List<Purchase>?) {
   if (billingResult.responseCode == BillingResponseCode.OK && purchases != null) {
       for (purchase in purchases) {
           // Process the purchase as described in the next section.
       }
   } else if (billingResult.responseCode == BillingResponseCode.USER_CANCELED) {
       // Handle an error caused by a user canceling the purchase flow.
   } else {
       // Handle any other error codes.
   }
}

@Override
void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
    if (billingResult.getResponseCode() == BillingResponseCode.OK
        && purchases != null) {
        for (Purchase purchase : purchases) {
            // Process the purchase as described in the next section.
        }
    } else if (billingResult.getResponseCode() == BillingResponseCode.USER_CANCELED) {
        // Handle an error caused by a user canceling the purchase flow.
    } else {
        // Handle any other error codes.
    }
}

Compras concluídas geram uma tela de conclusão de compra do Google Play semelhante à Figura 2.

Uma compra bem-sucedida também gera um token de compra, que é um identificador exclusivo que representa o usuário e o ID do produto único comprado. Seus apps podem armazenar o token de compra localmente, embora seja recomendável transmiti-lo para o servidor de back-end seguro, onde você pode verificar a compra e proteger contra fraudes. Esse processo é descrito em Como detectar e processar compras.

O usuário também recebe por e-mail um comprovante da transação, contendo o código do pedido ou um ID exclusivo para a transação. Os usuários recebem um e-mail com um código do pedido exclusivo para cada compra de produto único, assim como para a compra de assinatura inicial e as renovações automáticas seguintes. É possível usar o código do pedido para gerenciar reembolsos no Google Play Console.

Indicar um preço personalizado

Caso seu app possa ser distribuído aos usuários na União Europeia, use o método setIsOfferPersonalized() ao chamar launchBillingFlow para divulgar aos usuários que o preço de um item foi personalizado usando a tomada de decisões automatizada.

Você precisa consultar o Art. 6 (1) (ea) CRD da Diretiva de Direitos do Consumidor 2011/83/EU para determinar se o preço que você está oferecendo aos usuários é personalizado.

setIsOfferPersonalized() recebe uma entrada booleana. Quando é true, a IU do Google Play inclui a declaração. Quando false, a interface omite a declaração. O valor padrão é false.

Consulte a Central de Ajuda do consumidor para mais informações.

Anexar identificadores de usuários

Ao iniciar o fluxo de compra, o app pode anexar todos os identificadores de usuário que você tem para o usuário que está fazendo a compra usando obfuscatedAccountId ou obfuscatedProfileId. Um exemplo de identificador pode ser uma versão ofuscada do login do usuário no seu sistema. A definição desses parâmetros pode ajudar o Google a detectar fraudes. Além disso, ele pode ajudar a garantir que as compras sejam atribuídas ao usuário certo, conforme discutido em Como conceder direitos aos usuários.

Detectar e processar compras

A detecção e o processamento de uma compra descritos nesta seção são aplicáveis a todos os tipos de compras, incluindo compras fora do app, como resgates de promoções.

O app detecta novas compras e compras pendentes concluídas de uma destas maneiras:

1. Quando onPurchasesUpdated é chamado como resultado do app chamando launchBillingFlow (conforme discutido na seção anterior) ou se o app está em execução com uma conexão ativa da Biblioteca Faturamento quando há uma compra feita fora do app ou uma compra pendente é concluída. Por exemplo, um membro da família aprova uma compra pendente em outro dispositivo.
2. Quando o app chama queryPurchasesAsync para consultar as compras do usuário.

No caso 1, onPurchasesUpdated será chamado automaticamente para compras novas ou concluídas, desde que o app esteja em execução e tenha uma conexão ativa da Biblioteca Google Play Faturamento. Se o app não estiver em execução ou não tiver uma conexão ativa da biblioteca Google Play Faturamento, o onPurchasesUpdated não será invocado. É recomendável que o app tente manter uma conexão ativa enquanto estiver em primeiro plano para receber atualizações de compra em tempo hábil.

Para a opção 2, é necessário chamar BillingClient.queryPurchasesAsync() para garantir que o app processe todas as compras. É recomendável fazer isso quando o app estabelecer uma conexão com a Biblioteca Google Play Faturamento (o que é recomendado quando o app é iniciado ou aparece em primeiro plano, conforme discutido em Inicializar um BillingClient. Isso pode ser feito chamando queryPurchasesAsync ao receber um resultado bem-sucedido para onServiceConnected. Seguir essa recomendação é fundamental para processar eventos e situações como:

• Problemas de rede durante a compra: um usuário pode fazer uma compra e receber a confirmação do Google, mas o dispositivo perde a conexão de rede antes que o app receba uma notificação da compra pelo PurchasesUpdatedListener.
• Vários dispositivos: um usuário pode comprar um item em um dispositivo e esperar que ele apareça ao mudar de dispositivo.
• Processamento de compras feitas fora do app: algumas compras, como resgates de promoções, podem ser feitas fora do app.
• Processamento de transições de estado de compra: um usuário pode concluir o pagamento de uma compra PENDENTE enquanto seu aplicativo não está em execução e esperar receber a confirmação de que a compra foi concluída quando abrir o app.

Quando o app detectar uma compra nova ou concluída, ele precisará:

• Verifique a compra.
• Conceda conteúdo ao usuário para compras concluídas.
• Notifique o usuário.
• Notifique o Google de que o app processou as compras concluídas.

Essas etapas são discutidas em detalhes nas seções a seguir, seguidas por uma seção para resumir todas as etapas.

Verificar a compra

Seu app sempre precisa verificar a legitimidade das compras antes de conceder benefícios a um usuário. Isso pode ser feito seguindo as diretrizes descritas em Verificar compras antes de conceder direitos. Só depois de verificar a compra, seu app poderá continuar processando a compra e conceder direitos ao usuário, o que será discutido na próxima seção.

Conceder direito ao usuário

Depois que o app verificar uma compra, ele poderá continuar concedendo o direito de acesso ao usuário e notificando o usuário. Antes de conceder o direito, verifique se o app está verificando se o estado da compra é PURCHASED. Se a compra estiver no estado "PENDENTE", o app precisará notificar o usuário de que ele ainda precisa realizar ações para concluir a compra antes que o direito seja concedido. Conceda o direito apenas quando a compra mudar de "PENDING" para "SUCCESS". Confira mais informações em Como processar transações pendentes.

Se você tiver identificadores de usuário anexados à compra, conforme discutido em Anexar identificadores de usuário, é possível recuperá-los e usá-los para atribuir ao usuário correto no sistema. Essa técnica é útil ao reconciliar compras em que o app pode ter perdido o contexto sobre para qual usuário uma compra é destinada. As compras feitas fora do app não terão esses identificadores definidos. Nesse caso, o app pode conceder o direito ao usuário conectado ou solicitar que ele selecione uma conta preferida.

Para pré-encomendas, a compra fica em estado PENDENTE antes do lançamento. A compra da pré-venda será concluída no momento do lançamento e mudará o estado para "COMPRADA" sem outras ações.

Notificar o usuário

Depois de conceder o direito de acesso ao usuário, o app precisa mostrar uma notificação para confirmar a compra. Por causa da notificação, o usuário não fica confuso sobre se a compra foi concluída, o que poderia resultar na interrupção do uso do app, no contato com o suporte ao usuário ou na reclamação nas mídias sociais. Seu app pode detectar atualizações de compra a qualquer momento durante o ciclo de vida do aplicativo. Por exemplo, um pai aprova uma compra pendente em outro dispositivo. Nesse caso, o app pode adiar a notificação do usuário para um momento adequado. Alguns exemplos em que um atraso seria apropriado são:

• Durante a parte de ação de um jogo ou cenas, mostrar uma mensagem pode distrair o usuário. Nesse caso, notifique o usuário após o término da ação.
• Durante o tutorial inicial e as partes da configuração do usuário no jogo. Por exemplo, um usuário pode ter feito uma compra fora do app antes de instalá-lo. Recomendamos que você notifique os novos usuários sobre o prêmio imediatamente depois que eles abrirem o jogo ou durante a configuração inicial. Se o app exigir que o usuário crie uma conta ou faça login antes de conceder o direito, é recomendado informar ao usuário quais etapas ele precisa concluir para reivindicar a compra. Isso é importante porque as compras são reembolsadas após três dias se o app não as processar.

Ao notificar o usuário sobre uma compra, o Google Play recomenda os seguintes mecanismos:

• Mostrar uma caixa de diálogo no app.
• Entregar a mensagem a uma caixa de mensagens no aplicativo e informar claramente que há uma nova mensagem.
• Usar uma mensagem de notificação do SO.

A notificação precisa informar o usuário sobre o benefício recebido. Por exemplo, "Você comprou 100 moedas de ouro". Além disso, se a compra foi resultado de um benefício de um programa, como o Play Pass, o app vai comunicar isso ao usuário. Por exemplo, "Itens recebidos. Você acabou de ganhar 100 Gemas com o Play Pass. Continuar.". Cada programa pode ter orientações sobre o texto recomendado a ser mostrado aos usuários para comunicar os benefícios.

Notificar o Google de que a compra foi processada

Depois que o app conceder o direito ao usuário e notificar sobre a transação, ele precisará notificar o Google de que a compra foi processada. Isso é feito confirmando a compra e precisa ser feito em até três dias para que a compra não seja reembolsada automaticamente e a permissão revogada. O processo para reconhecer diferentes tipos de compras é descrito nas seções a seguir.

Produtos de consumo

No caso de produtos de consumo, se o app tiver um back-end seguro, recomendamos usar Purchases.products:consume para efetivar as compras de forma confiável. Confira se a compra já não foi consumida verificando o consumptionState do resultado da chamada de Purchases.products:get. Se o app for exclusivo para clientes sem um back-end, use consumeAsync() da Biblioteca Google Play Faturamento. Os dois métodos atendem ao requisito de confirmação e indicam que o app concedeu direito de acesso ao usuário. Eles também permitem que o app disponibilize o produto único correspondente ao token de compra de entrada para recompra. Com consumeAsync(), você também precisa transmitir um objeto que implemente a interface ConsumeResponseListener. Esse objeto cuida do resultado da operação de consumo. É possível substituir o método onConsumeResponse(), que a Biblioteca Google Play Faturamento chama quando a operação é concluída.

Confira um exemplo que ilustra o consumo de um produto com a Biblioteca Google Play Faturamento usando o token de compra associado:

    val consumeParams =
        ConsumeParams.newBuilder()
            .setPurchaseToken(purchase.getPurchaseToken())
            .build()
    val consumeResult = withContext(Dispatchers.IO) {
        client.consumePurchase(consumeParams)
    }

    ConsumeParams consumeParams =
            ConsumeParams.newBuilder()
                .setPurchaseToken(purchase.getPurchaseToken())
                .build();

    ConsumeResponseListener listener = new ConsumeResponseListener() {
        @Override
        public void onConsumeResponse(BillingResult billingResult, String purchaseToken) {
            if (billingResult.getResponseCode() == BillingResponseCode.OK) {
                // Handle the success of the consume operation.
            }
        }
    };

    billingClient.consumeAsync(consumeParams, listener);

Produtos que não são de consumo

Se o app tiver um back-end seguro, recomendamos usar Purchases.products:acknowledge para confirmar de maneira confiável as compras de produtos que não são de consumo. Confira se a compra não foi confirmada anteriormente verificando o acknowledgementState no resultado da chamada de Purchases.products:get.

Se o app for exclusivo para clientes, use o método BillingClient.acknowledgePurchase() da Biblioteca Google Play Faturamento. Antes de confirmar uma compra, o app precisa conferir se ela já foi confirmada usando o método isAcknowledged() na Biblioteca Google Play Faturamento.

O exemplo abaixo mostra como confirmar uma compra usando a Biblioteca Google Play Faturamento:

val client: BillingClient = ...
val acknowledgePurchaseResponseListener: AcknowledgePurchaseResponseListener = ...

val acknowledgePurchaseParams = AcknowledgePurchaseParams.newBuilder()
    .setPurchaseToken(purchase.purchaseToken)
val ackPurchaseResult = withContext(Dispatchers.IO) {
     client.acknowledgePurchase(acknowledgePurchaseParams.build())
}

BillingClient client = ...
AcknowledgePurchaseResponseListener acknowledgePurchaseResponseListener = ...

AcknowledgePurchaseParams acknowledgePurchaseParams =
                AcknowledgePurchaseParams.newBuilder()
                    .setPurchaseToken(purchase.getPurchaseToken())
                    .build();
 client.acknowledgePurchase(acknowledgePurchaseParams, acknowledgePurchaseResponseListener);

Assinaturas

As assinaturas são processadas de forma semelhante aos produtos que não são de consumo. Se possível, use Purchases.subscriptions.acknowledge da API Google Play Developer para confirmar de maneira confiável a compra no back-end seguro. Confira se a compra não foi confirmada anteriormente, verificando o acknowledgementState no recurso de compra de Purchases.subscriptions:get. Também é possível confirmar uma assinatura usando BillingClient.acknowledgePurchase() da Biblioteca Google Play Faturamento depois de conferir o isAcknowledged(). Todas as compras de assinatura inicial precisam ser confirmadas. Renovações de assinatura, por outro lado, não precisam passar por essa etapa. Para saber mais sobre quando as assinaturas precisam ser confirmadas, consulte o tópico Vender assinaturas.

Resumo

O snippet de código a seguir mostra uma recapitulação dessas etapas.

fun handlePurchase(Purchase purchase) {
    // Purchase retrieved from BillingClient#queryPurchasesAsync or your
    // onPurchasesUpdated.
    Purchase purchase = ...;

    // Step 1: Send the purchase to your secure backend to verify the purchase
    // following
    // https://developer.android.com/google/play/billing/security#verify
.
    // Step 2: Update your entitlement storage with the purchase. If purchase is
    // in PENDING state then ensure the entitlement is marked as pending and the
    // user does not receive benefits yet. It is recommended that this step is
    // done on your secure backend and can combine in the API call to your
    // backend in step 1.

    // Step 3: Notify the user using appropriate messaging (delaying
    // notification if needed as discussed above).

    // Step 4: Notify Google the purchase was processed using the steps
    // discussed in the processing purchases section.
}

void handlePurchase(Purchase purchase) {
    // Purchase retrieved from BillingClient#queryPurchasesAsync or your
    // onPurchasesUpdated.
    Purchase purchase = ...;

    // Step 1: Send the purchase to your secure backend to verify the purchase
    // following
    // https://developer.android.com/google/play/billing/security#verify

    // Step 2: Update your entitlement storage with the purchase. If purchase is
    // in PENDING state then ensure the entitlement is marked as pending and the
    // user does not receive benefits yet. It is recommended that this step is
    // done on your secure backend and can combine in the API call to your
    // backend in step 1.

    // Step 3: Notify the user using appropriate messaging (delaying
    // notification if needed as discussed above).

    // Step 4: Notify Google the purchase was processed using the steps
    // discussed in the processing purchases section.
}

Para verificar se o app implementou essas etapas corretamente, siga o guia de testes.

Processar transações pendentes

O Google Play oferece suporte para transações pendentes, ou aquelas que exigem uma ou mais etapas extras entre o momento em que um usuário inicia uma compra e o processamento da forma de pagamento. Não conceda direito de acesso a esses tipos de compras até que o Google notifique você de que a cobrança foi feita na forma de pagamento do usuário.

Por exemplo, um usuário pode iniciar uma transação escolhendo uma loja física em que vai pagar depois com dinheiro. O usuário recebe um código por notificação e e-mail. Quando o usuário chegar à loja física, ele poderá resgatar o código com o caixa e pagar com dinheiro. O Google notifica você e o usuário de que o pagamento foi recebido. Então, seu aplicativo pode conceder a titularidade ao usuário.

Chame enablePendingPurchases() como parte da inicialização do BillingClient para ativar transações pendentes no app. O app precisa ativar e oferecer suporte a transações pendentes para produtos de compra única. Antes de adicionar suporte, entenda o ciclo de vida da compra para transações pendentes.

Quando seu app recebe uma nova compra, pelo PurchasesUpdatedListener ou ao chamar queryPurchasesAsync, use o método getPurchaseState() para determinar se o estado de compra é PURCHASED ou PENDING. Conceda direitos apenas quando o estado for PURCHASED.

Se o app estiver em execução e você tiver uma conexão ativa da Biblioteca Play Faturamento quando o usuário concluir a compra, o método PurchasesUpdatedListener será chamado novamente, e o PurchaseState será PURCHASED. Nesse momento, seu app pode processar a compra usando o método padrão para detectar e processar compras. O app também precisa chamar queryPurchasesAsync() no método onResume() para processar compras que fizeram a transição para o estado PURCHASED enquanto ele não estava em execução.

Quando a compra mudar de PENDING para PURCHASED, o cliente real_time_developer_notifications vai receber uma notificação ONE_TIME_PRODUCT_PURCHASED ou SUBSCRIPTION_PURCHASED. Se a compra for cancelada, você vai receber uma notificação ONE_TIME_PRODUCT_CANCELED ou SUBSCRIPTION_PENDING_PURCHASE_CANCELED. Isso poderá acontecer se o cliente não concluir o pagamento no prazo exigido. É possível sempre usar a API Google Play Developer para verificar o estado atual de uma compra.

Processar compras de quantidade múltipla

O Google Play permite que os clientes comprem mais de uma unidade do mesmo produto de uso único em uma única transação especificando a quantidade no carrinho de compras. Esse recurso está disponível nas versões 4.0 e mais recentes da Biblioteca Google Play Faturamento. O app precisa processar compras de quantidade múltipla e conceder direito de acesso ao usuário de acordo com a quantidade especificada na compra.

Para aceitar compras de quantidade múltipla, a lógica de provisionamento do app precisa verificar a quantidade de itens. É possível acessar um campo quantity em uma destas APIs:

• getQuantity() na Biblioteca Google Play Faturamento.
• Purchases.products.quantity na API Google Play Developer.

Depois de adicionar a lógica de processamento de compras de quantidade múltipla, você precisará ativar esse recurso para o produto correspondente na página de gerenciamento de produtos no Google Play Console.

Consultar a configuração de faturamento do usuário

getBillingConfigAsync() mostra o país em que o usuário usa o Google Play.

É possível consultar a configuração de faturamento do usuário depois de criar um BillingClient. O snippet de código abaixo descreve como fazer uma chamada para getBillingConfigAsync(). Processe a resposta implementando o BillingConfigResponseListener. Esse listener recebe atualizações para todas as consultas de configuração de faturamento iniciadas pelo seu app.

Se o BillingResult retornado não contiver erros, confira o campo countryCode no objeto BillingConfig para saber o país do Google Play do usuário.

// Use the default GetBillingConfigParams.
val getBillingConfigParams = GetBillingConfigParams.newBuilder().build()
billingClient.getBillingConfigAsync(getBillingConfigParams,
    object : BillingConfigResponseListener {
        override fun onBillingConfigResponse(
            billingResult: BillingResult,
            billingConfig: BillingConfig?
        ) {
            if (billingResult.responseCode == BillingResponseCode.OK
                && billingConfig != null) {
                val countryCode = billingConfig.countryCode
                ...
            } else {
                // TODO: Handle errors
            }
        }
    })

// Use the default GetBillingConfigParams.
GetBillingConfigParams getBillingConfigParams = GetBillingConfigParams.newBuilder().build();
billingClient.getBillingConfigAsync(getBillingConfigParams,
    new BillingConfigResponseListener() {
      public void onBillingConfigResponse(
          BillingResult billingResult, BillingConfig billingConfig) {
        if (billingResult.getResponseCode() == BillingResponseCode.OK
            && billingConfig != null) {
            String countryCode = billingConfig.getCountryCode();
            ...
         } else {
            // TODO: Handle errors
        }
      }
    });

Lembretes de abandono do carrinho na página inicial do Google Play Games (ativados por padrão)

Para desenvolvedores de jogos que geram receita com produtos únicos, uma maneira de vender unidades de manutenção de estoque (SKUs) ativas no Google Play Console fora do app é o recurso "Lembrete de abandono do carrinho", que incentiva os usuários a concluir compras inacabadas enquanto navegam pela Google Play Store. Essas compras acontecem fora do app, na página inicial do Google Play Games na Google Play Store.

Esse recurso é ativado por padrão para ajudar os usuários a retomar de onde pararam e para ajudar os desenvolvedores a maximizar as vendas. No entanto, você pode desativar esse recurso no seu app enviando o formulário de desativação do recurso "Lembrete de abandono do carrinho". Para conferir as práticas recomendadas sobre como gerenciar SKUs no Google Play Console, consulte Criar um produto no app.

As imagens a seguir mostram o lembrete de abandono de carrinho aparecendo na Google Play Store: