Cómo integrar la Biblioteca de Facturación Google Play a tu app

En este tema, se describe cómo integrar la Biblioteca de Facturación Google Play a tu app para comenzar a vender productos.

Duración de una compra

Este es un flujo de compra típico para una compra única o una suscripción.

1. Muéstrale al usuario lo que puede comprar.
2. Inicia el flujo de compra para que el usuario acepte la compra.
3. Verifica la compra en tu servidor.
4. Proporciona contenido al usuario.
5. Confirma la entrega del contenido. En el caso de productos de consumo, procesa la compra de modo que el usuario pueda volver a comprar el artículo.

Las suscripciones se renuevan automáticamente hasta que se cancelan. Una suscripción puede pasar por los siguientes estados:

• Activa: El usuario está en regla y tiene acceso a la suscripción.
• Cancelada: El usuario la canceló, pero aún tiene acceso hasta el vencimiento.
• En período de gracia: El usuario tuvo un problema con el pago, pero aún tiene acceso. Mientras tanto, Google intenta procesar el pago nuevamente.
• En espera: El usuario tuvo un problema con el pago y ya no tiene acceso. Mientras tanto, Google intenta procesar el pago nuevamente.
• Detenida: El usuario detuvo el acceso y no podrá acceder hasta que lo reanude.
• Vencida: El usuario canceló la suscripción y perdió el acceso a ella. Se considera que el usuario desertó luego del vencimiento.

Cómo inicializar una conexión con Google Play

El primer paso para integrar el sistema de facturación de Google Play es agregar la Biblioteca de Facturación Google Play a tu app e inicializar una conexión.

Cómo agregar la dependencia de la Biblioteca de Facturación Google Play

Agrega la dependencia de la Biblioteca de Facturación Google Play al archivo build.gradle de la app como se muestra a continuación:

dependencies {
    def billing_version = "7.1.1"

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

dependencies {
    val billing_version = "7.1.1"

    implementation("com.android.billingclient:billing:$billing_version")
}

Si usas Kotlin, el módulo KTX de la Biblioteca de Facturación Google Play es compatible con las extensiones y las corrutinas de Kotlin, y permite la escritura de código idiomático de Kotlin cuando usas la Biblioteca de Facturación Google Play. Para incluir estas extensiones en tu proyecto, agrega la siguiente dependencia al archivo build.gradle de la app como se muestra a continuación:

dependencies {
    def billing_version = "7.1.1"

    implementation "com.android.billingclient:billing-ktx:$billing_version"
}

dependencies {
    val billing_version = "7.1.1"

    implementation("com.android.billingclient:billing-ktx:$billing_version")
}

Cómo inicializar un BillingClient

Una vez que agregues una dependencia en la Biblioteca de Facturación Google Play, deberás inicializar una instancia de BillingClient. BillingClient es la interfaz principal para la comunicación entre la Biblioteca de Facturación Google Play y el resto de la app. BillingClient proporciona métodos de conveniencia, tanto síncronos como asíncronos, para muchas operaciones de facturación comunes. Te recomendamos tener una conexión BillingClient activa a la vez para evitar varias devoluciones de llamada PurchasesUpdatedListener para un solo evento.

Para crear un BillingClient, usa newBuilder(). Puedes pasar cualquier contexto a newBuilder(), y BillingClient lo usará para obtener un contexto de aplicación. Eso significa que no debes preocuparte por las fugas de memoria. Para recibir actualizaciones sobre compras, también debes llamar a setListener() y pasar una referencia a PurchasesUpdatedListener. Este objeto de escucha recibe actualizaciones de todas las compras que se realizan en tu app.

private val purchasesUpdatedListener =
   PurchasesUpdatedListener { billingResult, purchases ->
       // To be implemented in a later section.
   }

private var billingClient = BillingClient.newBuilder(context)
   .setListener(purchasesUpdatedListener)
   // Configure other settings.
   .build()

private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
    @Override
    public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
        // To be implemented in a later section.
    }
};

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    // Configure other settings.
    .build();

