KappS Base de conhecimento · Blog

Google PlayPlanos base e ofertas de assinatura

Blog Tutorial

Duas perguntas decidem quanto um assinante do Google Play realmente paga, e elas são respondidas em dois lugares diferentes. O plano base responde "qual período de cobrança, a qual preço, com renovação automática ou pré-pago?". A oferta responde "quem tem direito a um início mais barato, e por quanto tempo?". Modele as ofertas de assinatura errado e todo pedido de marketing por um teste grátis vira um produto de assinatura totalmente novo — o que fragmenta seu catálogo, divide seus relatórios entre produtos que nunca poderão ser excluídos depois que alguém os comprar e deixa o cliente com uma lógica de compra que ninguém ousa mexer.

Este tutorial segue a ordem que o Play Console e a Billing Library realmente impõem: criar o produto, configurar os planos base, adicionar ofertas com critérios de elegibilidade, ler os tokens de oferta no cliente, tratar mudanças de plano com o modo de substituição correto e, por fim, verificar o direito de acesso no seu servidor. Três coisas derrubam as equipes repetidamente ao longo do caminho — o token de oferta que o cliente precisa passar explicitamente, o modo de proporcionalidade escolhido em um upgrade e a verificação no servidor que decide se um teste gratuito é real. As últimas seções cobrem as armadilhas que só aparecem depois do lançamento: lacunas de preço regional, ofertas que nunca podem ser exibidas e uma mudança de preço que silenciosamente se torna um segundo plano base.


1. O modelo de três camadas: produto, plano base, oferta

Uma Google Play assinatura é construída em três camadas, e os ciclos de vida delas são completamente diferentes. É isso que decide se a decisão de hoje ainda poderá ser alterada daqui a dois anos.

  • Produto — o item do catálogo, identificado por um ID de produto. O ID não pode ser alterado após a criação, e um produto que alguém já comprou não pode ser excluído, apenas desativado. Nomeie-o no primeiro dia pelo que ele é, não pela promoção que está rodando neste trimestre: "first_month_half_price" é um ID permanente para uma ideia temporária.
  • Plano base — a camada que de fato define a economia: período de cobrança (semanal, mensal, 3 meses, 6 meses, anual), tipo de renovação (renovação automática ou pré-pago), preço por país, além do período de tolerância e do comportamento de retenção da conta. Um único produto pode ter vários planos base, e é exatamente assim que você vende mensal e anual lado a lado sem um segundo produto.
  • Oferta — um tratamento de preço vinculado a um plano base: um teste gratuito, um preço introdutório, um desconto de reconquista. Cada oferta tem uma condição de elegibilidade, e só usuários elegíveis chegam a vê-la.

Há uma consequência técnica que vale memorizar: o offerToken que o cliente usa para comprar é a credencial de um par específico de "plano base + oferta". Assim que um produto tem mais de um plano base, ou qualquer oferta, o token precisa ser passado explicitamente — não existe padrão. A seção 5 é onde essa regra deixa de ser curiosidade e começa a explicar falhas reais.

2. Passo 1 — crie o produto de assinatura

No Play Console, acesse Monetizar com o Play → Produtos → Assinaturas e crie uma assinatura. Esta etapa faz quatro coisas, e cada uma é irreversível ou cara mais tarde.

  1. ID do produto — letras minúsculas, dígitos e sublinhados, único dentro do app, imutável e nunca reutilizável, nem após a exclusão. Renomear significa criar um novo produto, o que significa um novo ID e um novo caminho de compra.
  2. Nome — para você reconhecer a linha no console. O que o comprador vê na tela de compra é gerado pelo Play a partir do plano base e da oferta.
  3. Descrição e benefícios — o que a assinatura inclui. Esse texto aparece em algumas telas da loja e é o que o suporte vai citar de volta para você.
  4. Salvar — você salvou um rascunho. O produto só se torna comprável quando pelo menos um plano base existe e está ativo.

O erro estrutural mais comum é criar produtos separados para mensal e anual. Aí você mantém dois fluxos de compra, dois conjuntos de estados, dois caminhos de cancelamento — sendo que o Play foi projetado para manter os dois como planos base sob um único produto. Migrar depois é doloroso, então acerte de primeira.

