Guia completo para atualizar e implantar a Biblioteca de Faturamento do Google Play v7.

Se você trabalha com compras dentro de aplicativos no Android, mais cedo ou mais tarde terá que lidar com... Biblioteca de faturamento do Google Play v7Não se trata apenas de mais uma atualização: ela traz alterações na API, novos recursos de assinatura, requisitos para o console e prazos bem definidos pelo Google. Ignorá-la não é mais uma opção se você quiser continuar publicando ou atualizando seu aplicativo no Google Play sem surpresas.

Ao longo deste artigo, você verá como Atualize e implemente a Biblioteca de Faturamento do Google Play v7. Passo a passo: desde as diferenças entre o PBL 5 e 6, até como integrar assinaturas, compras únicas, RTDN, testes com o Play Billing Lab e como sobreviver em ecossistemas como o .NET MAUI, onde o suporte oficial deixa a desejar. A ideia é que, ao terminar a leitura, você possa preparar sua migração com confiança e sem gastar um centavo.

Visão geral da Biblioteca de Faturamento do Google Play v7

A Biblioteca de Faturamento do Google Play 7 introduz melhorias significativas na forma como as faturas são gerenciadas. Pagamentos, assinaturas e planos especiaisNo entanto, foi projetado para tornar a migração relativamente tranquila. A boa notícia é que muitas das novas APIs são opcionais: você pode atualizar a dependência, ajustar algumas referências e sua integração básica ainda funcionará.

Esta versão concentra-se em três áreas principais: novas opções de assinatura (como quotas virtuais), melhor suporte para compras pendentes em planos pré-pagose alterações na API que eliminam o que já estava obsoleto em versões anteriores (PBL 5 e 6). Além disso, o Google ajusta alguns procedimentos de tratamento de erros e a forma como você deve lidar com transações pendentes para evitar inconsistências.

Para começar, no módulo do seu aplicativo, você precisa atualizar a dependência no seu arquivo. construir.gradle:

dependencies {
    def billingVersion = "7.0.0"
    implementation "com.android.billingclient:billing:$billingVersion"
}

Feito isso, é hora de revisar o código que usa APIs legadas. Muitas chamadas relacionadas a rateio de assinatura e cobrança alternativa Eles foram renomeados ou removidos, portanto, é uma boa ideia examinar cuidadosamente todas as referências a BillingClient e BillingFlowParams antes de compilar e enviar qualquer coisa para o Play Console.

Estratégias de monetização com compras únicas e assinaturas

Ao vender produtos digitais dentro do seu aplicativo, simplesmente colar a caixa de diálogo de compra e pronto não é suficiente: é preciso criar um design que priorize a experiência do usuário. experiência de usuário perfeita durante todo o ciclo de compraIsso se aplica tanto a produtos individuais (consumíveis ou não consumíveis) quanto a assinaturas. Quanto mais natural e descomplicado for o processo, maior será a taxa de conversão e menor a taxa de cancelamento.

Um fluxo de compra típico com o Play Billing, seja para uma assinatura ou um item único, geralmente segue estas etapas bem definidas, que seu backend também deve conhecer:

O usuário explora os produtos disponíveis e seleciona um.
O aplicativo inicia o processo de faturamento do Google Play para concluir o pagamento.
A compra foi concluída e seu aplicativo recebeu o resultado.
Seu servidor valida a compra usando a API para desenvolvedores do Google Play.
O conteúdo ou direito correspondente é concedido ao usuário em seu sistema.
O Google é informado de que a compra foi processada (concluída ou confirmada).

No caso de produtos de consumo, é vital que consumir o token no momento certo para permitir recompras sem problemas e ajudar Bloquear compras acidentais no Google PlayEm modelos de assinatura, é preciso controlar renovações, períodos de carência, suspensões e cancelamentos para que o usuário receba exatamente o que pagou, sem um dia a menos.

