KappS Base de conhecimento · Blog

Google Play Biblioteca de cobrança em 2026

Blog Guia

Todo app Android que vende algo — uma assinatura, um desbloqueio único, um pacote de moedas — inclui uma cópia da Billing Library do Google Play. Essa biblioteca não é para sempre: o Google descontinua cada versão principal em um prazo fixo de dois anos, e quando sua versão é descontinuada, o app continua funcionando, mas você não pode mais publicar atualizações. Desde 31 de agosto de 2026, a versão mínima suportada é a Play Billing Library 8, e toda versão ainda compilada na versão 7 ou anterior tem uma única janela restante: o prazo de prorrogação de 1º de novembro de 2026.

Esta é a versão operacional dessa migração: o que a tabela de descontinuação realmente diz hoje, como descobrir qual versão um determinado APK carrega, os renomes exatos de API que quebram a compilação ao pular da 7 para a 8 ou a 9, onde fica o formulário de extensão e o que testar antes de publicar a build.

Quatro números decidem esta migração: 2 anos — o ciclo de descontinuação aplicado a cada versão principal da Play Billing Library desde que o Google anunciou a política no I/O 2019. 31 de agosto de 2026 — a data até a qual apps novos e atualizações devem usar a versão 8 ou posterior (este é o prazo da v7). 1º de novembro de 2026 — o prazo de prorrogação para a mesma versão. 8 — a versão mais baixa que o Google Play aceita em uma nova versão hoje.

1. Onde o prazo realmente está hoje

O banner na própria página Google de descontinuação da versão da Play Billing Library diz: "Até 31 de agosto de 2026, todos os novos apps e atualizações de apps existentes devem usar a Billing Library versão 8 ou superior. Se você precisar de mais tempo para atualizar seu app, pode solicitar uma extensão até 1º de novembro de 2026." Essa frase é a regra inteira, e ela tem duas metades que as pessoas confundem.

A primeira metade é uma restrição de publicação, não uma remoção: um app que ainda carrega uma versão descontinuada continua funcionando para os usuários que já o instalaram, mas o Play não aceitará seu novo lançamento. O FAQ de descontinuação afirma o corolário com clareza — APKs sem manutenção não precisam ser atualizados, enquanto novos apps e atualizações devem usar uma versão suportada. Portanto, o perfil de risco não é "meu app desaparece da loja". É "não consigo publicar a correção, o novo experimento da ficha do app na loja ou a atualização de conformidade até que isso seja resolvido".

A segunda metade é a saída de emergência: a extensão. Ela é solicitada dentro do Play Console e é concedida com base na mesma data-limite fixa, e não em uma nova contagem regressiva — então a pergunta prática para quem ainda está na v7 no fim de setembro de 2026 não é se há tempo, mas se a extensão já foi protocolada.

2. O relógio da descontinuação é fixo e é publicado com antecedência

O Google publicou a tabela completa de descontinuação, e vale lê-la como um cronograma, não como um aviso. Cada versão principal tem um prazo de "novo app e atualização" em 31 de agosto e um prazo de prorrogação em 1º de novembro, dois anos depois:

  • Versão 5 — prazo para novos apps e atualizações: 31 de agosto de 2024; prazo de extensão: 1º de novembro de 2024.
  • Versão 6 — 31 de agosto de 2025; prorrogação em 1º de novembro de 2025.
  • Versão 7 — 31 de agosto de 2026; prorrogação em 1º de novembro de 2026.
  • Versão 8 — 31 de agosto de 2027; prorrogação em 1º de novembro de 2027.
  • Versão 9 — 31 de agosto de 2028; prorrogação em 1º de novembro de 2028.

Duas conclusões se seguem. Primeiro, um app que já estava duas versões atrasado em 2025 agora está três atrasado, e o trabalho hoje é o mesmo que seria naquela época. Segundo, isso é um item permanente de manutenção, não um projeto pontual: qualquer que seja a versão que você escolher desta vez, você estará de volta aqui em no máximo dois anos. Agendar a atualização junto com o seu ciclo regular de lançamentos é mais barato do que reagir a um aviso do Console.

3. Etapa 1 — descubra o que sua versão realmente entrega

Comece pelo build.gradle. A Billing Library é declarada como dependência em com.android.billingclient:billing, e a string de versão dela é a sua resposta:

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

O FAQ de descontinuação acrescenta um detalhe importante: essas dependências só aparecem em APKs que exigem a permissão com.android.vending.BILLING. Em um projeto multimódulo, ou em um portfólio em que alguns apps usam um módulo compartilhado mais antigo, o build problemático é o que declara cobrança — não necessariamente o app em que você está pensando. Audite todo bundle que inclui cobrança, não só aqueles para os quais você lembra de ter escrito código de pagamento.

