Cómo migrar a la biblioteca de Google Play Billing 6 desde las versiones 4 o 5

En este tema, se describe cómo migrar desde la biblioteca de Google Play Billing 4 o 5 a la biblioteca de Google Play Billing 6 y cómo usar las nuevas funciones de suscripción.

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

Descripción general

La biblioteca de Google Play Billing 6 se basa en las nuevas funciones de suscripción que se introdujeron en la versión 5 y agrega algunas mejoras más. Estas funciones te permiten vender suscripciones de más formas, lo que reduce los costos operativos, ya que elimina la necesidad de crear y administrar una cantidad cada vez mayor de SKU.

Para obtener más información sobre las nuevas funciones que se presentan con la biblioteca de Play Billing 5, consulta Cambios recientes en las suscripciones de Play Console.

Actualización retrocompatible de la biblioteca de Play Billing

Todos los productos de suscripción existentes se convirtieron automáticamente a este nuevo paradigma como parte de la actualización de mayo de 2022 de la biblioteca de Play Billing 5 y la nueva plataforma de suscripciones. Es decir, no tienes que realizar ningún cambio en la configuración del producto de suscripción para tener un catálogo que sea compatible con las versiones nuevas de la biblioteca de Play Billing. Para obtener más información sobre cómo los SKU de suscripción se convirtieron en suscripciones retrocompatibles, consulta la sección Cómo trabajar con suscripciones anteriores en el artículo de ayuda de Play Console.

Las versiones anteriores de tu app siguen funcionando

Si tienes un catálogo de suscripción retrocompatible, todas las versiones existentes de tu app deberían funcionar, según lo previsto para esos productos. Las compras únicas de productos también deberían seguir funcionando sin problemas en versiones anteriores.

Las versiones de tu app que usen métodos obsoletos (por ejemplo, querySkuDetailsAsync()) no podrán vender ofertas ni planes básicos que no sean retrocompatibles. Puedes leer sobre las ofertas retrocompatibles en el artículo relevante del Centro de ayuda de Play Console.

Actualiza a la biblioteca de Play Billing 5 o 6

La biblioteca de Play Billing 5 y 6 incluyen los métodos obsoletos querySkuDetailsAsync y BillingFlowParams.Builder.setSkuDetails que toman SkuDetails como parámetro de flujo de facturación. Es decir, puedes cambiar gradualmente a la biblioteca de Play Billing 6 planificando diferentes etapas de migración.

Como primer paso para la migración, puedes actualizar la versión de la biblioteca, dejar tu catálogo y backend como están, y probar tu app mientras esta sigue usando los métodos obsoletos. Aunque no uses queryPurchases, launchPriceChangeFlow o setVrPurchaseFlow, debería funcionar según lo previsto. Después, puedes iterar para adoptar por completo las nuevas funciones de suscripción que se lanzaron en mayo de 2022.

Si ya implementaste estas funciones con una migración a la biblioteca de Google Play Billing 5, puedes ir directamente a las secciones Actualiza la biblioteca de Google Play Billing y Cambia las compras de suscripción de un usuario. Si comienzas desde una versión anterior o aún no adoptaste por completo las funciones nuevas, puedes leer los pasos completos para la migración que se mencionan a continuación para obtener información para adoptar estas funciones.

Pasos completos para la migración

Crea suscripciones nuevas en tu catálogo de productos de backend

Ahora, con Play Developer Console o la API de Play Developer, puedes configurar una sola suscripción con varios planes básicos, cada uno con varias ofertas. Las ofertas de suscripción tienen modelos de precios y opciones de elegibilidad flexibles. Puedes crear ofertas durante todo el ciclo de vida de la suscripción con una variedad de planes de renovación automática o prepagados.

Te recomendamos que crees nuevos productos siguiendo la estructura de la entidad en la nueva plataforma de suscripciones para la integración de la biblioteca de Play Billing 6 antes de migrar tu app. Puedes consolidar los productos duplicados de tu catálogo anterior que representen los mismos beneficios de derechos en una sola suscripción y usar la configuración del plan básico y de las ofertas para representar todas las opciones que quieras brindar. Para obtener más información sobre esta recomendación, consulta la sección Cómo trabajar con suscripciones anteriores del artículo de ayuda de Play Console.

Te recomendamos que no modifiques los productos de suscripción convertidos después del lanzamiento de mayo de 2022; debes dejarlos así, ya que se venderán con las versiones de tu app a través de métodos obsoletos (por ejemplo, querySkuDetailsAsync()) sin introducir cambios que podrían afectar estas compilaciones anteriores.