Cómo conectarse a Google Play

Después de crear un BillingClient, debes establecer una conexión con Google Play.

Para conectarte a Google Play, llama a startConnection(). El proceso de conexión es asíncrono. Debes implementar un BillingClientStateListener para recibir una devolución de llamada una vez que se complete la configuración del cliente y esté lista para realizar más solicitudes.

También debes implementar la lógica de reintento para controlar las pérdidas de conexión con Google Play. Para implementar la lógica de reintento, anula el método de devolución de llamada onBillingServiceDisconnected() y asegúrate de que BillingClient llame al método startConnection() para volver a conectarse a Google Play antes de realizar más solicitudes.

En el siguiente ejemplo, se muestra cómo iniciar una conexión y probar que esté lista para usarse:

billingClient.startConnection(object : BillingClientStateListener {
    override fun onBillingSetupFinished(billingResult: BillingResult) {
        if (billingResult.responseCode ==  BillingResponseCode.OK) {
            // The BillingClient is ready. You can query purchases here.
        }
    }
    override fun onBillingServiceDisconnected() {
        // Try to restart the connection on the next request to
        // Google Play by calling the startConnection() method.
    }
})

billingClient.startConnection(new BillingClientStateListener() {
    @Override
    public void onBillingSetupFinished(BillingResult billingResult) {
        if (billingResult.getResponseCode() ==  BillingResponseCode.OK) {
            // The BillingClient is ready. You can query purchases here.
        }
    }
    @Override
    public void onBillingServiceDisconnected() {
        // Try to restart the connection on the next request to
        // Google Play by calling the startConnection() method.
    }
});

Cómo mostrar productos disponibles para comprar

Después de establecer una conexión con Google Play, podrás buscar los productos disponibles y mostrarlos a los usuarios.

La consulta de detalles de productos es un paso importante antes de mostrar los productos a los usuarios, ya que devuelve información localizada sobre los productos. En el caso de suscripciones, asegúrate de que la visualización de tus productos cumpla con todas las políticas de Play.

Para buscar detalles de productos integrados en la app, llama a queryProductDetailsAsync().

Para administrar el resultado de la operación asíncrona, también debes especificar un objeto de escucha que implemente la interfaz de ProductDetailsResponseListener. Luego, puedes anular onProductDetailsResponse(), que notifica al objeto de escucha cuando finaliza la consulta, como se muestra en el siguiente ejemplo:

val queryProductDetailsParams =
    QueryProductDetailsParams.newBuilder()
        .setProductList(
            ImmutableList.of(
                Product.newBuilder()
                    .setProductId("product_id_example")
                    .setProductType(ProductType.SUBS)
                    .build()))
        .build()

billingClient.queryProductDetailsAsync(queryProductDetailsParams) {
    billingResult,
    productDetailsList ->
      // check billingResult
      // process returned productDetailsList
}

QueryProductDetailsParams queryProductDetailsParams =
    QueryProductDetailsParams.newBuilder()
        .setProductList(
            ImmutableList.of(
                Product.newBuilder()
                    .setProductId("product_id_example")
                    .setProductType(ProductType.SUBS)
                    .build()))
        .build();

billingClient.queryProductDetailsAsync(
    queryProductDetailsParams,
    new ProductDetailsResponseListener() {
        public void onProductDetailsResponse(BillingResult billingResult,
                List<ProductDetails> productDetailsList) {
            // check billingResult
            // process returned productDetailsList
        }
    }
)

Cuando busques detalles de productos, pasa una instancia de QueryProductDetailsParams que especifique una lista de cadenas del ID del producto creadas en Google Play Console junto con un ProductType. El objeto ProductType puede ser ProductType.INAPP para productos únicos o ProductType.SUBS para suscripciones.

Cómo hacer consultas con extensiones de Kotlin

Si usas extensiones de Kotlin, puedes llamar a la función de extensión queryProductDetails() para buscar los detalles del producto integrado en la app.