A integração com o aplicativo é apenas metade do trabalho: seu servidor deve manter um registro confiável de direitos e status de compraIsso é especialmente importante se você oferece acesso multiplataforma ou precisa de estatísticas detalhadas sobre receita, retenção e rotatividade de clientes. É aí que entram as notificações de desenvolvedor em tempo real (RTDNs), atuando como a "caixa preta" do ciclo de compra.

Com o RTDN, você pode reagir quase em tempo real a eventos críticos: uma nova compra, uma falha na renovação, uma assinatura entrando em período de carência ou uma compra cancelada. Isso permite que você desenvolva estratégias para recuperação de assinantes e prevenção de fraude, como o envio automático de e-mails quando um pagamento falha ou ajustes de direitos caso o cliente não receba a mensagem devido a problemas de rede.

Notificações de desenvolvedor em tempo real (RTDN) e Google Cloud Pub/Sub

RTDNs usam Google Cloud Pub/Sub como um sistema de mensagens em tempo real entre o Google Play e seu backend. O Google Play publica eventos sobre um tópico do Pub/Sub, e você se inscreve nesse tópico para receber mensagens sempre que o status de uma compra ou assinatura for alterado.

O fluxo básico é simples: o Google Play envia uma mensagem codificada em base64 para o tópico do Pub/Sub, seu assinante a extrai, decodifica e processa a notificação. Dentro do campo data Dentro da mensagem você encontrará um objeto JSON. Notificação ao desenvolvedorque inclui informações como versão da mensagem, nome do pacote, horário do evento e dados específicos sobre compras únicas, assinaturas, compras canceladas ou períodos de teste.

{
  "version": string,
  "packageName": string,
  "eventTimeMillis": long,
  "oneTimeProductNotification": OneTimeProductNotification,
  "subscriptionNotification": SubscriptionNotification,
  "voidedPurchaseNotification": VoidedPurchaseNotification,
  "testNotification": TestNotification
}

Graças a essas mensagens, você pode Mantenha seu backend sincronizado mesmo se o dispositivo do usuário falhar.Imagine que um usuário efetue uma compra com sucesso, o Google Play a confirme, mas o dispositivo móvel perca a conexão antes que seu aplicativo receba a notificação da Biblioteca de Faturamento. Sem o RTDN, você talvez nunca perceba. Com o Pub/Sub, seu servidor recebe uma notificação separada e pode conceder a autorização independentemente do cliente.

Configuração do Cloud Pub/Sub para RTDN

Antes de ativar o RTDN no console do Google Play, você precisa preparar um projeto em Google Cloud Platform (GCP) e configure o Pub/Sub lá. O processo é relativamente simples, mas é melhor segui-lo com atenção para evitar surpresas com permissões ou nomes de recursos.

Criando o tópico

Primeiro você deve criar um Tópico Pub/Sub que funcionará como seu ponto de publicação no Google Play. No console do Google Cloud, selecione seu projeto, acesse a seção Publicar/Assinar e crie um novo tópico seguindo o guia oficial "criar tópico". O resultado terá um nome no seguinte formato:

projects/{project_id}/topics/{topic_name}

Esse nome completo é o que você precisará colar no Play Console ao ativar as notificações.

Criação de assinatura

Para ler as mensagens nesta conversa, você precisa de um Assinatura Pub/SubVocê pode configurá-lo como empurrar o como puxarNo codelab de referência, trabalhamos com assinatura pull, onde seu backend inicia as solicitações para recuperar mensagens.

Você deve consultar as opções no guia de assinantes do Cloud Pub/Sub para decidir se o modelo push ou pull é o mais adequado para sua arquitetura. Depois de decidir, siga a documentação "adicionar assinatura" e vincule-a ao tópico que você criou anteriormente. A partir desse momento, todas as mensagens que o Google Play publicar no tópico ficarão acessíveis ao seu assinante.

Permissões para o Google Play publicar no seu tema

O recurso Publicar/Sub não permitirá que o Google Play publique nada a menos que você dê permissão explícita. conta de serviçoNo console do Google Cloud, você precisa acessar as configurações de permissões do tópico e adicionar a principal:

[email protected]

Atribua a esta conta o papel de Editora Pub/Sub (Editor). Salve as alterações e, a partir desse momento, o Google Play poderá enviar RTDNs para o seu tema sem problemas de autorização.