El proceso de conversión hizo que los productos de suscripción que estaban en el catálogo antes de mayo de 2022 sean de solo lectura para evitar cambios accidentales que podrían provocar problemas con la integración existente. Se pueden realizar cambios en esas suscripciones, pero habría consecuencias que podrían afectar las integraciones de frontend y backend:

• En el frontend, las versiones de la app que usan querySkuDetailsAsync() para obtener detalles del producto de suscripción solo pueden vender ofertas y planes básicos retrocompatibles, y solo puede haber una combinación de plan básico retrocompatible y oferta, de modo que si agregas ofertas o planes nuevos a las suscripciones convertidas, las ofertas o los planes básicos adicionales nuevos no se podrán vender en esas versiones anteriores de tu app.

• En el backend, si editas tus suscripciones convertidas en la IU de Play Console, no podrás administrarlas con el extremo inappproducts si lo llamabas para este fin. También debes migrar al nuevo extremo de estado de compra de la suscripción (purchases.subscriptionsv2.get) para administrar las compras de estas suscripciones, ya que el extremo de estado de compra anterior (purchases.subscriptions.get) solo muestra los datos necesarios para procesar planes básicos retrocompatibles y ofrece compras. Para obtener más información, consulta la sección Cómo administrar el estado de la compra de suscripciones.

Administra tu catálogo de suscripciones de backend con la nueva API

Si administras el catálogo de productos de suscripción automáticamente con la API de Google Play Developer, debes usar los nuevos extremos de definición del producto de suscripción para crear y administrar suscripciones, planes básicos y ofertas. Lee la guía de funciones de suscripción de mayo de 2022 a fin de obtener más información sobre los cambios en la API del catálogo de productos para esta versión.

A fin de migrar un módulo de administración automática del catálogo de productos para suscripciones a la Facturación Google Play, reemplaza la API de inappproducts por la nueva API de Subscription Purchases a fin de administrar y publicar el catálogo de suscripción. Hay tres extremos nuevos:

• Monetization.subscriptions para administrar los productos de suscripción.
• Monetization.basePlans para administrar planes básicos de las suscripciones.
• Monetization.offers para administrar las ofertas de los planes básicos.

Estos nuevos extremos tienen todas las funciones necesarias para aprovechar las nuevas funciones en tu catálogo: el plan básico y las etiquetas de oferta, la segmentación regional, los planes prepagados y mucho más.

Debes usar la API de inappproducts de todas formas a fin de administrar tu catálogo de productos integrados en la app para productos de compra única.

Las versiones de tu app que usen métodos obsoletos (por ejemplo, querySkuDetailsAsync()) no podrán vender ofertas ni planes básicos que no sean retrocompatibles. Puedes leer acerca de las ofertas retrocompatibles aquí.

Actualiza la biblioteca de Google Play Billing

Una vez que hayas creado tu nuevo catálogo de productos de suscripción, podrás migrar tu app a la Biblioteca de Facturación 5 de Google. Reemplaza la dependencia existente de la biblioteca de Play Billing por la versión actualizada en el archivo build.gradle de la app.

dependencies {
    def billingVersion = "6.0.0"

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

Tu proyecto debería compilarse de inmediato, incluso si no modificaste ninguna llamada a los métodos, ya que la biblioteca de Play Billing 6 es retrocompatible. El concepto de una SKU se considera obsoleto, pero aún está presente para que la portabilidad de apps sea un proceso más simple e incremental.

Inicializa el cliente de facturación y establece una conexión con Google Play

Los primeros pasos para iniciar compras desde una app para Android son los mismos:

• Inicializar el cliente de facturación
• Establecer una conexión con Google Play

Muestra productos disponibles para comprar

Para obtener todas las ofertas que puede comprar un usuario, haz lo siguiente:

• Reemplaza SkuDetailsParams con QueryProductDetailsParams.
• Cambia la llamada BillingClient.querySkuDetailsAsync() para usar BillingClient.queryProductDetailsAsync().

Ten en cuenta que los resultados de la búsqueda ahora son ProductDetails en lugar de SkuDetails. Cada elemento ProductDetails contiene la información sobre el producto (ID, título, tipo, etc.). En el caso de los productos de suscripción, ProductDetails incluye un List<ProductDetails.SubscriptionOfferDetails>, que es la lista de los detalles de la oferta de suscripción. En el caso de los productos de compra única, ProductDetails contiene un ProductDetails.OneTimePurchaseOfferDetails. Se pueden usar para decidir qué ofertas mostrar a los usuarios.

En el siguiente ejemplo, se muestra cómo podría verse tu app antes y después de realizar estos cambios:

Antes

val skuList = ArrayList<String>()

skuList.add("up_basic_sub")

val params = SkuDetailsParams.newBuilder()

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

billingClient.querySkuDetailsAsync(params) {
    billingResult,
    skuDetailsList ->
    // Process the result
}

List<String> skuList = new ArrayList<>();

skuList.add("up_basic_sub");

SkuDetailsParams.Builder params = SkuDetailsParams.newBuilder();

params.setSkusList(skuList).setType(SkuType.SUBS).build();

billingClient.querySkuDetailsAsync(params,
    new SkuDetailsResponseListener() {
        @Override
        public void onSkuDetailsResponse(BillingResult billingResult,
                List<SkuDetails> skuDetailsList) {
            // Process the result.
        }
    }
);

Después

val productList =
    listOf(
        QueryProductDetailsParams.Product.newBuilder()
            .setProductId("up_basic_sub")
            .setProductType(BillingClient.ProductType.SUBS)
            .build()
    )

val params = QueryProductDetailsParams.newBuilder().setProductList(productList).build()

billingClient.queryProductDetailsAsync(params) {
    billingResult,
    productDetailsList ->
    // Process the result
}

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
                }
        }
);