queryProductDetails() aprovecha las corrutinas de Kotlin para que no tengas que definir un objeto de escucha independiente. En cambio, la función se suspende hasta que se completa la consulta, y después puedes procesar el resultado:

suspend fun processPurchases() {
    val productList = listOf(
        QueryProductDetailsParams.Product.newBuilder()
            .setProductId("product_id_example")
            .setProductType(BillingClient.ProductType.SUBS)
            .build()
    )
    val params = QueryProductDetailsParams.newBuilder()
    params.setProductList(productList)

    // leverage queryProductDetails Kotlin extension function
    val productDetailsResult = withContext(Dispatchers.IO) {
        billingClient.queryProductDetails(params.build())
    }

    // Process the result.
}

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, obtén información sobre el uso de las funciones de retrocompatibilidad en la Guía de migración de la Biblioteca de Facturación Play 5.

Cómo procesar el resultado

La Biblioteca de Facturación Google Play almacena los resultados de búsqueda en una List de objetos ProductDetails. Luego, puedes llamar a diferentes métodos de cada objeto ProductDetails de la lista para ver información relevante de un producto integrado en la app, como el precio o la descripción. Para ver información detallada del producto disponible, consulta la lista de métodos de la clase ProductDetails.

Antes de poner un artículo en venta, verifica que el usuario no lo tenga. Si el usuario todavía tiene un producto consumible en su biblioteca de artículos, debe procesar su compra antes de volver a comprarlo.

Antes de ofrecer una suscripción, verifica que el usuario no esté suscrito. Además, ten en cuenta lo siguiente:

• queryProductDetailsAsync() devuelve los detalles del producto de suscripción, y se permite un máximo de 50 ofertas por suscripción.
• queryProductDetailsAsync() solo devuelve ofertas para las que el usuario reúne los requisitos. Si el usuario intenta comprar una oferta para la que no reúne los requisitos (por ejemplo, si la app muestra una lista desactualizada de ofertas aptas), Play informa al usuario que no reúne los requisitos, y el usuario puede optar por comprar el plan básico.

Cómo iniciar el flujo de compra

Para iniciar una solicitud de compra desde la app, llama al método launchBillingFlow() del subproceso principal de la app. Este método toma una referencia para un objeto BillingFlowParams que contiene el objeto ProductDetails relevante obtenido de la llamada a queryProductDetailsAsync(). Para crear un objeto BillingFlowParams, usa la clase BillingFlowParams.Builder.

// 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 an offer token, call ProductDetails.subscriptionOfferDetails()
        // for a list of offers that are available to the user
        .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 an offer token, call
            // ProductDetails.subscriptionOfferDetails() for a list of offers
            // that are available to the user.
            .setOfferToken(selectedOfferToken)
            .build()
    );

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

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

El método launchBillingFlow()BillingClient.BillingResponseCode devuelve uno de los códigos de respuesta que se indican en . Asegúrate de verificar este resultado para garantizar que no haya errores al iniciar el flujo de compra. Un BillingResponseCode de OK indica un inicio exitoso.

En una llamada exitosa a launchBillingFlow(), el sistema muestra la pantalla de compra de Google Play. En la Figura 1, se muestra la pantalla de compra de una suscripción:

Google Play llama a onPurchasesUpdated() para enviar el resultado de la operación de compra a un objeto de escucha que implementa la interfaz PurchasesUpdatedListener. El objeto de escucha se especifica con el método setListener() cuando inicializas tu cliente.

Debes implementar onPurchasesUpdated() para controlar los códigos de respuesta posibles. En el siguiente ejemplo, se muestra cómo anular onPurchasesUpdated():

override fun onPurchasesUpdated(billingResult: BillingResult, purchases: List<Purchase>?) {
   if (billingResult.responseCode == BillingResponseCode.OK && purchases != null) {
       for (purchase in purchases) {
           handlePurchase(purchase)
       }
   } else if (billingResult.responseCode == BillingResponseCode.USER_CANCELED) {
       // Handle an error caused by a user cancelling the purchase flow.
   } else {
       // Handle any other error codes.
   }
}

