Cómo migrar a la Biblioteca de Facturación Google Play 9 desde las versiones 7 u 8

En este documento, se describe cómo migrar de la Biblioteca de Facturación Google Play (PBL) 7 o 8 a la PBL 9 y cómo realizar la integración con las nuevas funciones.

Para obtener una lista completa de los cambios de la versión 9.0.0, consulta las notas de la versión.

Descripción general

La PBL 9 contiene mejoras en las APIs existentes, además de la eliminación de las APIs que habían dejado de estar disponibles. Esta versión de la biblioteca también introduce un contexto de error más enriquecido a través de nuevos códigos de subrespuesta.

Retrocompatibilidad para la actualización de PBL

Para migrar a la PBL 9, debes actualizar o quitar algunas de las referencias de la API existentes de tu app, como se describe en las notas de la versión y más adelante en esta guía de migración.

Actualiza de la PBL 7 o 8 a la PBL 9

Para actualizar de la PBL 7 o 8 a la PBL 9, sigue estos pasos:

  1. Actualiza la versión de dependencia de la Biblioteca de Facturación Play en el archivo build.gradle de tu app.

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

    Si usas Kotlin, el módulo KTX de la Biblioteca de Facturación Google Play es compatible con las extensiones y las corrutinas de Kotlin, y permite la escritura de código idiomático de Kotlin cuando usas la Biblioteca de Facturación Google Play. Para incluir estas extensiones en tu proyecto, agrega la siguiente dependencia al archivo build.gradle de la app como se muestra a continuación:

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

  2. (Solo se aplica a la actualización de la PBL 7 a la PBL 9). Actualiza la implementación del queryProductDetailsAsync método.

    Hay un cambio en la firma del ProductDetailsResponseListener.onProductDetailsResponse método, que requiere cambios en tu app para la queryProductDetailsAsync implementación. Para obtener más información, consulta Cómo mostrar los productos disponibles para la compra.

  3. Controla las APIs quitadas.

    En la siguiente tabla, se enumeran las APIs que se quitaron y las APIs alternativas correspondientes que debes usar en tu app.

    Actualiza desde

    La PBL 9 ya no admite las APIs que se enumeran en la siguiente tabla. Si tu implementación usa alguna de estas APIs quitadas, consulta la tabla para ver las APIs alternativas correspondientes.

    Se quitó la API que había dejado de estar disponible API alternativa que se debe usar
    APIs de queryPurchaseHistoryAsync Consulta Historial de compras. Si usabas queryPurchaseHistoryAsync para determinar la elegibilidad para las pruebas gratuitas, ahora debes usar ProductDetails.getSubscriptionOfferDetails() para determinar para qué ofertas es apto un usuario.
    BillingClient.SkuType BillingClient.ProductType. Las constantes de tipo de producto INAPP y SUBS siguen siendo funcionalmente similares a las constantes de tipo de SKU obsoletas.
    SkuDetails ProductDetails. Este es el nuevo modelo de datos que admite los productos únicos.
    SkuDetailsParams Usa QueryProductDetailsParams con queryProductDetailsAsync.
    SkuDetailsResponseListener Usa ProductDetailsResponseListener con queryProductDetailsAsync.
    QueryPurchaseHistoryParams
    • Usa queryPurchasesAsync para compras activas o pendientes.
    • Haz un seguimiento de las compras consumidas en tus servidores de backend.
    • Usa la API de Voided Purchases del servidor para las compras canceladas o anuladas.
    getSkuDetailsList y setSkuDetailsList Usa BillingFlowParams.Builder.setProductDetailsParamsList
    querySkuDetailsAsync queryProductDetailsAsync
    enablePendingPurchases() (API sin parámetros) enablePendingPurchases(PendingPurchasesParams params)
    Ten en cuenta que la función enablePendingPurchases() obsoleta es funcionalmente equivalente a enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()).
    queryPurchasesAsync(String skuType, PurchasesResponseListener listener) queryPurchasesAsync

    Actualiza desde

    En la siguiente tabla, se enumeran las APIs que se quitaron en la PBL 9 y las APIs alternativas correspondientes que debes usar en tu app.

    Se quitó la API que había dejado de estar disponible API alternativa que se debe usar
    BillingClient.SkuType BillingClient.ProductType. Las constantes de tipo de producto INAPP y SUBS siguen siendo funcionalmente similares a las constantes de tipo de SKU obsoletas.
    SkuDetails ProductDetails. Este es el nuevo modelo de datos que admite los productos únicos.
    SkuDetailsParams Usa QueryProductDetailsParams con queryProductDetailsAsync.
    SkuDetailsResponseListener Usa ProductDetailsResponseListener con queryProductDetailsAsync.
    QueryPurchaseHistoryParams
    • Usa queryProductDetailsAsync para compras activas o pendientes.
    • Haz un seguimiento de las compras consumidas en tus servidores de backend.
    • Usa la API de Voided Purchases del servidor para las compras canceladas o anuladas.
    getSkuDetailsList y setSkuDetailsList Usa BillingFlowParams.Builder.setProductDetailsParamsList

  4. (Recomendado) Habilita la reconexión automática del servicio.

    La Biblioteca de Facturación Play puede intentar restablecer automáticamente la conexión de servicio si se realiza una llamada a la API mientras el servicio está desconectado. Para obtener más información, consulta Cómo habilitar la reconexión automática del servicio.

  5. Controla los nuevos códigos de subrespuesta.

    El BillingResult que se muestra desde launchBillingFlow() ahora incluirá un campo de código de subrespuesta. Este campo solo se propagará en algunos casos para proporcionar un motivo más específico del error. El campo de subrespuesta puede tener los siguientes valores:

    • PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS - Se muestra cuando los fondos del usuario son inferiores al precio del artículo que intenta comprar.
    • USER_INELIGIBLE - Se muestra cuando el usuario no cumple con los requisitos de elegibilidad configurados para una oferta de suscripción.
    • NO_APPLICABLE_SUB_RESPONSE_CODE: Es el valor predeterminado que se muestra cuando no se aplica ningún otro código de subrespuesta.

    Paso de migración: Actualiza tu PurchasesUpdatedListener o el control de resultados equivalente para reconocer y responder a estos códigos de subrespuesta específicos para proporcionar una mejor experiencia del usuario. Por ejemplo, solicitar que se corrijan los métodos de pago o mostrar un mensaje de error específico.

  6. Conocimiento de la reclasificación de códigos de error.

    En los casos en los que el sistema bloquea la app de Play Store (por ejemplo, en el modo para niños personalizado por el OEM), el código de respuesta de la PBL cambió de ERROR a BILLING_UNAVAILABLE.

    Paso de migración: Asegúrate de que la lógica de manejo de errores se adapte a este cambio y no dependa de recibir un error genérico en estas situaciones específicas.

  7. Controla la DeveloperProvidedBillingDetails.getLinkUri() nulabilidad.

    Si usas DeveloperProvidedBillingDetails como parte de una integración de pagos externos, getLinkUri() ahora es @Nullable.

    Paso de migración: Para controlar este cambio de forma segura, asegúrate de que tu código de integración controle los valores null y de cadena vacía ("") del DeveloperProvidedBillingDetails.getLinkUri() método antes de analizar o iniciar intents del navegador. Por ejemplo:

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