3. Etapa 2 — configure os planos base

Os planos base são onde está a economia da assinatura. Todo produto precisa de pelo menos um; a maioria precisa de dois (mensal e anual).

Escolha primeiro o tipo de renovação. Um plano base com renovação automática cobra novamente ao fim de cada período, que é o que a maioria das assinaturas de conteúdo e de utilitários precisa. Um plano base pré-pago vende um período fixo antecipadamente e exige que o usuário faça uma nova recarga quando ele termina — uma boa opção para mercados de preço baixo e para usuários que não querem uma cobrança recorrente. Os dois não se misturam: um plano pré-pago não tem ciclo de renovação, não tem o conceito de período de tolerância e não pode incluir um teste gratuito. Se os testes fazem parte do seu plano de crescimento, o plano principal precisa ser com renovação automática.

Depois, defina o período e os preços. O período define o ritmo de cobrança; os preços são inseridos por país e região. Esta é a fonte mais confiável de tickets de suporte: o Play permite definir preço só para alguns países, e um país sem preço simplesmente não é comprável. Os compradores de lá veem "item não disponível no seu país", o que parece um bug para eles e não parece nada no seu console. Antes do lançamento, preencha todos os mercados-alvo e confira se o preço exibido atende às regras locais de representação tributária.

Por fim, as configurações de ciclo de vida — elas decidem o que acontece quando uma cobrança falha, não quando dá certo:

  • Período de tolerância — uma janela após uma cobrança malsucedida em que o usuário mantém o direito de acesso, ganhando tempo para corrigir o método de pagamento.
  • Retenção da conta — quando o período de tolerância termina sem pagamento, o direito é suspenso, mas o registro da assinatura é mantido, então pagar depois o restaura.
  • Reassinar — permite que um usuário que cancelou volte no mesmo plano em vez de percorrer o fluxo de compra novamente.

Os padrões aqui não são automaticamente corretos. Apps utilitários geralmente querem um período de tolerância e retenção da conta; apps de conteúdo podem preferir um downgrade mais rápido. Seja qual for a sua escolha, o mapeamento no servidor precisa corresponder, porque a API de estado de assinatura distingue período de tolerância de retenção da conta — juntar os dois em "válido" descarta essa informação.

4. Etapa 3 — adicione ofertas e critérios de elegibilidade

As ofertas são a alavanca de conversão e a camada mais frequentemente mal configurada. Toda oferta carrega três coisas: um ID de oferta, uma ou mais fases e uma condição de elegibilidade.

Fases definem como a oferta se desenrola no tempo. Uma fase é uma avaliação gratuita (preço zero, um número de dias) ou um preço com desconto (um número de períodos por um valor determinado). As fases podem ser empilhadas, por exemplo "7 dias grátis, depois 50% de desconto no primeiro mês" — mas a ordem das fases é a ordem em que o usuário realmente paga, então invertê-las significa cobrar primeiro e dar de graça depois, o que atrai tanto tickets de suporte quanto questionamentos na revisão.

Elegibilidade é o interruptor que decide quem chega a ver a oferta. O Play oferece três condições:

  • Novo assinante — nunca assinou este produto. A condição usual para um teste gratuito.
  • Upgrade — atualmente contém outra assinatura que se qualifica como destino de upgrade.
  • Reconquista — assinou antes e depois cancelou ou expirou. Muito mais preciso do que um cupom genérico, e não contamina o preço que novos usuários veem.

As tags de oferta não são decoração. Elas acompanham a compra e são a única forma limpa de separar, mais tarde, as conversões de teste das compras a preço cheio nos seus próprios relatórios e na lógica do servidor. Se você as ignorar, três meses depois não conseguirá responder se os testes geraram retenção.

Uma oferta afeta apenas novas compras. Editar ou desativar uma oferta não altera a cobrança dos assinantes que já estão nela. Por outro lado, para dar um novo preço aos assinantes existentes você precisa do fluxo de alteração de preço — não de outra oferta.

Vale registrar duas fronteiras. Cada plano base só pode carregar um número limitado de ofertas, então as promoções devem ser reaproveitadas em vez de criadas sem parar. E quando um plano base está inativo, toda oferta abaixo dele fica invendável: quando uma oferta "não aparece", verifique primeiro o estado do plano base, depois a elegibilidade e, por último, o código do cliente.