@Override
void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
    if (billingResult.getResponseCode() == BillingResponseCode.OK
        && purchases != null) {
        for (Purchase purchase : purchases) {
            handlePurchase(purchase);
        }
    } else if (billingResult.getResponseCode() == BillingResponseCode.USER_CANCELED) {
        // Handle an error caused by a user cancelling the purchase flow.
    } else {
        // Handle any other error codes.
    }
}

Si la compra es exitosa, se generará una pantalla de compra exitosa de Google Play similar a la Figura 2.

Una compra exitosa también genera un token de compra, es decir, un identificador único que representa al usuario y al ID del producto integrado en la aplicación que compró. Las apps pueden almacenar el token de compra de forma local, aunque recomendamos pasarlo a tu servidor de backend seguro, donde podrás verificar la compra y protegerte contra el fraude. Este proceso se describe más detalladamente en la siguiente sección.

Además, el usuario recibe un correo electrónico con un comprobante de la operación, que incluye un ID de pedido o ID único de la transacción. Los usuarios reciben un correo electrónico con un ID de pedido único por cada compra de producto único, así como por la compra de la suscripción inicial y las renovaciones automáticas posteriores. Puedes usar el ID de pedido para administrar los reembolsos en Google Play Console.

Cómo indicar un precio personalizado

Si tu app puede distribuirse a usuarios de la Unión Europea, usa el método setIsOfferPersonalized() para informar a los usuarios que el precio de un artículo se personalizó con la toma de decisiones automatizada.

Debes consultar el artículo 6 (1) (ea) CRD de la Directiva de Derechos de los Consumidores 2011/83/UE para determinar si el precio que ofreces a los usuarios es personalizado.

setIsOfferPersonalized() toma una entrada booleana. Cuando se establece en true, la IU de Play incluye la divulgación. Cuando es false, la IU omite la divulgación. El valor predeterminado es false.

Para obtener más información, consulta al Centro de ayuda al consumidor.

Cómo procesar las compras

Una vez que un usuario completa una compra, tu app debe procesarla. En la mayoría de los casos, la app recibe notificaciones de las compras realizadas a través del PurchasesUpdatedListener, aunque hay casos en los que tu app sabrá sobre las compras llamando a BillingClient.queryPurchasesAsync(), como se describe en Cómo recuperar las compras.

Además, si tienes un cliente de notificaciones para desarrolladores en tiempo real en tu backend seguro, puedes registrar compras nuevas recibiendo un elemento subscriptionNotification o oneTimeProductNotification que te alertan sobre una compra nueva. Después de recibir estas notificaciones, llama a la API de Google Play Developer para obtener el estado completo y actualizar tu propio estado de backend.

Tu app debe procesar una compra de la siguiente manera:

1. Verifica la compra.
2. Proporciona contenido al usuario y confirma la entrega del contenido. Opcionalmente, marca el artículo como consumido para que el usuario pueda volver a comprarlo.

Para verificar una compra, primero confirma que el estado de compra sea PURCHASED. Si la compra figura como PENDING, debes procesarla según se describe en Cómo administrar transacciones pendientes. En el caso de las compras recibidas de onPurchasesUpdated() o queryPurchasesAsync(), también debes verificar la compra para asegurarte de que sea legítima antes de que la app otorgue los derechos. Si quieres obtener información para verificar correctamente una compra, consulta Cómo verificar las compras antes de otorgar derechos.

Una vez que verifiques la compra, tu app estará lista para otorgarle derechos al usuario. La cuenta de usuario asociada con la compra se puede identificar con el elemento ProductPurchase.obfuscatedExternalAccountId que muestra Purchases.products:get para compras de productos integrados en la aplicación y el elemento SubscriptionPurchase.obfuscatedExternalAccountId que muestra Purchases.subscriptions:get para suscripciones del servidor, o el elemento obfuscatedAccountId de Purchase.getAccountIdentifiers() del cliente si se configuró con setObfuscatedAccountId cuando se realizó la compra.

