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 e a remoção de APIs descontinuadas anteriormente. Essa versão da biblioteca também apresenta um contexto de erro mais rico com novos códigos de sub-resposta.

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 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 queryProductDetailsAsync método.

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

  3. Gerenciar as APIs removidas.

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

    Upgrade da

    A PBL 9 não oferece mais suporte às APIs listadas na tabela a seguir. Se a implementação usa alguma dessas APIs removidas, consulte a tabela para conferir as APIs alternativas correspondentes.

    API descontinuada anteriormente 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 para quais ofertas um usuário está qualificado.
    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.
    • Acompanhe 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)
    Observe que o enablePendingPurchases() descontinuado é funcionalmente equivalente a enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()).
    queryPurchasesAsync(String skuType, PurchasesResponseListener listener) queryPurchasesAsync

    Upgrade da

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

    API descontinuada anteriormente 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
    • Use queryProductDetailsAsync para compras ativas ou pendentes.
    • Acompanhe 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

  4. Recomendado: ativar 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. Gerenciar novos códigos de sub-resposta.

    O BillingResult retornado de launchBillingFlow() agora vai incluir um campo de código de sub-resposta. Esse campo só será preenchido em alguns casos para fornecer um motivo mais específico para a falha. O campo de sub-resposta 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 sub-resposta é aplicável.

    Etapa de migração: atualize o PurchasesUpdatedListener ou o processamento de resultados equivalente para reconhecer e responder a esses códigos de sub-resposta específicos para oferecer uma melhor experiência do usuário. Por exemplo, solicitando a correção das formas de pagamento ou mostrando uma mensagem de erro específica.

  6. Conscientização da reclassificação do código de erro.

    Para instâncias em que o app Google Play Store está 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 esta mudança e não depende do recebimento de um erro genérico nestes cenários específicos.

  7. Gerenciar 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 processar essa mudança com segurança, verifique se o código de integração processa valores null e de string vazia ("") do DeveloperProvidedBillingDetails.getLinkUri() antes de analisar ou iniciar intents do navegador. Por 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.