5. Etapa 4 — ler o token de oferta correto no cliente

Os detalhes do produto retornam uma list, não um preço único. Consultar uma assinatura retorna subscriptionOfferDetails, em que cada entrada é uma combinação de "plano base + oferta" que carrega um basePlanId, um offerId (que pode estar vazio, significando o próprio caminho de preço cheio do plano base) e um offerToken.

Comprar significa entregar explicitamente uma entrada dessa lista ao fluxo de cobrança: construa o ProductDetailsParams para a compra e defina o offerToken selecionado nele. A regra é simples, e o custo de quebrá-la é imediato:

  • Um plano base e nenhuma oferta — o token pode ser omitido, embora passá-lo explicitamente seja mais seguro entre versões da biblioteca.
  • Vários planos base, ou qualquer oferta — omitir o token faz a compra falhar. Essa é a causa raiz por trás do clássico "o mensal funciona, o anual dá erro".
  • O preço mostrado na interface deve vir da entrada que você selecionou, nunca do primeiro elemento da lista. Exibir $4.99 enquanto cobra $49.99 é o bug mais caro deste artigo.

Escreva a regra de seleção em vez de confiar na ordem da lista: encontre o plano base pelo basePlanId que você reconhece, depois escolha a oferta de maior prioridade dentro dele que a lista retornada realmente contenha e, quando nenhuma oferta estiver disponível, use a entrada de preço cheio do plano base. A elegibilidade é responsabilidade do Play — a lista que você recebe já é "o que este usuário pode comprar agora", então não reimplemente as regras de elegibilidade localmente nem tente adivinhar.

Durante os testes, use uma conta de teste de licença e lembre-se de que a elegibilidade também se aplica aos testadores: uma conta que já assinou não verá uma oferta para novos assinantes. Esse é o comportamento esperado, não um código quebrado. Para verificar se um teste gratuito é exibido, uma conta nova é o caminho mais rápido.

6. Etapa 5 — upgrades, downgrades e modos de substituição

Mover um usuário do mensal para o anual, ou de um nível básico para um premium, é uma substituição, não uma segunda compra. Como essa substituição se comporta é decidido pelo modo de substituição, e escolher errado significa cobrar o usuário duas vezes ou deixar dinheiro na mesa por um período inteiro.

  • Com proporção por tempo — entra em vigor imediatamente e credita o valor restante da assinatura antiga na nova, então o usuário paga a diferença agora.
  • Cobrar preço proporcional — entra em vigor imediatamente e cobra o valor proporcional de uma vez; costuma ser usado em downgrades para que o usuário não consuma primeiro e pague depois.
  • Cobrar o preço cheio — entra em vigor imediatamente pelo preço cheio do novo plano, sem crédito pelo período restante; razoável só quando o valor em jogo é menor que o custo de rateá-lo.
  • Sem proporcionalidade — entra em vigor imediatamente, a nova assinatura é cobrada a partir do próximo ciclo, e o restante do período antigo simplesmente termina. O mais gentil com o usuário, o menos lucrativo para você, e um padrão sensato para downgrades.

Na Billing Library 8 o ponto de entrada é unificado como setSubscriptionReplacementMode; os nomes de método mais antigos de versões anteriores da biblioteca estão descontinuados. Se o seu código ainda os chama, o erro de compilação é um presente — mais barato do que descobrir no meio do lançamento gradual que a semântica é diferente.

Planos base pré-pagos não participam da substituição: eles não têm ciclo de renovação e expiram no próprio cronograma. Qualquer aviso de "mudar de mensal para anual" precisa excluir usuários pré-pagos, ou você mostrará a eles um botão que nunca pode ser concluído.

Uma regra de ordenação: uma solicitação de substituição ou falha ou entra em vigor, nunca parcialmente. Então não conceda o direito local no cliente antes de enviá-la — espere até que o servidor tenha a nova credencial de compra e só então libere.

7. Passo 6 — verifique e confirme no seu servidor

O que o cliente devolve é apenas "o usuário diz que comprou". O direito de acesso é decidido no servidor: chame a consulta de assinatura (purchases.subscriptionsv2) com o token de compra, obtenha o estado e a validade oficiais e grave isso na sua própria tabela de direitos.