Después de otorgar los derechos, la app debe confirmar la compra. Esta confirmación le informa a Google Play que otorgaste derechos para la compra.

El proceso para otorgar derechos y confirmar la compra depende de si la compra es por un producto no consumible, por uno consumible o por una suscripción.

Productos consumibles

En el caso de los productos de consumo, si la app tiene un backend seguro, te recomendamos que uses Purchases.products:consume para consumir compras de manera confiable. Asegúrate de que la compra no se haya consumido. Para ello, consulta el objeto consumptionState que aparece en el resultado de la llamada a Purchases.products:get. Si tu app es solo para clientes sin un backend, usa consumeAsync() de la Biblioteca de Facturación Google Play. Ambos métodos cumplen con el requisito de confirmación e indican que tu app le otorgó derechos al usuario. Estos métodos también permiten que tu app habilite el producto único correspondiente al token de compra de entrada para volver a comprar. Con consumeAsync(), también debes pasar un objeto que implemente la interfaz de ConsumeResponseListener. Este objeto controla el resultado de la operación de consumo. Puedes anular el método onConsumeResponse(), que la Biblioteca de Facturación Google Play llama cuando la operación finaliza.

El siguiente ejemplo ilustra el consumo de un producto usando la Biblioteca de Facturación Google Play con el token de compra asociado:

suspend fun handlePurchase(purchase: Purchase) {
    // Purchase retrieved from BillingClient#queryPurchasesAsync or your PurchasesUpdatedListener.
    val purchase : Purchase = ...;

    // Verify the purchase.
    // Ensure entitlement was not already granted for this purchaseToken.
    // Grant entitlement to the user.

    val consumeParams =
        ConsumeParams.newBuilder()
            .setPurchaseToken(purchase.getPurchaseToken())
            .build()
    val consumeResult = withContext(Dispatchers.IO) {
        client.consumePurchase(consumeParams)
    }
}

void handlePurchase(Purchase purchase) {
    // Purchase retrieved from BillingClient#queryPurchasesAsync or your PurchasesUpdatedListener.
    Purchase purchase = ...;

    // Verify the purchase.
    // Ensure entitlement was not already granted for this purchaseToken.
    // Grant entitlement to the user.

    ConsumeParams consumeParams =
        ConsumeParams.newBuilder()
            .setPurchaseToken(purchase.getPurchaseToken())
            .build();

    ConsumeResponseListener listener = new ConsumeResponseListener() {
        @Override
        public void onConsumeResponse(BillingResult billingResult, String purchaseToken) {
            if (billingResult.getResponseCode() == BillingResponseCode.OK) {
                // Handle the success of the consume operation.
            }
        }
    };

    billingClient.consumeAsync(consumeParams, listener);
}

Productos no consumibles

Para confirmar las compras de productos no consumibles, si la app tiene un backend seguro, te recomendamos que uses Purchases.products:acknowledge para confirmar compras de manera confiable. Para asegurarte de que no se haya confirmado la compra con anterioridad, consulta el elemento acknowledgementState del resultado de la llamada a Purchases.products:get.

Si tu app es solo para clientes, usa BillingClient.acknowledgePurchase() de la Biblioteca de Facturación Google Play. Antes de confirmar una compra, la app debe verificar si ya se confirmó a través del método isAcknowledged() en la Biblioteca de Facturación Google Play.

En el siguiente ejemplo, se muestra la confirmación de una compra con la Biblioteca de Facturación Google Play:

val client: BillingClient = ...
val acknowledgePurchaseResponseListener: AcknowledgePurchaseResponseListener = ...

suspend fun handlePurchase() {
    if (purchase.purchaseState === PurchaseState.PURCHASED) {
        if (!purchase.isAcknowledged) {
            val acknowledgePurchaseParams = AcknowledgePurchaseParams.newBuilder()
                    .setPurchaseToken(purchase.purchaseToken)
            val ackPurchaseResult = withContext(Dispatchers.IO) {
               client.acknowledgePurchase(acknowledgePurchaseParams.build())
            }
        }
     }
}

