Este documento 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.
As 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 anteriores.
As versões do app que usam métodos descontinuados (por exemplo,
querySkuDetailsAsync()) não poderão vender planos básicos ou ofertas
que não sejam compatíveis com versões anteriores. Leia sobre as ofertas compatíveis com versões anteriores
no artigo 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 ofertas de assinatura têm modelos de preços e opções 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 por assinatura convertidos após o lançamento de maio de 2022 para que
as versões do app que usam métodos descontinuados (como querySkuDetailsAsync())
possam continuar vendendo esses produtos sem afetar esses builds.
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 planos básicos e ofertas compatíveis com versões anteriores. Além disso, só pode haver uma combinação de plano básico e oferta compatível com versões anteriores. Portanto, se você adicionar novos planos ou ofertas às assinaturas convertidas, os novos planos básicos ou ofertas adicionais 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, se estiver chamando 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.subscriptionspara gerenciar produtos por assinatura.Monetization.basePlans, para gerenciar planos básicos de assinaturas.Monetization.offerspara gerenciar ofertas 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 ofertas
que não sejam compatíveis com versões anteriores. Leia sobre as ofertas compatíveis com versões anteriores
no artigo de ajuda do Play Console.
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 Faturamento do Google Play 5. 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
SkuDetailsParamsporQueryProductDetailsParams. - 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, ofertas, entre outros, o novo sistema
converte cada SKU de assinatura em uma única oferta 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 casos raros, alguns dispositivos não oferecem 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 o recurso PRODUCT_DETAILS antes de
chamar queryProductDetailsAsync. Se a resposta for OK, o dispositivo
oferece suporte ao recurso e você pode 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
SkuDetailsparaBillingFlowParams, useProductDetailsParams. - Use o objeto
SubscriptionOfferDetailspara obter os detalhes da oferta, como ID da oferta, 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.SkuTypeparaqueryPurchasesAsync(), transmita um objetoQueryPurchasesParamscontendo 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,
List<Purchase> 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 ofertas 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.
Ao migrar o módulo de gerenciamento de status de compra:
- Chame a API Subscription Purchases sempre que receber uma
notificação do desenvolvedor em tempo real
SubscriptionNotificationpara extrair as informações mais recentes sobre o status da assinatura. - Substitua as chamadas para
purchases.subscriptions.getpela nova versão da API Subscription Purchases,purchases.subscriptionsv2.get. - Use o novo recurso
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 do 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.