Guía de integración en la app para facturación alternativa con elección del usuario

En esta guía, se describe cómo integrar las APIs para ofrecer facturación alternativa con elección del usuario en tu app.

Configuración de la Biblioteca de Facturación Play

Agrega la dependencia de la Biblioteca de Facturación Play a tu app para Android. Si quieres usar las APIs de facturación alternativa, debes utilizar la versión 5.2 o una posterior. Si necesitas migrar desde una versión anterior, sigue las instrucciones de la guía de migración antes de intentar implementar la facturación alternativa.

Cómo conectarse a Google Play

Los primeros pasos del proceso de integración son los mismos que los descritos en la Guía de integración de la Facturación Google Play, con algunas modificaciones cuando inicializas tu BillingClient:

• Debes llamar a un método nuevo para indicar que quieres ofrecerle al usuario opciones de facturación: enableUserChoiceBilling.
• Debes registrar un UserChoiceBillingListener para manejar los casos en los que el usuario elige la facturación alternativa.

En el siguiente ejemplo, se muestra cómo inicializar un objeto BillingClient con estas modificaciones:

val purchasesUpdatedListener =
   PurchasesUpdatedListener { billingResult, purchases ->
       // Handle new Google Play purchase.
   }

val userChoiceBillingListener =
   UserChoiceBillingListener { userChoiceDetails ->
       // Handle alternative billing choice.
   }

var billingClient = BillingClient.newBuilder(context)
   .setListener(purchasesUpdatedListener)
   .enablePendingPurchases()
   .enableUserChoiceBilling(userChoiceBillingListener)
   .build()

private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
    @Override
    public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
        // Handle new Google Play purchase.
    }
};

private UserChoiceBillingListener userChoiceBillingListener = new UserChoiceBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
        UserChoiceDetails userChoiceDetails) {
        // Handle new Google Play purchase.
    }
};

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableUserChoiceBilling(userChoiceBillingListener)
    .build();

Después de inicializar el objeto BillingClient, debes establecer una conexión con Google Play, como se describe en la guía de integración.

Cómo mostrar los productos disponibles

Puedes mostrar los productos disponibles al usuario de la misma manera que con una integración del sistema de Facturación Google Play. Cuando el usuario vea los productos disponibles y seleccione uno para comprar, se iniciará el flujo de facturación a elección del usuario, como se describe en la siguiente sección.

Cómo iniciar el flujo de facturación a elección del usuario

Llama a launchBillingFlow() para iniciar el flujo de facturación a elección del usuario. Esto funciona igual que iniciar un flujo de compra con una integración del sistema de Facturación Google Play: proporcionas una instancia de ProductDetails y un offerToken que corresponden al producto y a la oferta que el usuario quiere adquirir. Si el usuario elige el sistema de facturación de Google Play, esta información se usa para continuar con el flujo de compra.

Cuando los desarrolladores llaman a launchBillingFlow(), el sistema de Facturación Google Play realiza la siguiente verificación:

• El sistema verifica si el país de Google Play del usuario es un país que admite la facturación alternativa con elección del usuario (es decir, un país compatible). Si el país de Google Play del usuario es compatible, Google Play verifica si se habilitó la facturación alternativa según la configuración de BillingClient.
  • Si se habilitó la facturación alternativa con elección del usuario, el flujo de compra mostrará la UX a elección del usuario.
  • Si no está habilitada la facturación alternativa con elección del usuario, el flujo de compra mostrará la UX estándar del sistema de Facturación Google Play, sin la elección del usuario.
• Si el país de Google Play del usuario no es compatible, el flujo de compra mostrará la UX estándar del sistema de Facturación Google Play, sin la elección del usuario.

Cómo controlar la selección de usuarios

La forma en que manejas el resto del flujo de compra difiere según si el usuario seleccionó el sistema de facturación de Google Play o un sistema alternativo de facturación.

Cuando el usuario selecciona un sistema alternativo de facturación

Si el usuario elige el sistema de facturación alternativo, Google Play llama a UserChoiceBillingListener para notificarle a la app que debe iniciar el flujo de compra en ese sistema. En particular, se llama al método userSelectedAlternativeBilling().

El token de transacción externa que se proporciona en el objeto UserChoiceDetails representa una firma para que el usuario ingrese al flujo de facturación alternativo. Usa este token para informar cualquier transacción que resulte de esta opción, como se explica en la guía de integración del backend.