BillingClient client = ...
AcknowledgePurchaseResponseListener acknowledgePurchaseResponseListener = ...

void handlePurchase(Purchase purchase) {
    if (purchase.getPurchaseState() == PurchaseState.PURCHASED) {
        if (!purchase.isAcknowledged()) {
            AcknowledgePurchaseParams acknowledgePurchaseParams =
                AcknowledgePurchaseParams.newBuilder()
                    .setPurchaseToken(purchase.getPurchaseToken())
                    .build();
            client.acknowledgePurchase(acknowledgePurchaseParams, acknowledgePurchaseResponseListener);
        }
    }
}

Suscripciones

Las suscripciones se controlan de manera similar a como se controlan los productos no consumibles. Si es posible, usa Purchases.subscriptions.acknowledge de la API de Google Play Developer para confirmar la compra, de forma confiable, desde tu backend seguro. Para verificar que no se haya confirmado la compra con anterioridad, consulta el elemento acknowledgementState en el recurso de compra de Purchases.subscriptions:get. De lo contrario, puedes confirmar una suscripción con BillingClient.acknowledgePurchase() de la Biblioteca de Facturación Google Play después de verificar isAcknowledged(). Se deben confirmar todas las compras de suscripciones iniciales. Las renovaciones de suscripciones no necesitan confirmarse. Para obtener más información sobre cuándo se deben confirmar las suscripciones, consulta el tema Cómo vender suscripciones.

Cómo recuperar las compras

Utilizar objetos de escucha para las actualizaciones de compra con un PurchasesUpdatedListener no es suficiente para garantizar que tu app procese todas las compras. Es posible que la app no esté al tanto de todas las compras que realizó un usuario. A continuación, se indican algunas situaciones en las que la app podría perder el registro de las compras o desconocerlas:

• Problemas de red durante la compra: Un usuario realiza una compra exitosa y recibe la confirmación de Google, pero su dispositivo pierde la conexión de red antes de recibir la notificación de la compra a través del PurchasesUpdatedListener.
• Varios dispositivos: Un usuario compra un artículo en un dispositivo y, luego, espera ver el elemento cuando cambia de dispositivo.
• Administración de compras realizadas fuera de la app: Algunas compras, como los canjes de promociones, se pueden realizar fuera de la app.

Si quieres resolver estas situaciones, asegúrate de que la app llame a BillingClient.queryPurchasesAsync() en el método onResume() para garantizar que todas las compras se procesen correctamente como se describe en el artículo para procesar compras.

En el siguiente ejemplo, se muestra cómo recuperar las compras de suscripción de un usuario. Ten en cuenta que queryPurchasesAsync() solo muestra las suscripciones activas y las compras únicas no consumidas.

val params = QueryPurchasesParams.newBuilder()
               .setProductType(ProductType.SUBS)

// uses queryPurchasesAsync Kotlin extension function
val purchasesResult = billingClient.queryPurchasesAsync(params.build())

// check purchasesResult.billingResult
// process returned purchasesResult.purchasesList, e.g. display the plans user owns

billingClient.queryPurchasesAsync(
    QueryPurchasesParams.newBuilder()
      .setProductType(ProductType.SUBS)
      .build(),
    new PurchasesResponseListener() {
      public void onQueryPurchasesResponse(BillingResult billingResult, List<Purchase> purchases) {
        // check billingResult
        // process returned purchase list, e.g. display the plans user owns

      }
    }
);

Cómo controlar las compras realizadas fuera de la app

Algunas compras pueden ocurrir fuera de la app, como los canjes de promociones o los recordatorios de abandono de carrito para las compras directas desde la aplicación (CDA) de Google Play Juegos. Cuando un usuario realiza una compra fuera de tu app, espera que esta muestre un mensaje en la app o use algún tipo de mecanismo de notificación para informarle que la app recibió y procesó correctamente la compra. Estos son algunos mecanismos aceptables:

• Mostrar una ventana emergente en la app.
• Enviar el mensaje a una casilla de mensajes integrada en la app e indicar claramente que hay un mensaje nuevo en la casilla.
• Usar un mensaje de notificación del SO.

Ten en cuenta que la app puede estar en cualquier estado cuando reconozca la compra. Incluso es posible que se realice la compra sin que la app esté instalada. Los usuarios esperan recibir la compra cuando reanuden la app, sin importar el estado en el que se encuentre.

Debes poder detectar las compras independientemente del estado en el que se encuentre la app cuando se realice la compra. Sin embargo, hay algunas excepciones en las que es aceptable no notificar de inmediato al usuario que se recibió el elemento. Por ejemplo:

• Durante la parte de acción de un juego, ya que mostrar un mensaje puede distraer al usuario. En este caso, debes notificar al usuario una vez finalizada la acción.
• Durante las escenas cinemáticas, ya que mostrar un mensaje puede distraer al usuario. En este caso, debes notificar al usuario después de que termine la escena.
• Durante el instructivo inicial y las partes de configuración del juego. Te recomendamos notificar a los usuarios nuevos sobre la recompensa inmediatamente después de que abran el juego o durante la configuración inicial del usuario. Sin embargo, es aceptable esperar hasta que la secuencia principal del juego esté disponible para notificar al usuario.

Siempre ten en cuenta al usuario en el momento de decidir cuándo y cómo notificar sobre las compras realizadas fuera de la app. Cada vez que un usuario no recibe una notificación de inmediato, es posible que se confunda y deje de usar la app, e incluso se comunique con el servicio de atención al usuario o se queje en las redes sociales.

Recordatorios de abandono del carrito en la página principal de Google Play Juegos (habilitados de forma predeterminada)

En el caso de los desarrolladores de juegos que monetizan a través de IAP, una forma en que las unidades de mantenimiento de existencias (SKU) que están activas en Google Play Console se pueden vender fuera de tu app es la función Recordatorio de abandono de carrito, que les sugiere a los usuarios que completen las compras que abandonaron anteriormente mientras exploran Google Play Store. Estas compras se realizan fuera de tu app, desde la página principal de Google Play Juegos en Google Play Store.

Esta función está habilitada de forma predeterminada para ayudar a los usuarios a retomar desde donde quedaron y a los desarrolladores a maximizar las ventas. Sin embargo, puedes inhabilitar esta función en tu app. Para ello, envía el formulario de inhabilitación de la función Cart Abandonment Reminder. Para conocer las prácticas recomendadas sobre cómo administrar los SKU en Google Play Console, consulta Cómo crear un producto integrado en la aplicación.

En las siguientes imágenes, se muestra el recordatorio de abandono del carrito que aparece en Google Play Store:

Cómo administrar transacciones pendientes

Google Play admite transacciones pendientes o que requieran uno o más pasos adicionales entre el momento en que un usuario inicia una compra y el momento en que se procesa la forma de pago de la compra. Tu app no debe otorgar derechos a estos tipos de compras hasta que Google te notifique que la forma de pago del usuario se cobró correctamente.

Por ejemplo, un usuario puede iniciar una transacción eligiendo una tienda física en la que pagará más tarde con dinero en efectivo. El usuario recibe un código a través de una notificación y un correo electrónico. Cuando el usuario llega a la tienda física, puede canjear el código con el cajero y pagar en efectivo. Luego, Google les notifica al usuario y a ti que se recibió el pago. Posteriormente, la app puede otorgar derechos al usuario.

Llama a enablePendingPurchases() como parte de la inicialización de BillingClient para habilitar las transacciones pendientes en tu app. Tu app debe habilitar y admitir transacciones pendientes para productos únicos. Antes de agregar compatibilidad, asegúrate de comprender el ciclo de vida de compras para las transacciones pendientes.

