Guía de integración en la app para facturación alternativa (solo en Corea del Sur)

En esta guía, se describe cómo integrar las APIs de facturación alternativas 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: enableAlternativeBilling.
  • Debes registrar un AlternativeBillingListener 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:

Kotlin

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

val alternativeBillingListener =
   AlternativeBillingListener { alternateChoiceDetails ->
       // Handle alternative billing choice.
   }

var billingClient = BillingClient.newBuilder(context)
   .setListener(purchasesUpdatedListener)
   .enablePendingPurchases()
   .enableAlternativeBilling(alternativeBillingListener)
   .build()

Java

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

private AlternativeBillingListener alternativeBillingListener = new AlternativeBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
        AlternativeChoiceDetails alternateChoiceDetails) {
        // Handle new Google Play purchase.
    }
};

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableAlternativeBilling(alternativeBillingListener)
    .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 corresponde al producto y la oferta que el usuario quiere adquirir. Si el usuario elige el sistema de Facturación 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 lógica:

  • El sistema verifica si el país de Google Play del usuario es Corea del Sur. Si el país de Google Play del usuario es Corea del Sur, Google Play verifica si se habilitó la facturación alternativa en función de la configuración de BillingClient.

    • Si se habilitó la facturación alternativa, el flujo de compra muestra la nueva UX.
    • Si no está habilitada la facturación alternativa, el flujo de compra muestra la UX del sistema de facturación estándar de Google Play, sin la elección del usuario.
  • Si el país de Google Play del usuario no es Corea del Sur, el flujo de compra mostrará la UX estándar del sistema de Facturación Google Play sin la elección del usuario.

El país del usuario de Play es Corea del Sur El país del usuario del juego no es Corea del Sur
Se llamó a enableAlternativeBilling durante la configuración de BillingClient El usuario ve una UX nueva El usuario ve la UX estándar del sistema de Facturación Google Play
No se llamó a enableAlternativeBilling durante la configuración de BillingClient El usuario ve la UX estándar del sistema de Facturación Google Play El usuario ve la UX estándar del sistema de Facturación Google Play

Cómo controlar la selección de usuarios

La manera en la que el resto del flujo de compra se diferencia en función de si el usuario seleccionó el sistema de Facturación Google Play o un sistema de facturación alternativo.

Cuando el usuario selecciona un sistema de facturación alternativo

Si el usuario elige el sistema de facturación alternativo, Google Play llama a AlternativeBillingListener 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 externo que se proporciona en el objeto AlternativeChoiceDetails 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.

AlternativeBillingListener 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 de facturación alternativo del desarrollador, debes informar la transacción a Google Play. Para ello, llama a la API de Google Play Developer desde tu servidor y proporciona el objeto 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 AlternativeBillingListener:

Kotlin

private val alternativeBillingListener =
    AlternativeBillingListener { alternativeChoiceDetails ->
        // Get the products being purchased by the user.
        val products = alternativeChoiceDetails.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(
            alternativeChoiceDetails.externalTransactionToken,
            user
        )

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

Java

private AlternativeBillingListener alternativeBillingListener = new AlternativeBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
           AlternativeChoiceDetails alternateChoiceDetails) {
       // Get the products being purchased by the user.
       List<Product> products =
              alternativeChoiceDetails.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(
              alternateChoiceDetails.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 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 procesar las nuevas compras directas desde la aplicación a través del sistema de Facturación Google Play.
  • Consulta Suscripciones nuevas en la guía de administración de suscripciones para obtener información adicional sobre las compras de suscripciones.

Controla los cambios en la suscripción

Para los desarrolladores que usan un sistema de facturación alternativo, las compras deben procesarse a través del sistema de Facturación 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 flujos de actualización y de cambio a una versión inferior deben manejarse de forma 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.

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 una versión anterior. 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 anteriores. En este caso, la llamada a launchBillingFlow genera un token de transacción externo nuevo para la transacción que puedes recuperar desde la devolución de llamada.

Kotlin

// 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 AlternativeBillingListener is triggered.

Java

// 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 AlternativeBillingListener is triggered.

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

Suscripciones compradas a través del sistema de Facturación 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 debe mostrará el flujo de actualización o de cambio a una versión anterior en el sistema de Facturación Google Play. En las siguientes instrucciones, se describe cómo iniciar el flujo de compra de una actualización o una versión anterior a través del sistema de Facturación Google Play:

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

    Kotlin

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

    Java

    String offerTokenNewPlan = productDetailsNewPlan
                         .getSubscriptionOfferDetails(selectedOfferIndex)
                         .getOfferToken();
    
  2. Envía la información correcta al sistema de Facturación Google Play para procesar la compra nueva, incluido el token de compra de la suscripción existente:

    Kotlin

    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)
    

    Java

    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 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 hasta que finalice 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 siendo 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 Google Play

Por lo general, los usuarios pueden restablecer las suscripciones en el sistema de Facturación 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 mediante la función Volver a suscribirse de Google Play. En ese caso, recibirás una notificación de desarrollador en tiempo real SUBSCRIPTION_RESTARTED en tu backend y no se emitirá un token de compra nuevo. El token original se usará para lo siguiente: continuar con la suscripción. Para obtener información sobre cómo 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 de desarrollador 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 anterior, 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 Inicia el flujo de facturación a elección del usuario.

Próximos pasos

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