Ative o RTDN no Google Play Console.

Após configurar o Pub/Sub, você precisa informar ao Play Console para onde enviar as notificações. No seu app, no Google Play Console, acesse... Monetize com o Play > Configurações de monetização e localize a seção de notificações para desenvolvedores em tempo real.

Lá você precisará:

Marque a caixa para ativar as notificações em tempo real.
Insira o nome completo do tópico Pub/Sub no campo correspondente, respeitando o formato. projects/{project_id}/topics/{topic_name}.
Envie uma mensagem de teste usando o botão de teste.

A mensagem de teste é essencial para verificar se o A integração foi bem implementada.Se você tiver uma assinatura pull, poderá acessar o console do Cloud, selecionar a assinatura, clicar em "Visualizar mensagens" e extrair a mensagem de teste. Não se esqueça de fazer ack de qualquer mensagem que você leia para evitar recepções repetidas.

Para assinaturas push, verifique se seu endpoint recebe a mensagem e responde com um código HTTP válido. Se algo der errado, o console exibirá um erro ao publicar o teste, geralmente relacionado ao nome do tópico ou às permissões da conta de serviço.

Assine os testes de aplicativos na Google Play Store

Crie um assinante Pub/Sub no seu backend.

Com o tema e a assinatura prontos, é hora de implementar um assinante que lê e processa RTDNsO Google fornece exemplos em várias linguagens; um caso típico em Java utiliza as bibliotecas de cliente do Cloud Pub/Sub para iniciar uma Subscriber quem ouve mensagens e liga para MessageReceiver.

O padrão geral é sempre o mesmo: você recupera a mensagem e decodifica o campo. data Você converte base64 em texto, analisa o JSON e extrai os campos relevantes (como packageName, oneTimeProductNotification o subscriptionNotification) e decida o que fazer em seu sistema. Após processar a notificação com sucesso, você deve Confirme a mensagem com um ACK. para que o Pub/Sub não o envie novamente.

O código de exemplo mostra como o receptor imprime a versão e o nome do pacote, mas em uma implementação real você iria além: Você validaria a compra, concedendo o direito ao usuário correto.Você atualizaria seu banco de dados e, se necessário, chamaria a API do Play Developer para consumir ou reconhecer a compra.

Enviar notificações vinculadas ao usuário: usando obfuscatedAccountId

Um problema comum ao gerenciar compras do servidor é saber a qual usuário uma notificação RTDN específica pertence. Para isso, a API do Cliente de Faturamento permite anexar um identificador de conta ofuscado Ao iniciar o fluxo de compra: obfuscatedAccountId.

A ideia é que você use um identificador estável do seu sistema (por exemplo, o ID interno do usuário), mas oculto por motivos de privacidade e segurançaEsse valor está associado à compra e aparece nas informações retornadas pela API do Google Play Developer, de forma que, ao receber o RTDN e verificar o token, você saberá inequivocamente a qual conta do seu banco de dados deverá conceder a permissão.

Do lado do cliente, ao preparar o BillingFlowParamsVocê só precisa criar a lista de ProductDetailsParams e ligar setObfuscatedAccountId(obfuscatedAccountId) antes de iniciar o fluxo. Isso não altera a experiência visível do usuário, mas simplifica bastante o processo. lógica de alocação de compras de back-end e ajuda o Google a detectar fraudes.

Verifique as compras usando a API do desenvolvedor do Google Play.

Antes de conceder quaisquer direitos em seu servidor, é obrigatório verificar se a compra é legítima, entrando em contato com a empresa de segurança. API para desenvolvedores do Google PlayNão basta confiar no que o cliente ou mesmo o RTDN dizem: você deve validar o purchaseToken diretamente contra os endpoints oficiais e, se necessário, gerenciar reembolsos.

No caso de produtos únicos, você usará o endpoint purchases.products:getPara assinaturas, o caminho passa por purchases.subscriptionsv2:getO fluxo recomendado é:

Extraia o purchaseToken da mensagem Pub/Sub.
Verifique seu banco de dados para ver se você já o processou; cada token é único no mundoPortanto, é perfeita como chave primária para evitar duplicados.
Se for novo, chame a API de desenvolvedor do Google Play com o pacote, SKU e o purchaseToken.
Verifique se a resposta indica o status da compra. COMPRADO (Não está PENDENTE nem cancelado).
Se tudo estiver correto, registre o token e conceda o direito correspondente ao usuário associado.

Para se comunicar com a API do Play Developer a partir do Java, você pode usar Publicador de Android, inicializado com credenciais de conta de serviço em formato JSON. Você configura o escopo. AndroidPublisherScopes.ANDROIDPUBLISHERVocê cria o cliente e chama o método. purchases().products().get(...)Caso a chamada falhe devido a um problema temporário de rede ou de serviço, recomenda-se Implementar novas tentativas com recuo exponencial. para não perder o evento.

Confirme ou conclua a compra no servidor.

Após verificar a compra e conceder a autorização no seu sistema, o próximo passo é notificar o Google de que a transação foi processada com sucesso. Para produtos de item único, você tem duas opções: consumir a compra ou simplemente reconhecê-la.

Produtos consumíveis (por exemplo, moeda virtual, vidas, etc.) devem passar pelo ponto final. purchases.products:consumeIsso marca o token como usado e permite que o usuário compre o mesmo item novamente sem conflitos. Para produtos não consumíveis (como desbloquear a versão premium para sempre), você deve ligar purchases.products:acknowledge, que informa ao Google que o usuário já possui o direito associado.

Assinaturas são utilizadas. purchases.subscriptions:acknowledgeindicando que a assinatura foi processada com sucesso e atribuída ao usuário. Se você não confirmar a compra dentro de um prazo razoável, o Google poderá presumir que há um problema e reverter a transação, por isso é importante que você A devolução é feita logo após a concessão do direito..

No seu auxiliar AndroidPublisher, você pode adicionar métodos como: executeProductPurchasesConsume y executeProductPurchasesAcknowledge que chamam os endpoints correspondentes. Novamente, é aconselhável implementar novas tentativas em caso de falhas ocasionais, para garantir que nenhum token permaneça em um estado intermediário perigoso.

Testes avançados com o Play Billing Lab

Um aspecto que muitos desenvolvedores subestimam é a fase de testes. Para lançar um produto com qualquer grau de confiança, é necessário ser capaz de simular... erros de rede, respostas não padronizadas e casos extremosÉ aí que entra o Play Billing Lab, um aplicativo gratuito no Google Play desenvolvido especificamente para testar integrações da Play Billing Library.

O Play Billing Lab inclui um simulador de respostas o que permite forçar diferentes BillingResponseCode nas chamadas do seu aplicativo para a Biblioteca de Faturamento. Dessa forma, você pode recriar cenários em que, por exemplo, o cliente não consegue concluir a compra devido a um problema de rede, mas seu backend processa corretamente o RTDN e, por fim, concede o direito sem intervenção do usuário.

Para que seu aplicativo se comunique com o simulador, você precisa habilitar o teste de "substituições de faturamento" usando metadados no AndroidManifest.xml:

<manifest ... >
  <application ... >
    ...
    <meta-data
        android:name="com.google.android.play.largest_release_audience.NONPRODUCTION"
        android:value="" />
    <meta-data
        android:name="com.google.android.play.billingclient.enableBillingOverridesTesting"
        android:value="true" />
  </application>
</manifest>

A etiqueta ativarTestesDeSubstituiçõesDeFaturamento Ative os testes de resposta simulada na Biblioteca de Faturamento. A etiqueta NONPRODUCTION serve como um lembrete de que esta versão não deve ser colocada em produção com as alterações ativadas. Ao preparar a versão final para os usuários, certifique-se de Remova esses metadados ou use um manifesto separado..