O campo de estado indica em qual segmento o usuário está — ativo, em período de tolerância, em espera, pausado, cancelado, expirado, pendente. Esses estados se mapeiam diretamente para as ramificações de direito: o período de tolerância geralmente mantém o acesso, a espera por conta geralmente o restringe, a pausa deve interromper o serviço mantendo os dados. Fixar o mapeamento em "válido ou inválido" joga fora justamente as distinções que o Play oferece.

Depois, duas ações fáceis de esquecer. Confirme a compra em até três dias, ou ela é reembolsada automaticamente; fazer isso pelo servidor é mais confiável do que confiar no cliente. E configure as notificações em tempo real para desenvolvedores para que renovações, cancelamentos, entradas em período de tolerância, recuperações e confirmações de mudança de preço cheguem até você. Uma notificação é um sinal para ir verificar, não o estado final: busque a assinatura completa depois, deduplique pelo ID da mensagem e processe de forma idempotente.

Acerte essas três camadas e o ciclo se fecha: o cliente inicia, o servidor decide, as notificações mantêm tudo em dia.

8. As armadilhas que só aparecem depois do lançamento

Esses problemas raramente aparecem nos testes e chegam todos de uma vez com o tráfego real.

  • Lacunas de preço regional — um novo mercado é adicionado e a tabela de preços não é preenchida, então os compradores de lá veem "não disponível". Percorrer a tela de compra uma vez com uma conta daquela região é melhor do que confiar na tabela do console.
  • Alterar o preço do jeito errado — editar um plano base existente inicia o fluxo de alteração de preço, no qual os assinantes atuais precisam confirmar antes que o novo preço passe a valer. Se o objetivo é "usuários antigos mantêm o preço antigo, usuários novos pagam o novo", a resposta habitual é criar um novo plano base e mudar o que você vende, não editar. Decida qual resultado você quer antes de mexer no preço.
  • Desativar uma oferta com assinantes ativos — a desativação bloqueia apenas novas compras; os assinantes existentes mantêm a oferta até o fim do período. Não é um bug, mas é um roteiro de suporte que você deveria ter pronto.
  • Transformar cada promoção em um novo produto — você acaba com produtos que não podem ser excluídos, relatórios fragmentados e uma lógica de cliente que ninguém vai refatorar.
  • Esquecer as tags de oferta — sem elas você não consegue separar conversões de teste das compras diretas, então não dá para dizer qual promoção de fato reteve.
  • Visível para testadores, invisível para usuários — a elegibilidade se aplica também a contas de teste. Verificar com uma conta limpa é o caminho de depuração mais rápido que você tem.

9. Onde o KappS se encaixa

A configuração de assinaturas é uma decisão de produto, mas roda sobre contas que precisam permanecer em conformidade por anos: perfil de pagamentos, informações fiscais, status de verificação do desenvolvedor. Se qualquer um desses quebrar, a cadeia de receita quebra no pior momento possível. O KappS prepara e envia material em conformidade e mantém as contas e o estado de publicação saudáveis, para que essas precondições deixem de ser uma variável.

  • Consistência entre conta e pagamentos — identidade do desenvolvedor, perfil de pagamentos e o beneficiário real alinhados, para que a liquidação não trave por dados divergentes.
  • Revisão de impostos e configuração regional — W-8BEN/W-9, alíquotas de retenção e mercados-alvo conferidos antes do lançamento, não depois de um repasse chegar a menor.
  • Um segundo par de olhos na configuração — planos base, elegibilidade a ofertas e tratamento de tokens no lado do cliente, especialmente em portfólios com vários produtos, regiões e idiomas.

Não oferecemos nada que contorne as regras das plataformas: preços e testes precisam ser reais, a elegibilidade precisa seguir as definições do Play, e toda compra precisa passar pela verificação do lado do servidor. Essas são as regras e também a única versão disso que continua funcionando.

Fontes (documentação do Google): Play Console Help — criar e configurar assinaturas, planos base, ofertas e elegibilidade, planos pré-pagos; Android Developers — integração do Play Billing, modos de substituição de assinatura, verificação no servidor, notificações em tempo real para desenvolvedores.

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