UserChoiceBillingListener debe realizar las siguientes acciones:

• Obtén los productos que compra el usuario para que se puedan presentar en el flujo de compra en el sistema de facturación alternativo.
• Recopila la cadena recibida como token de transacción externa y envíala a tu backend para conservarla. Se usa más adelante para informar la transacción externa a Google Play si el usuario completa esta compra específica.
• Inicia el flujo de compra alternativo del desarrollador.

Si el usuario completa la compra con el sistema alternativo de facturación, debes informar la transacción a Google Play. Para ello, llama a la API de Google Play Developer desde tu backend en un plazo de 24 horas y proporciona el externalTransactionToken y los detalles de la transacción adicionales. Consulta la guía de integración del backend para obtener más detalles.

En el siguiente ejemplo, se muestra cómo implementar UserChoiceBillingListener:

private val userChoiceBillingListener =
    UserChoiceBillingListener { userChoiceDetails ->
        // Get the products being purchased by the user.
        val products = userChoiceDetails.products

        // Send external transaction token to developer backend server
        // this devBackend object is for demonstration purposes,
        // developers can implement this step however best fits their
        // app to backend communication.
        devBackend.sendExternalTransactionStarted(
            userChoiceDetails.externalTransactionToken,
            user
        )

        // Launch alternative billing
        // ...
        // The developer backend handles reporting the transaction
        // to Google Play's backend once the alternative billing
        // purchase is completed.
    }

private userChoiceBillingListener userChoiceBillingListener = new UserChoiceBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
           UserChoiceDetails userChoiceDetails) {
       // Get the products being purchased by the user.
       List<Product> products =
              userChoiceDetails.getProducts();

       // Send external transaction token to developer backend server
       // this devBackend object is for demonstration purposes,
       // developers can implement this step however best fits their
       // app to backend communication.
       devBackend.sendExternalTransactionStarted(
              userChoiceDetails.getExternalTransactionToken(),
              user
       );

       // Launch alternative billing
       // ...
       // The developer backend handles reporting the transaction
       // to Google Play's backend once the alternative billing
       // purchase is completed.
    }
};

Cuando el usuario selecciona el sistema de Facturación Google Play

Si el usuario elige el sistema de facturación de Google Play, continúa con la compra a través de Google Play.

• Consulta la sección sobre cómo procesar compras en la guía de integración de bibliotecas para descubrir cómo manejar las nuevas compras directas desde la aplicación a través del sistema de Facturación Google Play.
• Consulta la sección sobre nuevas suscripciones en la guía de administración de suscripciones para obtener información adicional sobre las compras de suscripciones.

Cómo controlar los cambios en la suscripción

En el caso de los desarrolladores que usan la facturación alternativa con elección del usuario, las compras deben procesarse a través del sistema de facturación de Google Play o informarse con un externalTransactionId, según la elección del usuario. Los cambios en las suscripciones existentes que se procesaron a través del flujo de elección del usuario se pueden realizar a través del mismo sistema de facturación hasta el vencimiento.

En esta sección, se describe cómo abordar algunas situaciones comunes de cambio de suscripción.

Flujos de actualización y de cambio a una versión inferior

Los cambios de plan de suscripción, incluidos los flujos de actualización y de cambio a una versión inferior, deben manejarse de manera diferente según si la suscripción se compró originalmente a través del sistema de Facturación Google Play o a través de un sistema de facturación alternativo.

Los complementos que dependen de una suscripción existente, comparten la misma forma de pago y alinean los cargos recurrentes se manejan como actualizaciones. Para otros complementos, los usuarios deben poder elegir qué sistema de facturación desean usar. Inicia una experiencia de compra nueva con launchBillingFlow(), como se describe en Inicia el flujo de facturación a elección del usuario.

Suscripciones compradas a través de un sistema de facturación alternativo

Para las suscripciones que se compraron originalmente a través del sistema de facturación alternativo del desarrollador después de la elección del usuario, los usuarios que solicitan una actualización o un cambio a una versión inferior deben pasar por el sistema de facturación alternativo del desarrollador sin volver a pasar por la experiencia de elección del usuario.

