Guia das mudanças em assinaturas de maio de 2022

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, PENDING ou CANCELED.
  • 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 subscriptionId das 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:
  • O pagamento está pendente:
    • SUBSCRIPTION_STATE_PENDING (novas compras com transação pendente)
    • SUBSCRIPTION_STATE_IN_GRACE_PERIOD
    • SUBSCRIPTION_STATE_ON_HOLD
  • O pagamento foi recebido:
    • SUBSCRIPTION_STATE_ACTIVE
  • Teste sem custo financeiro:
    • (nenhum campo equivalente)
  • Upgrade/downgrade interrompido:
    • SUBSCRIPTION_STATE_PENDING
cancelReason, userCancellationTimeMillis, cancelSurveyResult canceledStateContext
linkedPurchaseToken linkedPurchaseToken (nenhuma mudança)
purchaseType Teste: com testPurchase
Promoção: (nenhum campo equivalente). Em breve
priceChange lineItems.autoRenewingPlan.priceChangeDetails
profileName, emailAddress, givenName, familyName, profileId subscribeWithGoogleInfo
acknowledgementState acknowledgementState (no change)
promotionType, promotionCode (nenhum campo equivalente); em breve
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.