Guia de migração da versão 4 para a versão 5 da Biblioteca Google Play Faturamento

Este artigo descreve como migrar da versão 4 para a versão 5 da Biblioteca Google Play Faturamento e como usar os novos recursos de assinatura.

Visão geral

A Biblioteca Google Play Faturamento 5 introduz planos básicos e opções de assinatura. Esses recursos aumentam as possibilidades de venda de assinaturas, reduzindo os custos operacionais ao remover a necessidade de criar e gerenciar um número cada vez maior de SKUs. Para mais informações, consulte Mudanças recentes em assinaturas no Play Console.

Todos os produtos por assinatura já existentes foram convertidos automaticamente nesse novo paradigma, como parte do lançamento da biblioteca Play Faturamento 5 em maio de 2022 e da nova plataforma de assinaturas. Para saber mais sobre a conversão, consulte a seção Como trabalhar com assinaturas mais antigas no artigo de ajuda do Play Console.

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. Você pode criar opções no ciclo de vida da assinatura usando vários planos pré-pagos e de renovação automática. Para saber mais, consulte o guia de integração.

No entanto, se você não pretende adotar esses novos recursos imediatamente, ainda pode migrar seu app para a Biblioteca Play Faturamento 5 e planejar a migração dos componentes de back-end mais tarde, desde que o catálogo de produtos mantenha uma configuração compatível com versões anteriores.

Etapas da migração

Criar seu catálogo de produtos de back-end

Recomendamos criar novos produtos de acordo com a estrutura da entidade na nova plataforma de assinaturas para integração da Biblioteca Play Faturamento 5 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.

Recomendamos que você não modifique os produtos de assinatura convertidos após o lançamento de maio de 2022. Eles devem ficar do jeito que serão vendidos com as versões do app usando métodos descontinuados (por exemplo, querySkuDetailsAsync()), sem introduzir mudanças que podem 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íveis com versões anteriores. Se você adicionar novos planos ou opções às assinaturas convertidas, os novos planos básicos ou opções não poderão ser vendidos nessas versões anteriores do app.

  • No back-end, se você editar suas assinaturas convertidas na IU 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 da assinatura (purchases.subscriptionsv2.get) para gerenciar compras dessas assinaturas, porque 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 Como 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:

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()) só podem vender planos básicos ou opções que são 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 = "5.0.0"

    implementation "com.android.billingclient:billing:$billingVersion"
}

O projeto vai ser criado imediatamente, mesmo que você não tenha modificado nenhuma chamada para métodos, porque a Biblioteca Play Faturamento 5 oferece compatibilidade com versões anteriores. No entanto, é importante notar que o conceito de SKU foi descontinuado.

Como 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:

Como mostrar os produtos disponíveis para compra

Para acessar todas as opções de assinatura que os usuários podem comprar, faça o seguinte:

  • 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

Kotlin

val skuList = ArrayList<String>()

skuList.add("up_basic_sub")

val params = SkuDetailsParams.newBuilder()

params.setSkusList(skuList).setType(BillingClient.SkuType.SUBS)

billingClient.querySkuDetailsAsync(params.build()) {
    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);

billingClient.querySkuDetailsAsync(params.build(),
    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)

billingClient.queryProductDetailsAsync(params.build()) {
    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 da Biblioteca Play Faturamento 5, consulte o Guia de recursos de assinatura de maio de 2022.

Como 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 uma solicitação de compra na versão 5, faça o seguinte:

  • 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 poderá 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 = ...;
// Retrieve a value for "productDetails" by calling queryProductDetailsAsync()
// Get the offerToken of the selected offer
val offerToken = productDetails.subscriptionOfferDetails?.get(selectedOfferIndex)?.offerToken

val productDetailsParamsList =
    listOf(
        BillingFlowParams.ProductDetailsParams.newBuilder()
            .setProductDetails(productDetails)
            .setOfferToken(offerToken)
            .build()
    )
val billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(productDetailsParamsList)
        .build()

// Launch the billing flow
val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Java

// Retrieve a value for "productDetails" by calling queryProductDetailsAsync()
// Get the offerToken of the selected offer
String offerToken = productDetails
                     .getSubscriptionOfferDetails()
                     .get(selectedOfferIndex)
                     .getOfferToken();
// Set the parameters for the offer that will be presented
// in the billing flow creating separate productDetailsParamsList variable
ImmutableList<ProductDetailsParams> productDetailsParamsList =
        ImmutableList.of(
                 ProductDetailsParams.newBuilder()
                     .setProductDetails(productDetails)
                     .setOfferToken(offerToken)
                     .build()
        );

BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(productDetailsParamsList)
            .build();

// Launch the billing flow
BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

Como processar compras

Na Biblioteca Google Play Faturamento 5, o processamento de compras continua semelhante às versões anteriores.

Para extrair todas as compras ativas de um usuário e consultar novas compras, faça o seguinte:

  • 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

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