Cuando la app reciba una compra nueva, ya sea a través del PurchasesUpdatedListener o como resultado de una llamada a queryPurchasesAsync(), usa el método getPurchaseState() para determinar si el estado de compra es PURCHASED o PENDING. Debes otorgar derechos solo si el estado es PURCHASED.

Si la app se está ejecutando cuando el usuario completa la compra, se vuelve a llamar a PurchasesUpdatedListener, y PurchaseState ahora será PURCHASED. En este punto, la app puede procesar la compra con el método estándar para procesar compras. La app también debe llamar a queryPurchasesAsync() en el método onResume() para controlar las compras que pasaron al estado PURCHASED mientras no se estaba ejecutando.

Cuando la compra pasa de PENDING a PURCHASED, tu cliente de notificaciones para desarrolladores en tiempo real recibe una notificación de ONE_TIME_PRODUCT_PURCHASED o SUBSCRIPTION_PURCHASED. Si se cancela la compra, recibirás una notificación de ONE_TIME_PRODUCT_CANCELED o SUBSCRIPTION_PENDING_PURCHASE_CANCELED. Esto puede suceder si el cliente no completa el pago en el plazo requerido. Ten en cuenta que siempre puedes usar la API de Google Play Developer para verificar el estado actual de una compra.

Cómo administrar compras de varias cantidades

Google Play, compatible con las versiones 4.0 y posteriores de la Biblioteca de Facturación Google Play, permite que los clientes compren, en una transacción, más artículos de un mismo producto integrado en la aplicación si especifican una cantidad en el carrito de compras. Se espera que la app administre compras de varias cantidades y otorgue derechos en función de la cantidad de compra especificada.

Para admitir las compras de varias cantidades, la lógica de aprovisionamiento de la app debe verificar una cantidad de artículos. Puedes acceder a un campo quantity desde una de las siguientes APIs:

• getQuantity() de la Biblioteca de Facturación Google Play
• Purchases.products.quantity de la API de Google Play Developer

Una vez que hayas agregado lógica para controlar las compras de varias cantidades, deberás habilitar la función de varias cantidades para el producto correspondiente en la página de administración de productos integrados en la aplicación en Google Play Console.

Cómo consultar la configuración de facturación del usuario

getBillingConfigAsync() proporciona el país que usa el usuario para Google Play.

Puedes consultar la configuración de facturación del usuario después de crear un BillingClient. En el siguiente fragmento de código, se describe cómo realizar una llamada a getBillingConfigAsync(). Para controlar la respuesta, implementa BillingConfigResponseListener. Este objeto de escucha recibe actualizaciones de todas las consultas de configuración de facturación que se inician desde tu app.

Si el BillingResult que se muestra no contiene errores, puedes verificar el campo countryCode en el objeto BillingConfig para obtener el país de Play del usuario.

// Use the default GetBillingConfigParams.
val getBillingConfigParams = GetBillingConfigParams.newBuilder().build()
billingClient.getBillingConfigAsync(getBillingConfigParams,
    object : BillingConfigResponseListener {
        override fun onBillingConfigResponse(
            billingResult: BillingResult,
            billingConfig: BillingConfig?
        ) {
            if (billingResult.responseCode == BillingResponseCode.OK
                && billingConfig != null) {
                val countryCode = billingConfig.countryCode
                ...
            } else {
                // TODO: Handle errors
            }
        }
    })

// Use the default GetBillingConfigParams.
GetBillingConfigParams getBillingConfigParams = GetBillingConfigParams.newBuilder().build();
billingClient.getBillingConfigAsync(getBillingConfigParams,
    new BillingConfigResponseListener() {
      public void onBillingConfigResponse(
          BillingResult billingResult, BillingConfig billingConfig) {
        if (billingResult.getResponseCode() == BillingResponseCode.OK
            && billingConfig != null) {
            String countryCode = billingConfig.getCountryCode();
            ...
         } else {
            // TODO: Handle errors
        }
      }
    });