In-app Billing API

La In-app Billing Version 3 API facilita la incorporación de facturación integrada en tus aplicaciones. Entre las funciones de esta versión se incluyen un flujo sincrónico de compra mejorado, las API para que puedas rastrear fácilmente la propiedad de bienes consumibles, y el almacenamiento de datos de compras directas desde la aplicación en caché local.

Tipos de productos

Tus productos se definen por medio de la Google Play Developer Console; se incluyen el tipo de productos, la SKU, el precio y la descripción, entre otros elementos. Para obtener más información, consulta Administrar la facturación integrada. La Version 3 API admite productos integrados en la aplicación gestionados y suscripciones.

Productos integrados en la aplicación gestionados

Los productos integrados en la aplicación gestionados son artículos cuya información de propiedad se rastrea y administra a través de Google Play. Cuando un usuario adquiere un artículo integrado en la aplicación gestionado, Google Play almacena la información de la compra de cada artículo por cada usuario. Esto te permite realizar posteriormente, y en cualquier momento, consultas a Google Play para que recupere el estado de los artículos que un usuario en particular haya adquirido. Esta información se conserva en los servidores de Google Play incluso si el usuario desinstala la aplicación o cambia de dispositivo.

Si usas la Version 3 API, también puedes consumir artículos gestionados dentro de tu aplicación. Normalmente, implementarás el consumo para aquellos artículos que puedan adquirirse varias veces (tales como dinero de un juego, combustible o hechizos). Una vez adquirido, un artículo gestionado no puede comprarse nuevamente hasta que lo consumas, mediante el envío de una solicitud de consumo a Google Play. Para más información sobre el consumo de productos integrados en la aplicación, visita Consumo de artículos.

Suscripciones

Una suscripción es un tipo de producto que se ofrece mediante facturación integrada y te permite vender contenido, servicios o funciones a los usuarios desde tu app con facturación periódica mensual o anual. Puedes vender suscripciones a casi cualquier tipo de contenido digital desde cualquier tipo de aplicación o juego. Para entender el funcionamiento de las suscripciones, visita Suscripciones de facturación integrada.

Con la Version 3 API, puedes usar el mismo flujo de compra para adquirir suscripciones y obtener información sobre compras de suscripciones, como en el caso de los productos integrados en la aplicación. Para ver un ejemplo de código, visita Implementación de suscripciones.

Importante: A diferencia de los productos integrados en la aplicación, las suscripciones no pueden consumirse.

Compra de artículos

Figura 1: Secuencia básica para una solicitud de compra.

A continuación puedes ver un flujo de compra típico con la Version 3 API:

  1. Tu aplicación envía una solicitud isBillingSupported a Google Play para determinar que sea compatible la versión de destino de la In-app Billing API que uses.
  2. Cuando se inicie tu aplicación o el usuario acceda a ella, una buena práctica es consultar a Google Play para determinar los artículos que posee el usuario. Para consultar las compras directas desde la aplicación realizadas por el usuario, envía una solicitud getPurchases. Si la solicitud tiene éxito, Google Play muestra un Bundle que contiene una lista de las ID de producto de los artículos comprados, una lista de los detalles de las compras individuales y una lista de las firmas para las compras.
  3. Normalmente, querrás informar al usuario sobre los productos que estén disponibles para la compra. Para consultar los detalles de los productos integrados en la aplicación que hayas definido en Google Play, tu aplicación puede enviar una solicitud getSkuDetails. Debes especificar una lista de los ID de producto en la solicitud de consulta. Si la solicitud tiene éxito, Google Play muestra un Bundle que contiene información detallada de los productos, incluidos el precio, el título, la descripción y el tipo de compra.
  4. Si el usuario no posee el producto integrado en la aplicación. puedes iniciar la compra del mismo. Para iniciar una solicitud de compra, tu aplicación envía una solicitud getBuyIntent, en la que especifica el ID de producto del artículo que se comprará y otros parámetros. Debes registrar el ID de producto cuando crees un nuevo producto integrado en la aplicación en la Developer Console.
    1. Google Play muestra un Bundle que contiene un PendingIntent que tu aplicación usa para iniciar la IU del proceso de finalización de compra.
    2. Tu aplicación inicia la intent pendiente llamando al método startIntentSenderForResult.
    3. Cuando el flujo de finalización de compra termina (es decir que el usuario compra el artículo correctamente o cancela la compra), Google Play envía una respuesta Intent a tu método onActivityResult. El código de resultado del onActivityResult tiene un código de resultado que indica si la compra fue exitosa o se canceló. El Intent de respuesta contiene información sobre el artículo adquirido, en la que se incluye una string purchaseToken que Google Play genera para identificar exclusivamente a esta transacción de compra. El Intent también contiene la firma de la compra, que se firma con tu clave privada de desarrollador.

