Guía de migración de la Biblioteca de Facturación Google Play 4 a 5

En este tema, se describe la migración de la Biblioteca de Facturación Google Play 4 a la Biblioteca de Facturación Google Play 5 y el uso de las nuevas capacidades de suscripción.

Resumen

La Biblioteca de Facturación Google Play 5 introdujo planes básicos y ofertas de suscripción. Estas funciones amplían las formas en las que puedes vender suscripciones al reducir los costos operativos, ya que eliminan la necesidad de crear y administrar una cantidad cada vez mayor de SKUs. Para obtener más información, consulta Cambios recientes en las suscripciones en Play Console.

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 Facturación Play 5 y la nueva plataforma de suscripciones. Para obtener más información sobre esta conversión, consulta la sección Cómo trabajar con suscripciones anteriores en el artículo de ayuda de Play Console.

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 prepagados y de renovación automática. Para obtener más información, consulta la guía de integración.

Sin embargo, si no planeas implementar estas nuevas funciones de inmediato, puedes migrar tu app a la Biblioteca de Facturación Play 5 y planificar la migración de los componentes de backend más adelante, siempre y cuando tu catálogo de productos mantenga una configuración retrocompatible.

Pasos de la migración

Cómo crear tu catálogo de productos de backend

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 Facturación Play 5 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.

Cómo administrar 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 Facturación Google Play

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 Facturación Play por la versión actualizada en el archivo build.gradle de la app.

dependencies {
    def billingVersion = "5.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 integramos la retrocompatibilidad con la Biblioteca de Facturación Play 5. Sin embargo, el concepto de SKU se considera obsoleto.

Cómo inicializar el cliente de facturación y cómo establecer 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

Cómo mostrar 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)

billingClient.querySkuDetailsAsync(params.build()) {
    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);

billingClient.querySkuDetailsAsync(params.build(),
    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)

billingClient.queryProductDetailsAsync(params.build()) {
    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 Facturación Play 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 sobre el uso de las funciones de retrocompatibilidad de la Biblioteca de Facturación Play 5, consulta la guía de funciones de suscripción de mayo de 2022.

Cómo iniciar 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 5, 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 los siguientes ejemplos, se muestra cómo se vería 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 = ...;
// Retrieve a value for "productDetails" by calling queryProductDetailsAsync()
// Get the offerToken of the selected offer
val offerToken = productDetails.subscriptionOfferDetails?.get(selectedOfferIndex)?.offerToken

val productDetailsParamsList =
    listOf(
        BillingFlowParams.ProductDetailsParams.newBuilder()
            .setProductDetails(productDetails)
            .setOfferToken(offerToken)
            .build()
    )
val billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(productDetailsParamsList)
        .build()

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

// Retrieve a value for "productDetails" by calling queryProductDetailsAsync()
// Get the offerToken of the selected offer
String offerToken = productDetails
                     .getSubscriptionOfferDetails()
                     .get(selectedOfferIndex)
                     .getOfferToken();
// Set the parameters for the offer that will be presented
// in the billing flow creating separate productDetailsParamsList variable
ImmutableList<ProductDetailsParams> productDetailsParamsList =
        ImmutableList.of(
                 ProductDetailsParams.newBuilder()
                     .setProductDetails(productDetails)
                     .setOfferToken(offerToken)
                     .build()
        );

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

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

Cómo procesar las compras

El procesamiento de compras con la Biblioteca de Facturación Google Play 5 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 los siguientes ejemplos, se muestra cómo se vería 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.