Este artigo descreve como migrar da versão 4 ou 5 para a versão 6 da Biblioteca Google Play Faturamento e como usar os novos recursos de assinatura.
Para conferir uma lista completa das mudanças na versão 6.0.0, consulte as notas da versão.
Visão geral
A Biblioteca Google Play Faturamento 6 usa como base os novos recursos de assinatura apresentados na versão 5 e adiciona mais algumas melhorias. Esses recursos permitem vender assinaturas de mais maneiras, reduzindo custos operacionais ao eliminar a necessidade de criar e gerenciar um número cada vez maior de SKUs.
Para saber mais sobre os novos recursos apresentados com a Biblioteca Play Faturamento 5, consulte Mudanças recentes em assinaturas no Play Console.
Upgrade da Biblioteca Play Faturamento para ser compatível com versões anteriores
Todos os produtos por assinatura já existentes foram convertidos automaticamente para esse novo paradigma como parte do lançamento da Biblioteca Play Faturamento 5 e da nova plataforma de assinaturas em maio de 2022. Isso significa que você não precisa fazer mudanças na configuração do produto por assinatura para ter um catálogo compatível com as novas versões da Biblioteca Play Faturamento. Para saber mais sobre como as SKUs de assinatura foram convertidas para assinaturas compatíveis com versões anteriores, consulte Como trabalhar com assinaturas mais antigas na seção Artigo de ajuda do Play Console.
Versões anteriores do app ainda funcionam
Se você tiver um catálogo de assinaturas compatível com versões anteriores, todas as versões atuais do app ainda vão funcionar conforme o esperado para esses produtos. As compras de produtos únicos também continuarão funcionando sem problemas em versões mais antigas.
As versões do app que usam métodos descontinuados (por exemplo,
querySkuDetailsAsync()
)
não poderão vender planos básicos ou opções que não sejam compatíveis
com versões anteriores. Leia sobre as opções de assinatura compatíveis com versões anteriores no artigo relevante da Central de Ajuda
do Play
Console.
Fazer upgrade para a Biblioteca Play Faturamento 5 ou 6
As Bibliotecas Play Faturamento 5 e 6 incluem os métodos descontinuados
querySkuDetailsAsync
e BillingFlowParams.Builder.setSkuDetails
, que usam
SkuDetails
como um parâmetro de
fluxo de faturamento. Isso significa que você pode migrar gradualmente para a Biblioteca Play Faturamento 6
planejando diferentes estágios da migração.
Como primeira etapa para a migração, atualize a versão da
biblioteca, deixe o catálogo e o back-end como estão e teste
o app enquanto ele ainda usa os métodos descontinuados. Se você não estiver usando
queryPurchases
, launchPriceChangeFlow
ou setVrPurchaseFlow
, ele ainda
funcionará como pretendido. Depois disso, teste a adoção total dos novos
recursos de assinatura lançados em maio de 2022.
Se você já adotou esses recursos com uma migração da Biblioteca Google Play Faturamento 5, prossiga para as seções Atualizar a Biblioteca Google Play Faturamento e Mudar as compras de assinatura de um usuário. Se você estiver começando com uma versão anterior ou ainda não tiver adotado totalmente os novos recursos, leia a seção Etapas completas de migração a seguir para aprender a adotá-los.
Etapas completas de migração
Criar novas assinaturas no catálogo de produtos de back-end
Com o Play Console ou a API Play Developer, é possível configurar uma única assinatura com vários planos básicos, cada um com várias opções. As opções de assinatura têm modelos de preços e tipos de qualificação flexíveis. Crie opções no ciclo de vida da assinatura usando uma variedade de planos pré-pagos e de renovação automática.
Recomendamos criar novos produtos de acordo com a estrutura da entidade na nova plataforma de assinaturas para integração da Biblioteca Play Faturamento 6 antes de migrar o app. É possível consolidar produtos duplicados no catálogo antigo com os mesmos benefícios de direito em uma única assinatura e usar configurações de plano básico e de opções de assinatura para representar tudo que você quer oferecer. Para saber mais sobre essa recomendação, consulte a seção Como trabalhar com assinaturas mais antigas do artigo de ajuda do Play Console.
Não modifique os produtos de assinatura convertidos após o
lançamento de maio de 2022. Eles serão vendidos com as versões do
app usando métodos descontinuados (por exemplo, querySkuDetailsAsync()
), sem apresentar mudanças que
possam afetar esses builds mais antigos.
O processo de conversão transformou os produtos de assinatura que estavam no seu catálogo antes de maio de 2022 em somente leitura para evitar mudanças acidentais que poderiam resultar em problemas com a integração atual. É possível fazer mudanças nessas assinaturas, mas há implicações que podem afetar suas integrações de front-end e back-end:
No front-end, as versões do app que usam
querySkuDetailsAsync()
para receber detalhes do produto por assinatura só podem vender opções e planos básicos compatíveis com versões anteriores. Além disso, só pode haver um plano básico ou combinação de opções de assinatura compatível com versões anteriores. Se você adicionar novos planos ou opções às assinaturas convertidas, eles não poderão ser vendidos nessas versões anteriores do app.No back-end, se você editar suas assinaturas convertidas na interface do Play Console, não vai poder gerenciá-las com o endpoint
inappproducts
quando chamar o endpoint para essa finalidade. Também é possível migrar para o novo endpoint de status de compra de assinatura (purchases.subscriptionsv2.get
) para gerenciar compras dessas assinaturas, já que o endpoint do status de compra antigo (purchases.subscriptions.get
) retorna apenas os dados necessários para processar compras de opções de assinatura e planos básicos compatíveis com versões anteriores. Consulte a seção Gerenciar o status de compra da assinatura para saber mais.
Gerenciar seu catálogo de assinaturas de back-end com a nova API
Se você gerencia seu catálogo de produtos por assinatura automaticamente com a API Google Play Developer, é necessário usar os novos endpoints de definição do produto por assinatura para criar e gerenciar assinaturas, planos básicos e opções. Leia o guia de recursos de assinatura de maio de 2022 para saber mais sobre as mudanças na API do catálogo de produtos para essa versão.
Para migrar um módulo de gerenciamento de catálogo de produtos automático de
assinaturas do Google Play Faturamento, substitua a API
inappproducts
pela nova API Subscription Publishing a fim de gerenciar e publicar
seu catálogo de assinaturas. Há três novos endpoints:
Monetization.subscriptions
, para gerenciar produtos por assinatura.Monetization.basePlans
, para gerenciar planos básicos de assinaturas.Monetization.offers
, para gerenciar opções de planos básicos.
Esses novos endpoints têm todas as funcionalidades necessárias para aproveitar os novos recursos no seu catálogo: tags de opções de assinaturas e plano básico, segmentação por região, planos pré-pagos e muito mais.
Use a API
inappproducts
para gerenciar seu catálogo de produtos no app para compras únicas.
As versões do app que usam métodos descontinuados (por exemplo, querySkuDetailsAsync()
) não poderão vender planos básicos ou opções de assinatura que não sejam compatíveis com versões anteriores. Leia sobre as opções de assinatura compatíveis com versões anteriores neste link.
Atualizar a Biblioteca Google Play Faturamento
Depois de criar o novo catálogo de produtos por assinatura,
você pode migrar o app para a Biblioteca Google Play Faturamento 5 do Google. No arquivo build.gradle
do app,
substitua a dependência da Biblioteca Play Faturamento existente pela
versão atualizada.
dependencies {
def billingVersion = "6.0.0"
implementation "com.android.billingclient:billing:$billingVersion"
}
O projeto será criado imediatamente, mesmo que você não tenha modificado as chamadas para métodos, já que a Biblioteca Play Faturamento 6 é compatível com versões anteriores. O conceito de SKU é considerado descontinuado, mas ainda está presente para tornar a portabilidade de apps um processo mais simples e incremental.
Inicializar o cliente de faturamento e estabelecer uma conexão com o Google Play
As primeiras etapas necessárias para lançar compras em um app Android continuam as mesmas:
Mostrar produtos disponíveis para compra
Para acessar todas as opções de assinatura que os usuários podem comprar, siga estas etapas:
- Substitua
SkuDetailsParams
porQueryProductDetailsParams
. - Troque a chamada
BillingClient.querySkuDetailsAsync()
porBillingClient.queryProductDetailsAsync()
.
Agora, os resultados da consulta serão ProductDetails
, em vez de SkuDetails
.
Cada item ProductDetails
contém as informações sobre o produto,
como ID, título, tipo, entre outros. Para produtos por assinatura, ProductDetails
contém um List<ProductDetails.SubscriptionOfferDetails>
, que é a
lista de detalhes da opção de assinatura. Para produtos de compra única,
ProductDetails
contém um ProductDetails.OneTimePurchaseOfferDetails
. Essas funções
podem ser usadas para decidir quais opções vão aparecer para os usuários.
O exemplo a seguir mostra como o app pode ficar antes e depois dessas mudanças.
Antes
Kotlin
val skuList = ArrayList<String>() skuList.add("up_basic_sub") val params = SkuDetailsParams.newBuilder() params.setSkusList(skuList).setType(BillingClient.SkuType.SUBS).build() billingClient.querySkuDetailsAsync(params) { billingResult, skuDetailsList -> // Process the result }
Java
List<String> skuList = new ArrayList<>(); skuList.add("up_basic_sub"); SkuDetailsParams.Builder params = SkuDetailsParams.newBuilder(); params.setSkusList(skuList).setType(SkuType.SUBS).build(); billingClient.querySkuDetailsAsync(params, new SkuDetailsResponseListener() { @Override public void onSkuDetailsResponse(BillingResult billingResult, List<SkuDetails> skuDetailsList) { // Process the result. } } );
Depois
Kotlin
val productList = listOf( QueryProductDetailsParams.Product.newBuilder() .setProductId("up_basic_sub") .setProductType(BillingClient.ProductType.SUBS) .build() ) val params = QueryProductDetailsParams.newBuilder().setProductList(productList).build() billingClient.queryProductDetailsAsync(params) { billingResult, productDetailsList -> // Process the result }
Java
ImmutableList<Product> productList = ImmutableList.of(Product.newBuilder() .setProductId("up_basic_sub") .setProductType(ProductType.SUBS) .build()); QueryProductDetailsParams params = QueryProductDetailsParams.newBuilder() .setProductList(productList) .build(); billingClient.queryProductDetailsAsync( params, new ProductDetailsResponseListener() { public void onProductDetailsResponse(BillingResult billingResult, List<ProductDetails> productDetailsList) { // Process the result } } );
O callback para queryProductDetailsAsync
retorna uma List<ProductDetails>
.
Cada item ProductDetails
contém as informações sobre o produto,
como ID, título, tipo, entre outros. A principal diferença é que os produtos
por assinatura agora também têm uma List<ProductDetails.SubscriptionOfferDetails>
,
que inclui todas as opções disponíveis para o usuário.
Como as versões anteriores da Biblioteca Play Faturamento não oferecem suporte aos novos
objetos, como assinaturas, planos básicos, opções, entre outros, o novo sistema
converte cada SKU de assinatura em uma única opção ou plano básico
compatível com versões anteriores. Os produtos de compra única disponíveis também são
transferidos para um objeto ProductDetails
. Os detalhes de um produto de
compra única podem ser acessados com o
método getOneTimePurchaseOfferDetails()
.
Em raros momentos, alguns dispositivos não têm suporte a ProductDetails
e queryProductDetailsAsync()
.
Isso costuma ocorrer devido a versões desatualizadas do
Google Play Services. Para garantir
o suporte adequado a esse cenário, chame
isFeatureSupported()
para PRODUCT_DETAILS
antes de chamar queryProductDetailsAsync
. Se a resposta for
OK
,
o dispositivo vai oferecer suporte ao recurso e você poderá continuar chamando queryProductDetailsAsync()
.
Se ela for FEATURE_NOT_SUPPORTED
,
solicite a lista de produtos compatíveis com versões anteriores usando
querySkuDetailsAsync()
.
Para saber mais sobre como usar os recursos de compatibilidade
com versões anteriores, consulte o Guia de recursos de assinatura de maio de 2022.
Iniciar o fluxo de compra da opção de assinatura
O processo para iniciar um fluxo de compra de uma opção de assinatura é muito parecido com o utilizado para iniciar um fluxo de um SKU. Para iniciar um pedido de aprovação de compra na versão 6, siga estas etapas:
- Em vez de usar
SkuDetails
paraBillingFlowParams
, useProductDetailsParams
. - Use o objeto
SubscriptionOfferDetails
para acessar os detalhes das opções, como ID da opção, ID do plano básico, entre outros.
Para comprar um produto com a opção de assinatura selecionada pelo usuário, acesse o offerToken
dela e transmita-o para o objeto ProductDetailsParams
.
Depois de criar um objeto BillingFlowParams
, a inicialização do fluxo de faturamento
com BillingClient
continua a mesma.
O exemplo a seguir mostra como o app pode ficar antes e depois dessas mudanças.
Antes
Kotlin
// An activity reference from which the billing flow will be launched. val activity : Activity = ... // Retrieve a value for "skuDetails" by calling querySkuDetailsAsync(). val billingFlowParams = BillingFlowParams.newBuilder() .setSkuDetails(skuDetails) .build() val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)
Java
// An activity reference from which the billing flow will be launched. Activity activity = ...; // Retrieve a value for "skuDetails" by calling querySkuDetailsAsync(). BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder() .setSkuDetails(skuDetails) .build(); BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)
Depois
Kotlin
// An activity reference from which the billing flow will be launched. val activity : Activity = ...; val productDetailsParamsList = listOf( BillingFlowParams.ProductDetailsParams.newBuilder() // retrieve a value for "productDetails" by calling queryProductDetailsAsync() .setProductDetails(productDetails) // For One-time product, "setOfferToken" method shouldn't be called. // For subscriptions, to get the offer token corresponding to the selected // offer call productDetails.subscriptionOfferDetails?.get(selectedOfferIndex)?.offerToken .setOfferToken(selectedOfferToken) .build() ) val billingFlowParams = BillingFlowParams.newBuilder() .setProductDetailsParamsList(productDetailsParamsList) .build() // Launch the billing flow val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)
Java
// An activity reference from which the billing flow will be launched. Activity activity = ...; ImmutableList<ProductDetailsParams> productDetailsParamsList = ImmutableList.of( ProductDetailsParams.newBuilder() // retrieve a value for "productDetails" by calling queryProductDetailsAsync() .setProductDetails(productDetails) // For one-time products, "setOfferToken" method shouldn't be called. // For subscriptions, to get the offer token corresponding to the selected // offer call productDetails.getSubscriptionOfferDetails().get(selectedOfferIndex).getOfferToken() .setOfferToken(selectedOfferToken) .build() ); BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder() .setProductDetailsParamsList(productDetailsParamsList) .build(); // Launch the billing flow BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);
Processar as compras
Na Biblioteca Google Play Faturamento 6, o processamento de compras continua parecido com as versões anteriores.
Para extrair todas as compras ativas de um usuário e consultar novas compras, siga estas etapas:
- Em vez de transmitir um valor
BillingClient.SkuType
paraqueryPurchasesAsync()
, transmita um objetoQueryPurchasesParams
contendo um valorBillingClient.ProductType
.
O exemplo a seguir mostra como o app pode ficar antes e depois dessas mudanças.
Antes
Kotlin
billingClient.queryPurchasesAsync(BillingClient.SkuType.SUBS) { billingResult, purchaseList -> { // Process the result } }
Java
billingClient.queryPurchasesAsync( BillingClient.SkuType.SUBS, new PurchasesResponseListener() { public void onQueryPurchasesResponse( BillingResult billingResult, ListP<urchase >purchases) { // process the result } } );
Depois
Kotlin
billingClient.queryPurchasesAsync( QueryPurchasesParams.newBuilder() .setProductType(BillingClient.ProductType.SUBS) .build() ) { billingResult, purchaseList -> // Process the result }
Java
billingClient.queryPurchasesAsync( QueryPurchasesParams.newBuilder().setProductType(ProductType.SUBS).build(), new PurchasesResponseListener() { public void onQueryPurchasesResponse( BillingResult billingResult, List<Purchase> purchases) { // Process the result } } );
As etapas para gerenciar compras fora do app e transações pendentes não mudaram.
Gerenciar o status de compra da assinatura com a nova API no back-end
Migre o componente de gerenciamento de status de compra de assinaturas do back-end para poder processar compras dos novos produtos criados nas etapas anteriores. O componente atual de gerenciamento de status de compra de assinaturas vai funcionar normalmente para os produtos por assinatura convertidos que você definiu antes do lançamento de maio de 2022. Ele é suficiente para gerenciar compras de opções de assinatura compatíveis com versões anteriores, mas não há suporte para as novas funcionalidades.
É necessário implementar a nova API Subscription Purchases no módulo de gerenciamento de status de compra das assinaturas, que verifica o status da compra e gerencia os direitos de assinatura do Play Faturamento no back-end. A versão antiga da API não retorna todos os detalhes necessários para gerenciar compras na nova plataforma. Para conferir mais informações sobre o que mudou em relação às versões anteriores, consulte o guia de novos recursos de assinatura de maio de 2022.
Normalmente, você chamaria a API Subscription Purchases sempre que recebesse uma
notificação do desenvolvedor em tempo real SubscriptionNotification
para extrair as
informações mais recentes sobre o status da assinatura. Você precisa substituir as
chamadas para purchases.subscriptions.get
pela nova versão da
API Subscription Purchases, purchases.subscriptionsv2.get
.
Há um novo recurso, chamado
SubscriptionPurchaseV2
,
que fornece informações suficientes
para gerenciar o direito de compra de assinaturas no novo modelo.
Esse novo endpoint retorna o status de todos os produtos por assinatura e todas as compras, independente da versão do app que os vendeu e de quando o produto foi definido (antes ou depois do lançamento de maio de 2022). Por isso, após a migração, você só vai precisar dessa versão do módulo de gerenciamento de status da compra de assinaturas.
Mudar as compras de assinaturas de um usuário
Na Biblioteca Play Faturamento 5 e versões anteriores, o
ProrationMode
era usado para aplicar mudanças às compras de assinaturas de um usuário, como upgrades
ou downgrades. Ele foi descontinuado e substituído por
ReplacementMode
na versão 6.
Processar mudanças no preço de assinaturas
A API launchPriceConfirmationFlow
descontinuada foi removida na
Biblioteca Play Faturamento 6. Para conferir alternativas, consulte o guia de mudanças de
preço.
Processar erros da Biblioteca Play Faturamento
Na Biblioteca Play Faturamento 6, um novo código NETWORK_ERROR
foi adicionado para indicar
problemas com a conexão de rede entre o dispositivo do usuário e o sistema do
Google Play. Também houve mudanças nos códigos SERVICE_TIMEOUT
e
SERVICE_UNAVAILABLE
. Para saber mais, consulte Processar códigos de resposta de
BillingResult.
Processar transações pendentes
A partir da versão 6.0.0, a Biblioteca Play Faturamento não cria um código do pedido
para compras pendentes. Para essas compras, o código do pedido só é preenchido depois
que a compra é movida para o
estado
PURCHASED
. Confira se a integração espera um código de pedido apenas após a
conclusão de uma transação. Ainda é possível usar o token de compra para seus
registros. Para saber mais sobre como processar compras pendentes, consulte o guia de integração da Biblioteca
Play Faturamento e o
guia de gerenciamento do ciclo de vida de compras.