Para obtener más información sobre las llamadas de la Version 3 API y las respuestas del servidor, visita Referencias sobre facturación integrada.

Consumo de productos integrados en la aplicación

Puedes usar el mecanismo de consumo para rastrear la propiedad del usuario de los productos integrados en la aplicación.

En la versión 3, se gestionan todos los productos integrados en la aplicación. Esto significa que Google Play mantiene la propiedad del usuario respecto de todas las compras de artículos integrados en la aplicación, y tu aplicación puede consultar la información sobre la compra del usuario cuando sea necesario. Cuando el usuario compra correctamente un producto integrado en la aplicación, esa compra queda registrada en Google Play. Una vez que se concreta la compra de un producto integrado en la aplicación, se lo considera como “adquirido”. Los productos integrados en la aplicación en estado “adquirido” no pueden comprarse desde Google Play. Para que un producto integrado en la aplicación “adquirido” vuelva a estar disponible para la compra en Google Play, debes enviar una solicitud de consumo relacionada con este. El consumo del producto integrado en la aplicación restablece el estado “no adquirido” y descarta la información de compra anterior.

Figura 2: Secuencia básica de una solicitud de consumo.

Para recuperar la lista de productos adquiridos por el usuario, tu aplicación envía una llamada de getPurchases a Google Play. Tu aplicación puede hacer una solicitud de consumo enviando una llamada consumePurchase. En el argumento de la solicitud, debes especificar la string purchaseToken única del producto integrado en la aplicación que obtuviste de Google Play cuando se compró. Google Play muestra un código de estado que indica si el consumo se registró con éxito.

Productos consumibles y no consumibles integrados en la aplicación

Serás tú quien decida si gestionarás tus productos integrados en la aplicación como artículos consumibles o no consumibles.

Artículos no consumibles
Normalmente, no se implementará el consumo para productos integrados en la aplicación que solo puedan comprarse una vez en tu aplicación y brinden beneficios permanentes. Una vez comprados, estos artículos se asociarán de manera permanente a la cuenta de Google del usuario. Un ejemplo de un producto integrado en la aplicación no consumible es una mejora a premium o un paquete de niveles.
Artículos consumibles
Por el contrario, puedes implementar el consumo para los artículos que puedan estar disponibles para la compra varias veces. Normalmente estos artículos brindan ciertos efectos transitorios. Por ejemplo, el personaje del usuario en el juego puede obtener puntos de vida o recibir monedas de oro adicionales en su inventario. El ofrecimiento de beneficios o efectos del artículo comprado en tu aplicación se denomina aprovisionamiento del producto integrado en la aplicación. Tienes la responsabilidad de controlar y rastrear la manera en que se suministran los productos integrados en la aplicación a los usuarios.

Importante: Antes de suministrar en tu aplicación el producto consumible integrado en la aplicación, debes enviar una solicitud de consumo a Google Play y recibir una respuesta afirmativa en la cual se indique que se registró el consumo.

Gestión de compras consumibles en tu aplicación

Aquí puedes ver el flujo básico para la compra de un producto consumible integrado en la aplicación:

  1. Inicia el flujo de compra con una llamada de getBuyIntent.
  2. Obtén un Bundle de respuesta a través de Google Play en el cual se indique que la compra se completó correctamente.
  3. Si esto sucede, concreta el consumo de la compra haciendo una llamada de consumePurchase.
  4. Obtén un código de respuesta de Google Play indicando si el consumo se completó correctamente.
  5. Si el consumo se completó correctamente, suministra el producto en tu aplicación.

Posteriormente, cuando el usuario inicie tu aplicación o acceda a ella, debes controlar si este posee productos consumibles integrados en la aplicación que estén pendientes. En ese caso, asegúrate de consumir y suministrar esos productos. Aquí puedes ver el flujo de inicio de la aplicación recomendado si implementas productos integrados en tu aplicación:

  1. Envía una solicitud de getPurchases para consultar los productos integrados en la aplicación adquiridos por el usuario.
  2. Si hay productos consumibles integrados en la aplicación, concreta el consumo de los artículos llamando a consumePurchase. Este paso es necesario porque la aplicación puede completar previamente la orden de compra para el artículo consumible, pero también puede detenerse o desconectarse antes de enviar una solicitud de consumo.
  3. Obtén un código de respuesta de Google Play indicando si el consumo se completó correctamente.
  4. Si el consumo se completó correctamente, suministra el producto en tu aplicación.

Almacenamiento en caché local

Debido a que el cliente de Google Play ahora almacena la información de facturación integrada en el caché local del dispositivo, puedes usar la Version 3 API para consultar esta información de manera más frecuente; por ejemplo, a través de una llamada de getPurchases. A diferencia de las versiones anteriores de la API, muchas de las llamadas de la Version 3 API se harán a través de búsquedas en el caché, y no a través de una conexión de red a Google Play. Esto reduce considerablemente el tiempo de respuesta de la API.