Migrar das versões 7 ou 8 para a versão 9 da Biblioteca Google Play Faturamento

Este documento descreve como migrar da Biblioteca Google Play Faturamento (PBL, na sigla em inglês) 7 ou 8 para a PBL 9 e como fazer a integração com os novos recursos.

Para conferir uma lista completa das mudanças na versão 9.0.0, consulte as notas da versão.

Visão geral

A PBL 9 contém melhorias nas APIs atuais, além da remoção de APIs descontinuadas. Essa versão da biblioteca também apresenta um contexto de erro mais detalhado com novos códigos de subresposta.

Compatibilidade com versões anteriores para upgrade da PBL

Para migrar para a PBL 9, é necessário atualizar ou remover algumas das referências de API existentes do app, conforme descrito nas notas da versão e mais adiante neste guia de migração.

Fazer upgrade da PBL 7 ou 8 para a PBL 9

Para fazer upgrade da PBL 7 ou 8 para a PBL 9, siga estas etapas:

  1. Atualize a versão da dependência da Biblioteca Play Faturamento no arquivo build.gradle do app.

    dependencies {
  def billing_version = "9.1.0"
  implementation "com.android.billingclient:billing:$billing_version"
}

    Se você usa o Kotlin, o módulo KTX da Biblioteca Google Play Faturamento oferece suporte a extensões e corrotinas de Kotlin que permitem escrever Kotlin idiomático ao usar a Biblioteca Google Play Faturamento. Para incluir essas extensões no projeto, adicione a seguinte dependência ao arquivo build.gradle do app, como mostrado:

    dependencies {
  val billing_version = "9.1.0"
  implementation("com.android.billingclient:billing-ktx:$billing_version")
}

  2. (Aplicável apenas para upgrade da PBL 7 para a PBL 9). Atualize a implementação do método queryProductDetailsAsync.

    Há uma mudança na assinatura do método ProductDetailsResponseListener.onProductDetailsResponse, que exige mudanças no app para a implementação de queryProductDetailsAsync. Para mais informações, consulte Mostrar disponibilidade do produto para compra.

  3. Gerencie as APIs removidas.

    A tabela a seguir lista as APIs que foram removidas e as APIs alternativas correspondentes que você precisa usar no seu app.

    Fazer upgrade de

    A PBL 9 não é mais compatível com as APIs listadas na tabela a seguir. Se a implementação usar alguma dessas APIs removidas, consulte a tabela para ver as APIs alternativas correspondentes.

    A API descontinuada foi removida API alternativa a ser usada
    APIs queryPurchaseHistoryAsync Consulte Consultar histórico de compras. Se você estava usando queryPurchaseHistoryAsync para determinar a qualificação para testes sem custo financeiro, agora use ProductDetails.getSubscriptionOfferDetails() para determinar quais ofertas estão disponíveis para um usuário.
    BillingClient.SkuType BillingClient.ProductType. As constantes de tipo de produto INAPP e SUBS permanecem funcionalmente semelhantes às constantes de tipo de SKU descontinuadas.
    SkuDetails ProductDetails. Esse é o novo modelo de dados que oferece suporte aos produtos únicos.
    SkuDetailsParams Use QueryProductDetailsParams com queryProductDetailsAsync.
    SkuDetailsResponseListener Use ProductDetailsResponseListener com queryProductDetailsAsync.
    QueryPurchaseHistoryParams
    • Use queryPurchasesAsync para compras ativas ou pendentes.
    • Rastreie as compras consumidas nos servidores de back-end.
    • Use a API Voided Purchases do lado do servidor para compras canceladas ou anuladas.
    getSkuDetailsList e setSkuDetailsList Use BillingFlowParams.Builder.setProductDetailsParamsList.
    querySkuDetailsAsync queryProductDetailsAsync
    enablePendingPurchases() (API sem parâmetros) enablePendingPurchases(PendingPurchasesParams params)
    O método descontinuado enablePendingPurchases() é funcionalmente equivalente a enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()).
    queryPurchasesAsync(String skuType, PurchasesResponseListener listener) queryPurchasesAsync

    Fazer upgrade de

    A tabela a seguir lista as APIs que foram removidas na PBL 9 e as APIs alternativas correspondentes que você precisa usar no app.

    A API descontinuada foi removida API alternativa a ser usada
    BillingClient.SkuType BillingClient.ProductType. As constantes de tipo de produto INAPP e SUBS permanecem funcionalmente semelhantes às constantes de tipo de SKU descontinuadas.
    SkuDetails ProductDetails. Esse é o novo modelo de dados que oferece suporte aos produtos únicos.
    SkuDetailsParams Use QueryProductDetailsParams com queryProductDetailsAsync.
    SkuDetailsResponseListener Use ProductDetailsResponseListener com queryProductDetailsAsync.
    QueryPurchaseHistoryParams
    getSkuDetailsList e setSkuDetailsList Use BillingFlowParams.Builder.setProductDetailsParamsList.

  4. (Recomendado) Ative a reconexão automática do serviço.

    A Biblioteca Play Faturamento pode tentar restabelecer automaticamente a conexão de serviço se uma chamada de API for feita enquanto o serviço estiver desconectado. Para mais informações, consulte Ativar a reconexão automática do serviço.

  5. Processar novos códigos de subresposta.

    O BillingResult retornado de launchBillingFlow() agora inclui um campo de código de subresposta. Esse campo só será preenchido em alguns casos para fornecer um motivo mais específico para a falha. O campo de subresposta pode ter os seguintes valores:

    • PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS: retornado quando os fundos do usuário são menores que o preço do item que ele está tentando comprar.
    • USER_INELIGIBLE: retornado quando o usuário não atende aos requisitos de qualificação configurados para uma oferta de assinatura.
    • NO_APPLICABLE_SUB_RESPONSE_CODE: o valor padrão, retornado quando nenhum outro código de subresposta é aplicável.

    Etapa de migração: atualize o PurchasesUpdatedListener ou o tratamento de resultados equivalente para reconhecer e responder a esses códigos de subresposta específicos, proporcionando uma melhor experiência do usuário. Por exemplo, solicitar a correção das formas de pagamento ou mostrar uma mensagem de erro específica.

  6. Consciência da reclassificação de códigos de erro.

    Para instâncias em que o app Google Play Store é bloqueado pelo sistema (por exemplo, no modo infantil personalizado pelo OEM), o código de resposta da PBL mudou de ERROR para BILLING_UNAVAILABLE.

    Etapa de migração: verifique se a lógica de tratamento de erros acomoda essa mudança e não depende do recebimento de um erro genérico nesses cenários específicos.

  7. Processar a nulidade de DeveloperProvidedBillingDetails.getLinkUri().

    Se você usa DeveloperProvidedBillingDetails como parte de uma integração de pagamentos externos, getLinkUri() agora é @Nullable.

    Etapa de migração: para lidar com essa mudança com segurança, verifique se o código de integração processa os valores null e de string vazia ("") do método DeveloperProvidedBillingDetails.getLinkUri() antes de analisar ou iniciar intents do navegador. Exemplo:

    Kotlin

    Java

    String linkUri = details.getLinkUri();
if (!android.text.TextUtils.isEmpty(linkUri)) {
  Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(linkUri));
  context.startActivity(intent);
}

  8. Mudanças opcionais.