Para ello, llama a launchBillingFlow() cuando el usuario solicite una actualización o un cambio a una versión inferior. En lugar de especificar un objeto SubscriptionUpdateParams en los parámetros, usa setOriginalExternalTransactionId y proporciona el ID de transacción externo para la compra original. Esto no muestra la pantalla de elección del usuario, ya que la elección del usuario para la compra original se conserva para actualizaciones y cambios a versiones inferiores. En este caso, la llamada a launchBillingFlow() genera un nuevo token de transacción externa para la transacción que puedes recuperar desde la devolución de llamada.

// The external transaction ID from the current
// alternative billing subscription.
val externalTransactionId = //... ;

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                // Fetched via queryProductDetailsAsync.
                .setProductDetails(productDetailsNewPlan)
                // offerIdToken can be found in
                // ProductDetails=>SubscriptionOfferDetails.
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOriginalExternalTransactionId(externalTransactionId)
            .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

// When the user selects the alternative billing flow,
// the UserChoiceBillingListener is triggered.

// The external transaction ID from the current
// alternative billing subscription.
String externalTransactionId = //... ;

BillingFlowParams billingFlowParams =
        BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(
                ImmutableList.of(
                    ProductDetailsParams.newBuilder()
                        // Fetched via queryProductDetailsAsync.
                        .setProductDetails(productDetailsNewPlan)
                        // offerIdToken can be found in
                        // ProductDetails=>SubscriptionOfferDetails
                        .setOfferToken(offerTokenNewPlan)
                    .build()
                )
            )
            .setSubscriptionUpdateParams(
                SubscriptionUpdateParams.newBuilder()
                    .setOriginalExternalTransactionId(externalTransactionId)
                    .build()
            )
            .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

// When the user selects the alternative billing flow,
// the UserChoiceBillingListener is triggered.

Cuando se completa la actualización o el cambio a una versión inferior del sistema alternativo de facturación, debes informar una nueva transacción usando el token de transacción externa que obtuviste en la llamada anterior para la compra de la nueva suscripción.

Suscripciones compradas a través del sistema de facturación de Google Play

Del mismo modo, a los usuarios que compraron su suscripción actual a través del sistema de Facturación Google Play después de su elección se les mostrará el flujo de actualización o de cambio a una versión inferior en el sistema de facturación de Google Play. En las siguientes instrucciones, se describe cómo iniciar el flujo de compra de una actualización o un cambio a una versión inferior a través del sistema de Facturación Google Play:

1. Identifica el objeto offerToken de la oferta seleccionada para el plan nuevo:

val offerTokenNewPlan = productDetailsNewPlan
             .getSubscriptionOfferDetails(selectedOfferIndex)
             .getOfferToken()

String offerTokenNewPlan = productDetailsNewPlan
                     .getSubscriptionOfferDetails(selectedOfferIndex)
                     .getOfferToken();

1. Envía la información correcta al sistema de facturación de Google Play para procesar la compra nueva, incluido el token de compra de la suscripción existente:

val billingFlowParams =
    BillingFlowParams.newBuilder().setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                .setProductDetails(productDetailsNewPlan)
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOldPurchaseToken(oldToken)
            .setReplaceProrationMode(BillingFlowParams.ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
            .build()
        )
        .build()

BillingClient.launchBillingFlow(activity, billingFlowParams)