La devolución de llamada de queryProductDetailsAsync muestra un List<ProductDetails>. Cada elemento ProductDetails contiene la información sobre el producto (ID, título, tipo, etc.). La principal diferencia es que los productos de suscripción ahora contienen un List<ProductDetails.SubscriptionOfferDetails> con todas las ofertas disponibles para el usuario.

Debido a que las versiones anteriores de la biblioteca de Play Billing no son compatibles con los nuevos objetos (suscripciones, planes básicos, ofertas, etc.), el nuevo sistema convierte cada SKU de suscripción en una sola oferta y plan básico retrocompatible. Los productos de compra única disponibles también se transfieren a un objeto ProductDetails. Se puede acceder a los detalles de la oferta de un producto de compra única con el método getOneTimePurchaseOfferDetails().

En raras ocasiones, algunos dispositivos no admiten ProductDetails y queryProductDetailsAsync(), por lo general, debido a versiones desactualizadas de los Servicios de Google Play. Para garantizar la compatibilidad apropiada en este caso, llama a isFeatureSupported() para obtener la función PRODUCT_DETAILS antes de llamar a queryProductDetailsAsync. Si la respuesta es OK, el dispositivo admite la función y puedes continuar con la llamada a queryProductDetailsAsync(). Si la respuesta es FEATURE_NOT_SUPPORTED, en su lugar, puedes solicitar la lista de productos retrocompatibles disponible con querySkuDetailsAsync(). Para obtener más información para usar las funciones de retrocompatibilidad, consulta la guía de funciones de suscripción de mayo de 2022.

Inicia el flujo de compra de la oferta

Iniciar un flujo de compra de una oferta es muy similar a iniciar un flujo para un SKU. Para iniciar una solicitud de compra con la versión 6, haz lo siguiente:

• En lugar de usar SkuDetails para BillingFlowParams, usa ProductDetailsParams.
• Los detalles de la oferta, como el ID de oferta, el ID del plan básico y otros datos, se pueden obtener si usas el objeto SubscriptionOfferDetails.

Para comprar un producto con la oferta seleccionada del usuario, obtén el offerToken de la oferta seleccionada y pásalo al objeto ProductDetailsParams.

Una vez que hayas creado un objeto BillingFlowParams, el proceso para iniciar el flujo de facturación con el BillingClient es el mismo.

En el siguiente ejemplo, se muestra cómo podría verse tu app antes y después de realizar estos cambios:

Antes

// 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)

// 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)

Después

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...;

val productDetailsParamsList = listOf(
    BillingFlowParams.ProductDetailsParams.newBuilder()
        // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
        .setProductDetails(productDetails)
        // For One-time product, "setOfferToken" method shouldn't be called.
        // For subscriptions, to get the offer token corresponding to the selected
        // offer call productDetails.subscriptionOfferDetails?.get(selectedOfferIndex)?.offerToken
        .setOfferToken(selectedOfferToken)
        .build()
)

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

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

// An activity reference from which the billing flow will be launched.
Activity activity = ...;

ImmutableList<ProductDetailsParams> productDetailsParamsList =
    ImmutableList.of(
        ProductDetailsParams.newBuilder()
             // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
            .setProductDetails(productDetails)
            // For one-time products, "setOfferToken" method shouldn't be called.
            // For subscriptions, to get the offer token corresponding to the selected
            // offer call productDetails.getSubscriptionOfferDetails().get(selectedOfferIndex).getOfferToken()
            .setOfferToken(selectedOfferToken)
            .build()
    );

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

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

Procesa las compras

El procesamiento de compras con la biblioteca de Google Play Billing 6 sigue siendo similar a las versiones anteriores.

Para extraer todas las compras activas que pertenecen al usuario y buscar compras nuevas, haz lo siguiente:

• En lugar de pasar un valor de BillingClient.SkuType a queryPurchasesAsync(), pasa un objeto QueryPurchasesParams que contenga un valor BillingClient.ProductType.

En el siguiente ejemplo, se muestra cómo podría verse tu app antes y después de realizar estos cambios:

Antes

billingClient.queryPurchasesAsync(BillingClient.SkuType.SUBS) {
    billingResult,
    purchaseList -> {
        // Process the result
    }
}

billingClient.queryPurchasesAsync(
    BillingClient.SkuType.SUBS,
    new PurchasesResponseListener() {
        public void onQueryPurchasesResponse(
                BillingResult billingResult,
                List<Purchase> purchases) {
            // process the result
        }
    }
);

Después

billingClient.queryPurchasesAsync(
    QueryPurchasesParams.newBuilder()
        .setProductType(BillingClient.ProductType.SUBS)
        .build()
) { billingResult, purchaseList ->
    // Process the result
}

billingClient.queryPurchasesAsync(
    QueryPurchasesParams.newBuilder().setProductType(ProductType.SUBS).build(),
    new PurchasesResponseListener() {
        public void onQueryPurchasesResponse(
                BillingResult billingResult,
                List<Purchase> purchases) {
            // Process the result
        }
    }
);

No cambiaron los pasos para administrar las compras fuera de la app ni las transacciones pendientes.

Cómo administrar el estado de compra de la suscripción con la nueva API en tu backend

Debes migrar el componente de administración del estado de compra de suscripciones en tu backend para poder procesar las compras de los productos nuevos creados en los pasos anteriores. El componente de administración actual del estado de compra de suscripciones debe funcionar normalmente para los productos de suscripción convertidos que definiste antes del lanzamiento de mayo de 2022 y debería ser suficiente para administrar las compras de ofertas retrocompatibles, pero no admite ninguna de las funciones nuevas.

Debes implementar la nueva API de Subscription Purchases para tu módulo de administración de estados de compra de suscripciones, que verifica el estado de la compra y administra los derechos de suscripción a la Facturación Play en tu backend. La versión anterior de la API no muestra todos los detalles necesarios para administrar las compras en la plataforma nueva. Para obtener detalles sobre los cambios en versiones anteriores, consulta la guía sobre las nuevas funciones de suscripción de mayo de 2022.

Normalmente, llamarías a la API de Subscription Purchases cada vez que recibes una notificaciones para desarrolladores en tiempo real de SubscriptionNotification a fin de extraer la información más reciente sobre el estado de la suscripción. Debes reemplazar tus llamadas a purchases.subscriptions.get con la nueva versión de la API de Subscription Purchases, purchases.subscriptionsv2.get. Hay un nuevo recurso llamado SubscriptionPurchaseV2 que proporciona información suficiente para administrar los derechos de compra de las suscripciones en el modelo nuevo.

Este nuevo extremo muestra el estado de todos los productos de suscripción y todas las compras, sin importar la versión de la app que los vendió y el momento en que se definió el producto (antes o después de la actualización de mayo de 2022). Por lo tanto, después de la migración, solo necesitarás esta versión del módulo de administración del estado de compra de la suscripción.

Cambia las compras de suscripción de un usuario

En la biblioteca de Play Billing 5 y versiones anteriores, se usaba ProrationMode para aplicar cambios en las compras de suscripción de un usuario, por ejemplo, cambios a versiones anteriores o posteriores. Esta función dejó de estar disponible y se reemplazó por ReplacementMode en la versión 6.

Controla los cambios en el precio de las suscripciones

En la biblioteca de Play Billing 6, se quitó la API de launchPriceConfirmationFlow que ya estaba obsoleta. Para conocer otras alternativas, consulta la guía de cambios de precios.

Controla los errores de la biblioteca de Play Billing

En la biblioteca de Play Billing 6, se agregó un nuevo código NETWORK_ERROR para indicar problemas con la conexión de red entre el dispositivo del usuario y el sistema de Google Play. También se modificaron los códigos SERVICE_TIMEOUT y SERVICE_UNAVAILABLE. Para obtener más información, consulta Cómo administrar códigos de respuesta BillingResult.

Controla las transacciones pendientes

A partir de la versión 6.0.0, la biblioteca de Play Billing no crea un ID de pedido para las compras pendientes. Para estas compras, el ID de pedido se propaga después de que la compra pasa al estado PURCHASED. Asegúrate de que tu integración solo espere un ID de pedido después de que se complete una transacción. Puedes seguir usando el token de compra para tus registros. Si quieres obtener más información para controlar las compras pendientes, consulta la guía de integración de la biblioteca de Play Billing y la guía de administración del ciclo de vida de las compras.