Há também uma verificação de segundo nível que explica um aviso persistente. O Play identifica a versão da biblioteca pelo atributo com.google.android.play.billingclient.version no AndroidManifest.xml mesclado. Se você já atualizou a dependência e o Console ainda reporta uma versão obsoleta, a orientação oficial é confirmar que esse atributo existe — a mesclagem de manifest é o motivo habitual de ele desaparecer.

4. Etapa 2 — escolha seu alvo: versão 8 ou versão 9

O requisito é "versão 8 ou posterior", o que significa que tanto a 8.x quanto a 9.x o atendem. O trade-off é real, então faça essa escolha de forma deliberada.

  • Versão 8 — lançada em 30 de junho de 2025; a linha 8.x terminou com a 8.3.0 em 23 de dezembro de 2025. É o diff menor e, se o seu código está na v7, os erros de compilação são poucos e mecânicos.
  • Versão 9 — 9.0.0 lançada em 19 de maio de 2026 e 9.1.0 lançada em 18 de junho de 2026. APIs mais recentes, e atualiza o targetSdkVersion para 35, o que vale ponderar contra qualquer requisito de nível de API que você já esteja tratando para a política de nível de API de destino do Play.

Se você também está lendo isto para planejar o ciclo seguinte: o prazo do próprio v8 é 31 de agosto de 2027, com a extensão até 1º de novembro de 2027. Migrar para o 9.1.0 hoje garante a maior margem de tempo, e o guia de migração do v9 foi escrito para equipes que vêm direto do 7 ou do 8.

5. Etapa 3 — a própria migração da v7 para a v8

Conforme o guia oficial de migração para a Play Billing Library 8, a atualização consiste em três movimentos mais trabalho opcional.

Primeiro passo: atualizar a dependência. Aponte com.android.billingclient:billing para 8.0.0 ou superior (use o patch mais recente da linha, não a versão .0, a menos que tenha um motivo).

Segunda mudança: trate as APIs de assinatura renomeadas. São essas chamadas que quebram a compilação quando você vem do PBL 6; as alternativas são renomeações diretas:

  • setOldSkuPurchaseToken → setOldPurchaseToken
  • setReplaceProrationMode → setSubscriptionReplacementMode
  • setReplaceSkusProrationMode → setSubscriptionReplacementMode

Terceira mudança: corrija queryProductDetailsAsync. Há uma mudança de assinatura em ProductDetailsResponseListener.onProductDetailsResponse, que exige alterações de código na sua implementação. A mudança de comportamento por trás dela importa mais que a assinatura: antes da 8.0.0, produtos que não podiam ser buscados simplesmente não eram retornados; com o PBL 8, eles voltam com um novo código de status no nível do produto que explica o motivo — produto não encontrado ou nenhuma oferta disponível para aquele usuário. Se sua interface antes inferia "este usuário não é elegível" a partir do silêncio, agora ela precisa ler o status em vez de adivinhar.

Também removidos no PBL 8 se o seu código ainda chama algum deles: queryPurchaseHistoryAsync (use as alternativas em Consultar histórico de compras), querySkuDetailsAsync (use queryProductDetailsAsync), o enablePendingPurchases() sem parâmetros (use enablePendingPurchases(PendingPurchaseParams)) e a sobrecarga antiga queryPurchasesAsync(String skuType, PurchasesResponseListener). Leitores na v6 ou anterior que forem direto para a v8 também precisam sair de enableAlternativeBilling / AlternativeBillingListener / AlternativeChoiceDetails, substituídos por enableUserChoiceBilling / UserChoiceBillingListener / UserChoiceDetails.

Opcional, mas vale a pena: BillingClient.Builder.enableAutoServiceReconnection() permite que a biblioteca restabeleça sozinha a conexão com o serviço Play Billing, em vez de exigir que você chame startConnection() novamente após uma desconexão — a causa mais comum de relatos de "o botão de compra não faz nada" no Android. A mesma versão adiciona suporte a compras pendentes para planos pré-pagos e assinaturas de parcelamento virtual.

6. Etapa 4 — ou vá direto para a 9.1.0

O guia de migração para a Play Billing Library 9 atende equipes que vêm da versão 7 ou 8. Além do ajuste de dependência para 9.1.0, o tema recorrente é que o vocabulário legado de SKU finalmente desaparece (BillingClient.SkuType → ProductType, SkuDetails → ProductDetails, SkuDetailsParams → QueryProductDetailsParams, SkuDetailsResponseListener → ProductDetailsResponseListener, getSkuDetailsList/setSkuDetailsList → setProductDetailsParamsList), e uma mudança afeta diretamente a lógica de receita com assinaturas:

