Migrar das versões 4 ou 5 para a versão 6 da Biblioteca Google Play Faturamento

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:

• Inicialize o cliente de faturamento
• Estabeleça uma conexão com o Google Play

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 por QueryProductDetailsParams.
• Troque a chamada BillingClient.querySkuDetailsAsync() por BillingClient.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

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
}

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

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
}

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 para BillingFlowParams, use ProductDetailsParams.
• 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

// 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)

// 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

// 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)

// 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 para queryPurchasesAsync(), transmita um objeto QueryPurchasesParams contendo um valor BillingClient.ProductType.

O exemplo a seguir mostra como o app pode ficar antes e depois dessas mudanças.

Antes

billingClient.queryPurchasesAsync(BillingClient.SkuType.SUBS) {
    billingResult,
    purchaseList -> {
        // Process the result
    }
}

billingClient.queryPurchasesAsync(
    BillingClient.SkuType.SUBS,
    new PurchasesResponseListener() {
        public void onQueryPurchasesResponse(
                BillingResult billingResult,
                ListP<urchase >purchases) {
            // process the result
        }
    }
);

Depois

billingClient.queryPurchasesAsync(
    QueryPurchasesParams.newBuilder()
        .setProductType(BillingClient.ProductType.SUBS)
        .build()
) { billingResult, purchaseList ->
    // Process the result
}

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.