O sistema de faturamento do Google Play é um serviço que permite vender produtos e conteúdos digitais em apps Android. Na versão de maio de 2022, mudamos a maneira como os produtos por assinatura são definidos, o que afeta o processo de venda no app e de gerenciamento no back-end. Se você estiver fazendo a integração com o Google Play Faturamento pela primeira vez, leia Como se preparar antes de começar.
Se você já vendia produtos por assinatura usando o Google Play Faturamento antes de maio de 2022, é importante entender como adotar novos recursos e, ao mesmo tempo, manter as assinaturas atuais.
A primeira coisa que você precisa saber é que todas as assinaturas, apps e integrações de back-end atuais continuam funcionando exatamente da mesma maneira que já funcionavam antes da versão de maio de 2022. Não é necessário fazer nenhuma mudança imediata, e você pode adotar esses novos recursos ao longo do tempo. Continuamos a oferecer suporte a todas as versões principais da Biblioteca Google Play Faturamento por dois anos após o lançamento. Integrações existentes com a API Google Play Developer continuam funcionando como antes.
Confira uma visão geral das atualizações de maio de 2022:
- O novo Google Play Console permite criar e gerenciar assinaturas, planos básicos e ofertas. Isso inclui assinaturas novas e migradas.
- A API Play Developer contém atualizações para oferecer suporte a novas funções de interface do Google Play Console em formato de API. Há também uma nova versão da API Subscription Purchases. Você pode usar essa API para verificar o status e gerenciar as compras de assinaturas.
- Com a versão 5 da Biblioteca Play Faturamento, seu app pode aproveitar todos os novos recursos de assinatura. Quando estiver tudo pronto para fazer upgrade para a versão 5, siga as orientações no guia de migração.
Configuração de assinaturas
Como gerenciar assinaturas no Google Play Console
A partir de maio de 2022, você verá algumas mudanças no Google Play Console.
Agora, uma única assinatura pode ter vários planos básicos e ofertas. Os SKUs de assinatura criados anteriormente agora aparecem no Play Console como novos objetos de assinatura, plano básico e oferta. Consulte Mudanças recentes em assinaturas no Play Console para encontrar descrições dos novos objetos, incluindo as funções e configurações deles. Todos os produtos de assinatura já existentes serão exibidos nesse novo formato no Google Play Console. Agora, cada SKU é representado por um objeto de assinatura contendo um único plano básico e uma oferta compatível com versões anteriores, se aplicável.
Como nas integrações mais antigas cada assinatura continha uma única oferta,
que era representada por um
objeto SkuDetails,
só é possível ter uma oferta ou plano básico por assinatura que seja compatível com versões anteriores.
O plano básico ou a oferta compatível com versões anteriores é retornado como parte de um SKU
para apps que usam o método querySkuDetailsAsync(), que foi descontinuado.
Para aprender mais sobre como configurar e gerenciar ofertas
compatíveis com versões anteriores, consulte
Entender as assinaturas.
Depois que o app passa a usar apenas queryProductDetailsAsync() e
não há mais versões antigas sendo usadas para realizar compras, não é
mais necessário ter uma oferta compatível com versões anteriores.
Como gerenciar assinaturas na API Subscriptions Publishing
A API Play Developer
tem uma nova função para compras de assinaturas. A API
inappproducts,
usada para o gerenciamento de SKUs, continua funcionando como antes, incluindo o processamento
de assinaturas e produtos de compra única. Por isso, não é necessário
fazer nenhuma mudança imediata para manter a integração do app.
No entanto, é importante observar que o Google Play Console usa apenas as novas
entidades de assinatura. Depois que você começar a editar suas assinaturas no
Console, a API inappproducts
não poderá mais ser usada para assinaturas.
Se você usou a API Publishing antes de maio de 2022, para evitar problemas,
todas as assinaturas já existentes vão aparecer como somente leitura no
Google Play Console. Se você tentar fazer mudanças, um aviso explicando essa limitação poderá
ser mostrado. Antes de fazer novas edições no Console,
atualize sua integração de back-end para usar os novos endpoints da
Subscription Publishing. Os novos endpoints
monetization.subscriptions,
monetization.subscriptions.baseplans
e
monetization.subscriptions.offers
permitem gerenciar todos os planos básicos e promoções disponíveis. Confira
na tabela a seguir como os diferentes campos são associados à entidade InAppProduct para
os novos objetos em monetization.subscriptions.
| InAppProduct | Assinatura |
|---|---|
packageName |
packageName |
sku |
productId |
status |
basePlans[0].state |
prices |
basePlans[0].regionalConfigs.price |
listings |
listings |
defaultPrice |
Sem equivalência |
subscriptionPeriod |
basePlans[0].autoRenewingBasePlanType.billingPeriodDuration |
trialPeriod |
basePlans[0].offers[0].phases[0].regionalConfigs[0].free |
gracePeriod |
basePlans[0].autoRenewingBasePlanType.gracePeriodDuration |
subscriptionTaxesAndComplianceSettings |
taxAndComplianceSettings |
Esta atualização obrigatória da API só se aplica à API Publishing (gerenciamento de SKU).
Mudanças na Biblioteca Play Faturamento
Para possibilitar uma migração gradual, a Biblioteca Play Faturamento inclui todos os
métodos e objetos disponíveis nas versões anteriores.
Objetos e funções
SkuDetails,
como
querySkuDetailsAsync(),
ainda existem para que você possa fazer upgrade e passar a usar
a nova função
sem precisar atualizar o código das assinaturas imediatamente.
Também é possível controlar quais ofertas ficam disponíveis nesses métodos,
marcando-as como compatíveis com versões anteriores.
Além de manter os métodos legados, a Biblioteca Play Faturamento 5 agora inclui
um novo objeto ProductDetails e um método queryProductDetailsAsync()
correspondente para processar novas entidades e funções. Produtos já existentes no app,
como compras únicas e consumíveis, agora também têm suporte de
ProductDetails.
Para cada assinatura, ProductDetails.getSubscriptionOfferDetails()
retorna uma lista de todos os planos básicos e ofertas que o usuário pode comprar.
Assim, é possível acessar todos os planos básicos e ofertas disponíveis
para o usuário, não importa qual seja a compatibilidade com versões anteriores.
O método getSubscriptionOfferDetails() retorna o valor null para produtos
sem assinatura. Para compras únicas, use
getOneTimePurchaseOfferDetails().
A Biblioteca Play Faturamento 5 também inclui métodos novos e legados para
iniciar o fluxo de compra. Se o objeto BillingFlowParams transmitido para
BillingClient.launchBillingFlow()
estiver configurado com um objeto SkuDetails, o sistema vai extrair as informações
da oferta para venda da oferta ou plano compatível com versões anteriores
que corresponda à SKU. Se o objeto BillingFlowParams transmitido para
BillingClient.launchBillingFlow() for configurado usando
objetos ProductDetailsParams, que incluem ProductDetails e uma
String representando o token da oferta em
questão, o sistema vai usar essa informação para identificar o
produto que está sendo adquirido pelo usuário.
queryPurchasesAsync() retorna todas as compras
do usuário. Para indicar o tipo de produto solicitado, transmita
um valor BillingClient.SkuType, como era feito em versões mais antigas, ou um objeto
QueryPurchasesParams contendo um valor
BillingClient.ProductType que represente as novas entidades de assinatura.
Recomendamos que você atualize seus apps para a versão 5 da biblioteca assim que possível para começar a aproveitar esses novos recursos de assinatura.
Como gerenciar o status de uma assinatura
Esta seção descreve as principais mudanças que precisam ser implementadas nos componentes de back-end de uma integração ao sistema de faturamento do Google Play para migrar para a versão 5.
Notificações do desenvolvedor em tempo real
Em breve, o objeto SubscriptionNotification
não vai mais conter um subscriptionId. Se você depende desse
campo para identificar o produto por assinatura, atualize
o app e acesse essas informações no status da assinatura, usando
purchases.subscriptionv2:get
ao receber a notificação. Cada SubscriptionPurchaseLineItem
na coleção lineItems que for retornado como parte do status da compra
vai incluir o respectivo productId.
API Subscriptions Purchases: como verificar o status da assinatura
Em versões anteriores da API Subscriptions Purchases, era possível
consultar o status da assinatura usando
purchases.subscriptions:get.
Esse endpoint não mudou e continua funcionando para compras
de assinaturas compatíveis com versões anteriores. Contudo, esse endpoint não inclui suporte a nenhuma das novas
funções lançadas em maio de 2022.
Na nova versão da API Subscriptions Purchases, é necessário usar
purchases.subscriptionsv2:get
para verificar o status da compra da assinatura. Essa API é compatível com
assinaturas migradas, novas assinaturas (pré-pagas e
de renovação automática) e compras de todos os tipos. Você pode usar esse endpoint
para verificar o status da assinatura ao receber notificações. O
objeto SubscriptionPurchaseV2 retornado contém novos campos,
mas ainda inclui dados legados necessários para continuar a oferecer suporte
a assinaturas existentes.
Campos SubscriptionPurchaseV2 para planos pré-pagos
Novos campos foram adicionados para oferecer suporte aos planos pré-pagos, que são estendidos pelo usuário, e não renovados automaticamente. Todos os campos se aplicam aos planos pré-pagos da mesma maneira que às assinaturas de renovação automática, exceto:
- [Novo campo] lineItems[0].prepaid_plan.allowExtendedAfterTime: indica quando o usuário vai poder comprar outra recarga para estender o plano pré-pago, já que só é permitido ter uma recarga não consumida por vez.
- [Novo campo] SubscriptionState: especifica o estado do objeto de assinatura.
Para planos pré-pagos, esse valor é sempre
ACTIVE,PENDINGouCANCELED. - lineItems[0].expiryTime: sempre incluído em planos pré-pagos.
- paused_state_context: esse campo nunca está incluído, porque os planos pré-pagos não podem ser pausados.
- lineItems[0].auto_renewing_plan: não incluído em planos pré-pagos.
- canceled_state_context: não incluído em planos pré-pagos, porque se aplica somente a usuários que precisam executar uma ação para cancelar a assinatura.
- lineItems[0].productId: esse campo substitui
subscriptionIddas versões anteriores.
Campos SubscriptionPurchaseV2 para assinaturas recorrentes
purchases.subscriptionv2 contém novos campos que apresentam mais detalhes
sobre novos objetos de assinatura. A tabela a seguir mostra a maneira como os campos do
endpoint de assinatura legado equivalem aos campos correspondentes em
purchases.subscriptionv2.
| SubscriptionPurchase | SubscriptionPurchaseV2 |
|---|---|
countryCode |
regionCode |
orderId |
latestOrderId |
| (nenhum campo equivalente) | lineItems (lista de
SubscriptionPurchaseLineItem),
que representa os produtos adquiridos com a compra |
| (nenhum campo equivalente) | lineItems.offerDetails.basePlanId |
| (nenhum campo equivalente) | lineItems.offerDetails.offerId |
| (nenhum campo equivalente) | lineItems.offerDetails.offerTags |
startTimeMillis |
startTime |
expiryTimeMillis |
lineItems.expiryTime (cada assinatura adquirida na
compra tem um expiryTime próprio) |
| (nenhum campo equivalente) | subscriptionState (indica o
estado da assinatura) |
| (nenhum campo equivalente) | pausedStateContext (presente apenas se o status
da assinatura for SUBSCRIPTION_STATE_PAUSED) |
autoResumeTimeMillis |
pausedStateContext.autoResumeTime |
| (nenhum campo equivalente) | canceledStateContext (presente apenas se o
status da assinatura for SUBSCRIPTION_STATE_CANCELED) |
| (nenhum campo equivalente) | testPurchase (presente somente em compras de testadores
licenciados) |
autoRenewing |
lineItems.autoRenewingPlan.autoRenewEnabled |
priceCurrenceCode,
priceAmountMicros,
introductoryPriceInfo |
(nenhum campo equivalente) Essas informações podem ser encontradas no basePlan/offer de
cada uma das assinaturas compradas. |
| developerPayload | (nenhum campo equivalente) o payload do desenvolvedor foi descontinuado |
| paymentState | (nenhum campo equivalente) É possível inferir o estado do pagamento de subscriptionState:
|
cancelReason,
userCancellationTimeMillis,
cancelSurveyResult |
canceledStateContext |
linkedPurchaseToken |
linkedPurchaseToken (nenhuma mudança) |
purchaseType |
Teste: com testPurchasePromoção: signupPromotion |
priceChange |
lineItems.autoRenewingPlan.priceChangeDetails |
profileName,
emailAddress,
givenName,
familyName,
profileId |
subscribeWithGoogleInfo |
acknowledgementState |
acknowledgementState (no change) |
promotionType,
promotionCode |
signupPromotion |
externalAccountId,
obfuscatedExternalAccountId,
obfuscatedExteranlProfileId |
externalAccountIdentifiers |
Outras funções de gerenciamento de assinaturas
Embora
purchases.subscriptions:get
tenha sido atualizada para
purchases.subscriptionsv2:get,
as outras funções de gerenciamento de assinaturas do desenvolvedor continuam
inalteradas no endpoint purchases.subscriptions por enquanto,
para que você possa continuar a usar
purchases.subscriptions:acknowledge,
purchases.subscriptions:cancel,
purchases.subscriptions:defer,
purchases.subscriptions:refund
e
purchases.subscriptions:revoke
como antes.
API Pricing
Use o endpoint
monetization.convertRegionPrices
para calcular preços regionais, assim como no
Play Console. Esse método aceita um único preço em qualquer moeda que possa ser usada no Google Play
e retorna os preços convertidos (incluindo a taxa de tributação padrão,
quando aplicável) de todas as regiões em que o Google Play permite fazer compras.