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
UserChoiceBillingListenerpara 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 userChoiceBillingListener =
UserChoiceBillingListener { userChoiceDetails ->
// Handle alternative billing choice.
}
var billingClient = BillingClient.newBuilder(context)
.setListener(purchasesUpdatedListener)
.enablePendingPurchases()
.enableUserChoiceBilling(userChoiceBillingListener)
.build()
Java
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.
El país del usuario de Play es compatible |
El país del usuario de Play no es compatible |
|
|---|---|---|
Se llamó a enableUserChoiceBilling durante la configuración de BillingClient |
La persona ve la UX con elección del usuario |
El usuario ve la UX estándar del sistema de Facturación Google Play |
No se llamó a enableUserChoiceBilling 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 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:
Kotlin
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.
}
Java
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 en el plan de suscripción, incluidos los flujos de actualización y de cambio a una versión inferior, deben se manejan de forma diferente según si la suscripción se compró originalmente a través del sistema de facturación de Google Play o uno alternativo.
Los complementos que dependen de una suscripción existente comparten la misma forma de pago.
y alinear los cargos recurrentes se manejan como actualizaciones. Para otros complementos, los usuarios
deberían poder elegir el sistema de facturación que desean usar. Iniciar una nueva campaña
experiencia de compra 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.
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 UserChoiceBillingListener 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 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:
- Identifica el objeto
offerTokende la oferta seleccionada para el plan nuevo:
val offerTokenNewPlan = productDetailsNewPlan
.getSubscriptionOfferDetails(selectedOfferIndex)
.getOfferToken()
String offerTokenNewPlan = productDetailsNewPlan
.getSubscriptionOfferDetails(selectedOfferIndex)
.getOfferToken();
- 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 de licencias deben usarse para probar la integración de facturación alternativa. Tú no se facturarán las transacciones que haya iniciado el verificador con licencia cuentas de servicio. Para obtener más información, consulta Prueba la facturación integrada con licencias de aplicaciones. información sobre la configuración de verificadores con licencia.
Próximos pasos
Una vez que termines la integración en la app, tendrás todo listo para integrar tu backend.