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) 7 ou 8 para a PBL 9 e como integrar 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

O PBL 9 contém melhorias nas APIs atuais e a remoção de APIs descontinuadas anteriormente. Esta versão da biblioteca também apresenta um contexto de erro mais completo 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 atuais 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 do PBL 7 ou 8 para o 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.0.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.0.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 do queryProductDetailsAsync. Para mais informações, consulte Mostrar produtos disponíveis para compra.

  3. Processar as APIs removidas.

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

    Fazer upgrade de

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

    API descontinuada 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 a quais ofertas um usuário se qualifica.
    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)
    A função enablePendingPurchases() descontinuada é funcionalmente equivalente a enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()).
    queryPurchasesAsync(String skuType, PurchasesResponseListener listener) queryPurchasesAsync

    Fazer upgrade de

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

    API descontinuada 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 de serviços.

  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 seu PurchasesUpdatedListener ou o processamento de resultados equivalente para reconhecer e responder a esses códigos de sub-resposta específicos e oferecer uma experiência melhor ao usuário. Por exemplo, pedindo para corrigir as formas de pagamento ou mostrando uma mensagem de erro específica.

  6. Reclassificação de códigos de erro.

    Nos casos 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. Lide com a capacidade de aceitar valores nulos do DeveloperProvidedBillingDetails.getLinkUri().

    Se você usa DeveloperProvidedBillingDetails como parte de uma integração de pagamentos externa, 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

    val linkUri = details.getLinkUri()
if (!linkUri.isNullOrEmpty()) {
  val intent = Intent(Intent.ACTION_VIEW, Uri.parse(linkUri))
  context.startActivity(intent)
}

    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.