Se você usava queryPurchaseHistoryAsync para decidir se um usuário tem direito a um teste gratuito, o guia recomenda usar ProductDetails.getSubscriptionOfferDetails() para determinar a quais ofertas um usuário tem direito.

Três mudanças menores da v9 passam fácil despercebidas. O tratamento de Play Store bloqueada mudou os códigos de resposta: quando o próprio app da Play Store está bloqueado (modos infantis de OEM, por exemplo), o código de resultado passou de ERROR para BILLING_UNAVAILABLE com uma mensagem de depuração "Play Store is blocked", e isso exige a versão 1.9 ou superior do androidx.core para funcionar corretamente. DeveloperProvidedBillingDetails.getLinkUri() agora é @Nullable, então qualquer código que abra esse URI sem verificar se é nulo ou string vazia é um crash em potencial. E a 9.0.0 adiciona mensagens no app para aumentos de preço com aceitação, que mostram aos usuários o aumento pendente sem sair do app — limitadas a uma mensagem a cada sete dias.

7. Etapa 5 — o formulário de prorrogação, se você precisar

Se seu app ainda está sendo distribuído com uma versão sem suporte, o Play Console exibe um aviso. A extensão é solicitada na página de detalhes do aviso: abra Status da política, abra o aviso e use o formulário de extensão vinculado ali. Oficialmente, essa é a única via — não há solicitação por e-mail, nem uma segunda extensão além da data publicada de 1º de novembro para a versão em questão.

Trate isso como uma margem de segurança dentro de um prazo já fixo, não como tempo extra. Se você protocolar a prorrogação, o trabalho ainda precisa ser feito antes de 1º de novembro de 2026, e depois dessa data novos lançamentos na v7 deixam de ser aceitos — incluindo a versão de conformidade que você talvez esteja aguardando por causa de uma política totalmente não relacionada.

8. Etapa 6 — verifique antes de publicar

Regressões de cobrança não aparecem como falhas; elas aparecem como usuários pagantes que não conseguem comprar. Antes de a versão ir para produção:

  • Faça uma compra real, um upgrade ou downgrade de assinatura e uma restauração, usando testadores de licença em um dispositivo que realmente tenha a Play Store instalada — emuladores sem ela não exercitam o tratamento de conexão que você acabou de alterar.
  • Confirme que a chamada de detalhes do produto agora retorna os produtos não buscados com seus códigos de status, e que a interface mostra a mensagem certa para "não encontrado" versus "nenhuma oferta disponível para este usuário".
  • Verifique se o aviso de descontinuação desaparece no Play Console após o lançamento e se o atributo com.google.android.play.billingclient.version está presente no manifesto mesclado.
  • Faça o lançamento em etapas para que uma regressão de cobrança atinja uma fração dos usuários em vez de todos, com um código de versão mais alto pronto para substituí-la.

9. O que as versões mais recentes devolvem no lado da receita

A migração é trabalho cobrável, então é justo considerar o que a biblioteca mais recente oferece. O PBL 8.0.0 renomeou "itens dentro do app" para produtos de compra única e adicionou múltiplas opções de compra e ofertas para eles, o que reduz o número de produtos separados que você precisa criar para vender a mesma coisa em faixas de preço diferentes. Também adicionou códigos de sub-resposta ao launchBillingFlow(): PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS, USER_INELIGIBLE (o usuário não atende aos requisitos de elegibilidade configurados para uma oferta de assinatura) e o padrão NO_APPLICABLE_SUB_RESPONSE_CODE — a diferença entre um vago "algo deu errado" e uma tela que orienta o usuário a recarregar o cartão.

As versões 8.2.x e 8.3.0 (dezembro de 2025) adicionaram as APIs de links de conteúdo externo, ofertas externas e pagamentos externos, e a 9.1.0 adicionou as APIs de Billing Choice. Se o seu roteiro inclui algum desses programas, o salto de versão é o pré-requisito, não um projeto separado — o que é o argumento prático para ir para a 9.1.0 enquanto você já está neste código.


Gerencia contas de desenvolvedor em escala? Cuidamos do lado operacional.

Clique para escolher um arquivo · clique com o botão direito → Colar, ou pressione Ctrl/⌘+V para colar uma captura de tela

Você também pode arrastar um arquivo para esta caixa.

Respondemos ao e-mail que você fornecer. Seus dados ficam com KappS.

✔ Enviado

Recebemos sua mensagem e responderemos em até 24 horas.


← Voltar para editar