BillingFlowParams billingFlowParams =
        BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(
                ImmutableList.of(
                    ProductDetailsParams.newBuilder()
                        // Fetched via queryProductDetailsAsync
                        .setProductDetails(productDetailsNewPlan)
                        // offerIdToken can be found in
                        // ProductDetails=>SubscriptionOfferDetails.
                        .setOfferToken(offerTokenNewPlan)
                        .build()
                )
            )
            .setSubscriptionUpdateParams(
                SubscriptionUpdateParams.newBuilder()
                    // purchaseToken can be found in
                    // Purchase#getPurchaseToken
                    .setOldPurchaseToken("old_purchase_token")
                    .setReplaceProrationMode(ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
                    .build()
            )
            .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

Esta compra se lleva a cabo en el sistema de facturación de Google Play, y la app recibe la llamada PurchasesUpdatedListener.onPurchaseUpdated con el resultado de la compra. Si la compra se realizó correctamente, el método onPurchaseUpdated() también recibirá la información de la nueva compra, y tu backend recibirá una notificación para desarrolladores en tiempo real de SUBSCRIPTION_PURCHASED. Cuando extraes el estado de la compra nueva, un atributo linkedPurchaseToken se vincula a la compra de la suscripción anterior para que puedas retirarla como se recomienda.

Cancelaciones y restauraciones de suscripciones

Los usuarios deben poder cancelar su suscripción en cualquier momento. Cuando un usuario cancela una suscripción, es posible que se resuelva el derecho de acceso una vez finalizado el período pago. Por ejemplo, si un usuario cancela una suscripción mensual a mitad de mes, puede seguir accediendo al servicio durante las 2 semanas restantes, aproximadamente, hasta que se quite su acceso. Durante este período, la suscripción sigue estando técnicamente activa, por lo que el usuario puede usar el servicio.

No es inusual que los usuarios decidan revertir la cancelación durante este período activo. En esta guía, ese proceso se denomina restablecimiento. En las siguientes secciones, se describe cómo manejar situaciones de restablecimiento en tu integración de API de facturación alternativa.

Suscripciones compradas a través de un sistema de facturación alternativo

Si tienes un ID de transacción externo para una suscripción cancelada, no es necesario llamar a launchBillingFlow() para restablecer la suscripción, por lo que no se debe usar para este tipo de activación. Si un usuario restablece su suscripción mientras aún está en el período activo de una suscripción cancelada, no se realizará ninguna transacción en ese momento. Puede continuar informando sobre las renovaciones cuando venza el ciclo actual y se produzca la próxima renovación. Esto incluye casos en los que el usuario recibe un crédito o un precio de renovación especial como parte del restablecimiento (por ejemplo, una promoción para motivar al usuario a continuar con la suscripción).

Suscripciones compradas a través del sistema de facturación de Google Play

Por lo general, los usuarios pueden restablecer las suscripciones en el sistema de facturación de Google Play. En el caso de las suscripciones canceladas que se compraron originalmente en el sistema de Facturación Google Play, el usuario puede elegir deshacer la cancelación mientras la suscripción está activa con la función Volver a suscribirse de Google Play. En ese caso, recibirás una notificación para desarrolladores en tiempo real SUBSCRIPTION_RESTARTED en tu backend y no se emitirá un token de compra nuevo. El token original se usará para continuar con la suscripción. Si quieres obtener información para administrar la restauración en el sistema de Facturación Google Play, consulta Restauraciones en la guía de administración de suscripciones.

También puedes llamar a launchBillingFlow() para activar una restauración en el sistema de Facturación Google Play desde la app. Consulta Antes de que venza la suscripción (en la app) para aprender a hacerlo. En el caso de los usuarios que realizaron el proceso de elección de usuario para la compra original (que se canceló, pero aún está activo), el sistema detecta automáticamente su elección y muestra la interfaz de usuario para restablecer esas compras. Se le solicita que confirme su recompra de la suscripción a través de Google Play, pero no es necesario que vuelva a completar el proceso de elección del usuario. En este caso, se emite un nuevo token de compra para el usuario. Tu backend recibe una notificación para desarrolladores en tiempo real SUBSCRIPTION_PURCHASED y el valor linkedPurchaseToken para el estado de compra nuevo se establece como en el caso de una actualización o el cambio a una versión inferior, con el token de compra anterior de la suscripción que se canceló.

Cómo volver a suscribirse

Si una suscripción vence por completo, ya sea debido a una cancelación o el rechazo del pago sin recuperación (una suspensión vencida de la cuenta), el usuario debe volver a suscribirse si desea reiniciar el derecho a utilizarla.

La suscripción nueva también se puede habilitar a través de la app. Para ello, se la procesa de manera similar a un registro estándar. Los usuarios deben poder elegir qué sistema de facturación desean usar. En este caso, se puede llamar a launchBillingFlow(), como se describe en Cómo iniciar el flujo de facturación a elección del usuario.

Prueba la facturación alternativa

Los verificadores con licencia deben usarse para probar la integración de facturación alternativa. No se te facturarán las transacciones que se hayan iniciado con cuentas de verificador con licencia. Consulta Prueba la facturación integrada con licencias de aplicaciones para obtener más información sobre la configuración de verificadores de licencias.

Próximos pasos

Una vez que termines la integración en la app, tendrás todo listo para integrar tu backend.