Após a configuração, no aplicativo Play Billing Lab, faça login com uma conta de testador de licença, ative a opção "Simular resposta da Biblioteca de Faturamento do Play" e selecione quais códigos de erro você deseja retornar para cada API (por exemplo, um erro específico em consumeAsyncEm seguida, basta abrir o aplicativo e executar o fluxo que deseja testar: o simulador retornará as respostas configuradas e você poderá verificar se a lógica de repetição, o tratamento de erros e o RTDN se comportam conforme o esperado.

Principais alterações da API ao migrar para a Play Billing Library 7

Além do RTDN e dos testes, a migração para o PBL 7 envolve a resolução de alguns pontos específicos da API. Para quem vem do PBL 5 ou 6, vale a pena revisar as alterações mais relevantes para garantir que o projeto compile sem problemas e que a lógica de negócios permaneça consistente.

Primeiro, as APIs relacionadas a Modo de rateio As opções de alteração de assinatura foram removidas. Agora, utiliza-se a seguinte opção: Modo de Substituição Para gerenciar alterações de planos (upgrades, downgrades, etc.). Se você ainda estiver usando métodos como setReplaceProrationMode o setReplaceSkusProrationModeVocê terá que migrá-los para as novas variantes de setSubscriptionReplacementMode e ajuste a lógica de acordo com a documentação atualizada.

A API também foi removida. launchPriceConfirmationFlowque já estava marcada como obsoleta. Para lidar com alterações nos preços das assinaturas, consulte os novos fluxos de trabalho e recomendações no guia de alteração de preços, que detalha como informar adequadamente o usuário e como gerenciar o consentimento.

Outro ponto importante é o APIs de faturamento alternativasOs métodos BillingClient.Builder.enableAlternativeBilling, AlternativeBillingListener y AlternativeChoiceDetails desapareceram em favor de uma nomenclatura mais alinhada: agora você deve usar BillingClient.Builder.enableUserChoiceBilling() junto com UserChoiceBillingListener y UserChoiceDetailsSegundo o próprio Google, trata-se basicamente de uma mudança de nome sem alterações de comportamento, num contexto marcado por acordos como Google e Epic Games concordam em abrir o Android.

Por fim, um novo código de erro é inserido. ERRO_DE_REDE en BillingResulte os significados e condições de SERVICE_TIMEOUT e SERVICE_UNAVAILABLESe você possui uma lógica personalizada de tratamento de erros (por exemplo, decidindo quando exibir uma mensagem ao usuário, quando tentar novamente silenciosamente, etc.), é recomendável revisá-la para levar em consideração essas novas nuances.

Transações pendentes e ausência de ID do pedido até a conclusão da compra.

Uma mudança sutil no PBL 7 é que a biblioteca não gera mais um ID do pedido para compras pendentes. Nestes casos, o orderId Só estará disponível quando a compra atingir o estado COMPRADO. Isso afeta principalmente fluxos de trabalho em que você usou o ID do pedido como referência principal desde o início.

A recomendação do Google é que você confie no token de compra para seus registros e conciliaçõespelo menos enquanto a transação estiver pendente. Se você encontrar uma compra que desapareceu da Play Store, verifique O que fazer se a compra desaparecer?.

Se você ainda não trabalhou com saldos em aberto, revise o guia de integração e a documentação da Biblioteca de Faturamento em gestão do ciclo de vida de comprasLá você encontrará os diferentes estados, como reagir a cada um deles e como as RTDNs se encaixam nesse quebra-cabeça.

Novas funcionalidades opcionais no PBL 7: parcelamento e pré-pagamento virtuais.

Entre as novas funcionalidades "legais" do PBL 7 estão as assinaturas virtuais de taxas (assinaturas virtuais parceladas) e suporte estendido para compras pendentes em assinaturas pré-pagas. Esses recursos não são obrigatórios, mas podem oferecer mais flexibilidade na adaptação do seu modelo de negócios a diferentes mercados.

As parcelas virtuais permitem que um usuário pague por uma assinatura de longo prazo em pequenos pagamentos periódicosEm vez de um único pagamento único e vultoso, o Google explica que, para fins de faturamento de desenvolvedores, você continuará recebendo pagamentos mensais em um plano anual com parcelas mensais. Se um usuário perder um pagamento, nem você nem o Google deverão tentar recuperar as parcelas anteriores. Isso torna seu uso prático bastante semelhante a uma assinatura mensal padrão, pelo menos inicialmente.

Por enquanto, essas taxas de assinatura estão disponíveis apenas em Brasil, França, Itália e EspanhaO Google recomenda ficar de olho no Play Console para ver se novos países são compatíveis. A configuração é feita através de ProductDetails.InstallmentPlanDetails e seguindo o guia específico para integrá-los ao seu aplicativo.

Em paralelo, o apoio está sendo ampliado. compras pendentes para assinaturas pré-pagasAgora você pode oferecer modelos em que o usuário inicia a compra no aplicativo e conclui o pagamento posteriormente por outros meios, e a Biblioteca de Faturamento sabe como lidar com esse fluxo corretamente. A ativação é feita por meio de uma chamada. enablePendingPurchases() ao inicializar o BillingClient e, especificamente para planos pré-pagos, usando PendingPurchasesParams.Builder.enablePrepaidPlans().

Períodos de depreciação para a Play Billing Library 5 e 6

Com o PBL 7 em andamento, o Google definiu datas claras para o retirada do suporte para as versões 5 e 6Se você ainda estiver em alguma delas, marque o calendário em vermelho:

A Biblioteca de Faturamento do Google Play 5 será oficialmente descontinuada em 31 de agosto de 2024 para novos apps e atualizações. É possível solicitar uma prorrogação até 1º de novembro de 2024, mas não é algo com que você deva contar a longo prazo.
A Biblioteca de Faturamento do Google Play 6 pode ser usada para publicar novos apps até 1º de agosto de 2025 e para atualizar apps existentes até 1º de novembro de 2025.

Após essa data, se você não tiver migrado para pelo menos a versão 6 ou, idealmente, para a versão 7, será necessário atualizar para a versão mais recente. versão 7As atualizações do seu app serão bloqueadas no Play Console. Embora ele continue funcionando nos dispositivos dos usuários, você ficará impedido de corrigir erros ou adicionar novos recursos que dependem da publicação na loja.

O caso do .NET MAUI e as limitações atuais

Se você trabalha com .NET MAUI e assinaturas no Android, provavelmente já leu ou vivenciou que não é tão simples assim. Muitos projetos usaram Plugin.FaturamentoNoAplicativo Por James Montemagno, mas o plugin está arquivado e sem manutenção, portanto não será atualizado para oferecer suporte à Biblioteca de Faturamento 7. Ao mesmo tempo, o pacote oficial Xamarin.Android.Google.Cliente de Faturamento Permaneceu ancorado ao ecossistema Xamarin.Android e não é diretamente compatível com o .NET MAUI.

A consequência prática é que o O PlayStation avisa. Seu aplicativo não utiliza a Biblioteca de Faturamento 7.0.0 ou superior, o que impede atualizações caso você continue utilizando versões antigas. Alguns desenvolvedores optaram por soluções drásticas, como desativar temporariamente as assinaturas para poderem enviar uma nova versão, mas obviamente isso não é sustentável se o seu modelo de negócios depende dessa monetização.

Nesse contexto, muitas equipes estão considerando alternativas como SDKs de terceiros Esses serviços já oferecem suporte ao PBL 7 internamente e expõem uma API multiplataforma mais estável (por exemplo, soluções de backend de assinatura com SDKs para Android, iOS e outras plataformas). Normalmente, esses serviços lidam com migrações de versão da Biblioteca de Faturamento e expõem um wrapper estável, reduzindo significativamente o estresse a cada nova descontinuação do Google.

Até que a Microsoft e a equipe do MAUI ofereçam uma Pacote oficial atualizado e totalmente compatível. Com a Billing Library 7, as opções incluem: implementar sua própria integração com a Billing Library nativa, usar um serviço de terceiros ou repensar a forma como você integra as compras ao seu projeto MAUI. Em qualquer caso, é melhor não deixar a decisão para a última hora, pois os prazos do Play são fixos.