Se usó la API de Cloud Translation para traducir esta página.

Implementa la Facturación Play en tu PWA

Si tu PWA aparece en Google Play y quieres monetizarla vendiendo productos integrados en la aplicación o suscripciones, la política de Play te exigirá que implementes la Facturación Play. Deberás implementar dos APIs en tu APW: la API de Digital Goods y la API de Payment Request.

API de Digital Goods

La API de Digital Goods es una interfaz entre tu app y Google Play. Te permite recuperar los productos digitales y los detalles que ingresaste para tus productos integrados en la aplicación y suscripciones en Play Console, así como recuperar las compras existentes que realizó un usuario. Si aún no agregaste productos integrados en la aplicación ni suscripciones en Play Console, asegúrate de seguir la configuración de Play Console para la facturación de Play.

El 30 de noviembre de 2021, se lanzó ChromeOS 96 con la implementación de la API de Digital Goods 2.0.

La prueba de origen de la primera versión de la API de Digital Goods finalizó el 30 de enero de 2022. Por lo tanto, ahora está obsoleta y solo está disponible la versión 2 de la API.

El 23 de junio de 2022, se lanzó ChromeOS 103 con la implementación de la API de Digital Goods 2.1. Esta versión no incluye cambios rotundos y solo incluye métodos nuevos y campos adicionales: listPurchaseHistory() y itemType.

Regístrate para la prueba de origen

Nota: Actualmente, la API de Digital Goods está disponible a través de una prueba de origen, un mecanismo que permite a los desarrolladores acceder de forma anticipada a las nuevas APIs web. Deberás registrarte en la prueba de origen de la API de Digital Goods v2 y solicitar un token, que deberás proporcionar en todas las páginas de tu origen.

Cuando te registres en la prueba de origen, verás una fecha de “Validez hasta” que indica hasta cuándo se garantiza que funcionará tu token. Recuerda renovar tus tokens cuando se acerque esa fecha para seguir participando en la prueba. Las APIs que se ofrecen como prueba de origen están sujetas a cambios, por lo que debes mantenerte al tanto de los cambios más recientes en cualquier prueba de origen en la que participes. En caso de problemas, consulta la documentación de la API de Digital Goods.

API de Payment Request

La API de Payment Request controla la transacción de pago real cuando se realiza una compra. Utiliza los detalles del elemento que proporciona la API de Digital Goods para realizar la compra directa desde la aplicación con la forma de pago adecuada, que, en nuestro caso, es la facturación de Google Play.

Detecta la función de la API de Digital Goods

Puedes detectar si habilitaste correctamente la API en tu sitio web a través de la prueba de origen. Para ello, busca el método getDigitalGoodsService en el objeto window.

if ('getDigitalGoodsService' in window) {
  // Digital Goods API is supported!
} else {
  console.log('DigitalGoodsService is not available.');
  // Use another payment method
}

Conéctate al servicio de Facturación Google Play

La API de Digital Goods se diseñó para que sea compatible con varios navegadores y tiendas digitales, de manera similar a la API de Payment Request, que es independiente del navegador y se puede usar con diferentes proveedores de pagos. Para obtener una instancia del servicio asociado con la Facturación Google Play, pasa la cadena "https://play.google.com/billing" como la forma de pago a getDigitalGoodsService().

Si el método arroja un error, la forma de pago de la Facturación Google Play no está disponible (p.ej., el usuario accede a tu APW a través del navegador). En su lugar, debes ofrecer otra forma de pago para las transacciones.

if ('getDigitalGoodsService' in window) {
  // Digital Goods API is supported!
  try {
    const service = await window.getDigitalGoodsService('https://play.google.com/billing');
    // Google Play Billing service is available
  } catch (error) {
    // Google Play Billing service is not available. Use another payment flow.
  }
}

Obtén detalles del elemento

Una vez que hayas conectado el servicio de bienes digitales a Google Play, podrás usar la API para recuperar información sobre productos y compras.

El método getDetails() te permite obtener información sobre los elementos que configuraste en Play Console. La información, como el título, la descripción y el precio del producto, debe mostrarse al usuario en la IU de tu app para que sepa qué puede comprar y a qué precio.

El método getDetails() necesitará una lista de IDs de elementos que correspondan a los IDs de producto de los productos integrados en la aplicación y las suscripciones que creaste en Play Console.

const itemDetails = await service.getDetails(['product_1', 'product_2', 'product_3']);
for (const item of itemDetails) {
  // Display item information to user
  displayItem(item.title, item.description, item.price);
}

Para obtener el precio adecuado para la configuración regional del usuario, deberás aplicar un formato adicional:

const localePrice = new Intl.NumberFormat(navigator.language, {
  style: 'currency',
  currency: item.price.currency,
}).format(item.price.value);

Nota: La API de Digital Goods no te proporciona un método para obtener una lista de IDs de elementos. En cambio, deberás codificarlos de forma rígida en tu cliente o recuperarlos de tu servidor de backend. La API de Google Play Developer te permite consultar la lista de IDs de elementos desde un backend. (Obtén más información para implementar componentes clave de la Facturación Play en tu servidor de backend). Cualquiera sea la solución que elijas, asegúrate de que los IDs de los elementos coincidan con los que tienes en Play Console.

En la versión 2.1 de la API, uno de los campos que devuelve getDetails() es itemType. Es una enumeración en la que el valor es ”product” o ”subscription” para indicar si el elemento correspondiente es un producto integrado en la aplicación o una suscripción, respectivamente. Poder diferenciar entre los dos tipos de productos puede ser útil si necesitas aplicar tratamientos diferentes a cada tipo de producto. Por ejemplo, puedes tener una página específica para que los usuarios se suscriban y otra página para los demás productos que no son de suscripción. También es útil para conocer el recurso REST de la API de Google Play Developer adecuado para usar en tu backend (purchases.products o purchases.subscriptions).

Comprar un artículo

Una vez que se muestren tus productos y detalles al usuario, puedes compilar el flujo de compra con la API de Payment Request. Cuando se usa en conjunto con la API de Digital Goods, solo se requiere un parámetro de entrada: methodData.

Play Billing solo permite la compra de un solo elemento a la vez. El servidor de Play ya conoce el precio y los detalles del elemento, por lo que el parámetro details no es necesario. Consulta la explicación para obtener una explicación más detallada.

Usa el miembro supportedMethods del parámetro methodData en PaymentRequest para identificar la Facturación de Google Play como la forma de pago con la cadena "https://play.google.com/billing". Luego, en el miembro data, pasa el ID del elemento como sku.

const paymentMethodData = [
  {
    supportedMethods: 'https://play.google.com/billing',
    data: {
      sku: item.itemId,
    },
  },
];

Luego, crea la solicitud de pago y llama a show() para iniciar el flujo de pago:

const request = new PaymentRequest(paymentMethodData);
const paymentResponse = await request.show();

Se mostrará la IU de compra de Play al usuario, en la que verá los detalles del producto que intenta comprar. Puede abandonar la transacción o continuar con el pago. Si el usuario cancela el pago, la promesa que devuelve show() se rechazará con un error. Si paga y completa la compra correctamente, la promesa se resolverá con un PaymentResponse. En la propiedad details de la respuesta de pago, se devuelve un token de compra.

Para evitar el fraude, es fundamental verificar la compra y el token de compra en tu servidor de backend. También es una buena idea hacer un seguimiento de los usuarios y sus tokens de compra asociados. Obtén información para implementar la verificación en tu servidor de backend.

Después de validar la compra, llama a complete() en la respuesta de pago para finalizar el flujo de pago y cerrar la IU de facturación. También puedes pasar una cadena result opcional para indicar el estado del proceso de pago. Depende del navegador proporcionar o no alguna indicación de este resultado al usuario. Chrome no crea ninguna señal visible para el usuario, por lo que se recomienda que muestres tus propios mensajes de error o de éxito en tu PWA.

/* Changes were recently made so that the PaymentResponse `details` property returns the purchase token as `purchaseToken` instead of `token`. Note that `token` will be deprecated at some point in the future. To ensure that your app won't be affected by this, make the change to `purchaseToken` in your client code and use the latest version of Bubblewrap (v1.13.5 and later) to update and generate a new app package to upload to the Play Console. */
const { purchaseToken } = paymentResponse.details;

let paymentComplete;
if (validatePurchaseOnBackend(purchaseToken)) {
  paymentComplete = await paymentResponse.complete('success');
  // Let user know their purchase transaction has successfully completed and been verified
} else {
  paymentComplete = await paymentResponse.complete('fail');
  // Let user know their purchase transaction failed to verify
}

Actualizaciones y cambios a versiones anteriores de suscripciones

Este flujo de compra es el mismo para las compras de productos integrados en la aplicación y de suscripciones. Sin embargo, en el caso de las suscripciones, Google Play tiene opciones de compra adicionales que puedes implementar: actualizar a una versión superior y regresar a una versión anterior. Cuando compiles el objeto data para la forma de pago, deberás pasar lo siguiente para iniciar un flujo de actualización o degradación:

sku: Es el ID del artículo de la nueva suscripción a la que se actualizará o degradará la suscripción.
oldSku: Es el ID del elemento de la suscripción actual del usuario.
purchaseToken: Es el token de compra de la suscripción actual del usuario. Como se mencionó anteriormente, es una buena idea hacer un seguimiento de los tokens de compra en tu backend. En este y otros casos, también debes asociar un usuario a sus compras y tokens de compra actuales.
prorationMode: Indica cómo se cobrará la nueva suscripción cuando reemplace la suscripción actual del usuario.

Modo de prorrateo	Descripción
immediateAndChargeProratedPrice	La suscripción se actualiza de inmediato, y el ciclo de facturación sigue siendo el mismo. Luego se le cobra al usuario la diferencia de precio del período restante.
immediateAndChargeFullPrice	Se actualiza la suscripción o cambia a una versión inferior, y al usuario se le cobra el precio total por el nuevo derecho de inmediato. El valor restante de la suscripción anterior se prorratea para la nueva suscripción. Este modo de prorrateo se agregó recientemente en la versión 4.0 de la Biblioteca de Facturación Google Play. Ahora está disponible a través de Bubblewrap a partir de la versión 1.13.5.
immediateWithoutProration	INHABILITADO TEMPORALMENTE Existe una posible ruta de fraude con este modo de prorrateo en la que los usuarios podrían obtener una suscripción actualizada sin pago adicional durante un ciclo de facturación. Ten en cuenta que inhabilitamos temporalmente este modo mientras trabajamos en la solución.
immediateWithTimeProration	La suscripción se actualiza o se cambia a una versión inferior de inmediato. El tiempo restante se ajusta en función de la diferencia de precio y se atrasa la siguiente fecha de facturación para acreditarlo a la nueva suscripción. Este es el comportamiento predeterminado.
deferred	La suscripción se actualiza o se cambia a una versión inferior solo cuando se renueva. Esto es especialmente útil para las reversiones.
unknownSubscriptionUpgradeDowngradePolicy	No se estableció ninguna política. No se recomienda.

Obtén más información sobre los diferentes modos de prorrateo en la documentación de referencia de la Biblioteca de Facturación Google Play. Consulta la documentación para desarrolladores de Android para obtener más información sobre las actualizaciones y los cambios a versiones inferiores de suscripciones y las recomendaciones sobre el modo de prorrateo.

El uso de estos campos adicionales se verá de la siguiente manera:

const paymentMethod = [
  {
    supportedMethods: 'https://play.google.com/billing',
    data: {
      sku: item.itemId,
      oldSku: oldPurchase.itemId,
      purchaseToken: oldPurchase.purchaseToken,
      prorationMode: 'immediateAndChargeProratedPrice',
    },
  },
];

Aquí, item es el ItemDetails de la nueva suscripción a la que el usuario intenta actualizar o cambiar a una versión inferior, y oldPurchase es el PurchaseDetails de la suscripción actual del usuario.

Cómo confirmar una compra

Después de que un usuario compra un elemento, debes otorgarle los derechos correspondientes (acceso al elemento o al contenido que acaba de comprar). Luego, confirma la compra. Cuando confirmas una compra, le indicas a Google Play que la recibiste y la procesaste correctamente.

Nota: Si no se confirma una compra en un plazo de 72 horas a partir del momento de la compra, se reembolsará el pago al usuario y se revocará la compra. El token de compra ya no será válido, por lo que, cuando consultes las compras existentes, no se devolverá la compra revocada. Esto garantiza que no se le cobre al usuario de forma incorrecta en caso de que se produzca un error de red que impida que se le otorgue el derecho a su elemento.

Debes confirmar las compras desde tu servidor de backend con la API de Google Play Developer. Te recomendamos que otorgues los derechos y, luego, confirmes la compra en tu servidor de backend.

Después de que un usuario realiza una compra del lado del cliente, envía el token de compra y el ID del elemento en una solicitud a tu servidor de backend.
En tu backend, para obtener detalles sobre la compra y verificarla, llama a lo siguiente:
- purchases.products.get para elementos integrados en la aplicación
- purchases.subscriptions.get para suscripciones.
Otorga el derecho correspondiente en la base de datos de tu backend.
Luego, confirma la compra llamando a lo siguiente:
- purchases.products.acknowledge para elementos integrados en la app
- purchases.subscriptions.acknowledge para suscripciones.

Cómo consumir una compra

Cuando confirmas una compra, le indicas a Google Play que el usuario ahora es propietario del elemento y no se le debe permitir comprarlo de nuevo. Si se trata de un elemento que el usuario solo deberá comprar una vez y que tendrá para siempre (p.ej., un aspecto de personaje de juego), el elemento no es consumible.

También puede ser un elemento que le permitas al usuario tener solo uno a la vez. Luego, el usuario deberá usar el elemento antes de poder comprar otro. Cuando el usuario “usa” el elemento, debes llamar al método consume() para que Google Play sepa que el usuario consumió el elemento. Luego, Google Play hará que el elemento esté disponible para que el usuario lo vuelva a comprar.

En el caso de los elementos que permites que un usuario tenga varios, deben poder comprarse repetidamente sin necesidad de usarlos primero (los llamamos elementos repetibles). Del mismo modo, estos elementos deben “consumirse” antes de que Google Play permita que el usuario los vuelva a comprar. Por lo tanto, incluso si el usuario aún no usó el elemento, debes llamar al método consume() para marcarlo como consumido.

// After the user purchases the item, send the purchase token and item ID to your backend to grant the entitlement and acknowledge it right away

. . .
// When the user uses the item or if it is a repeatable item, consume it so it’s available for purchase again.
service.consume(purchaseToken);
}

Cómo consultar las compras existentes

El último flujo de usuarios clave es verificar las compras existentes (productos integrados en la aplicación que aún no se consumieron y suscripciones en curso) para que los usuarios sepan qué suscripción o elementos poseen actualmente. Estas compras existentes provendrán de compras anteriores de Google Play en cualquier dispositivo realizadas en la app o en Play Store. Las compras realizadas fuera de la app en Play Store se denominan compras fuera de la app.

Cuando recuperes compras existentes, también debes verificar el estado de confirmación y confirmar las compras que se realizaron anteriormente, pero no se confirmaron correctamente. Se recomienda confirmar la compra lo antes posible para que los derechos del usuario estén actualizados y se reflejen correctamente en la app.

El método listPurchases() de la API de Digital Goods devolverá una lista de PurchaseDetails que contiene los campos itemId y purchaseToken para cada una de las compras. Deberás usar la API de Google Play Developer en tu servidor de backend para verificar el estado de las compras y confirmarlas de forma adecuada. Podrás:

Llama al método listPurchases() de la API de Digital Goods del cliente para recuperar la lista de compras del usuario.
Para cada compra, pasa purchaseToken y itemId a tu backend.
Si corresponde, otorga el derecho en tu base de datos de backend.
Luego, llama a:y verifica acknowledgementState.
- purchases.products.get para elementos integrados en la aplicación
- purchases.subscriptions.get para suscripciones.
Si el valor es 0 (aún no se confirmó la recepción), llama a lo siguiente:
- purchases.products.acknowledge para elementos integrados en la app
- purchases.subscriptions.acknowledge para suscripciones.

Obtén más información para verificar las compras en tu servidor de backend antes de otorgar derechos.

Historial de compras

Si bien listPurchases devolverá información sobre las compras existentes del usuario, el método listPurchaseHistory() (en la versión 2.1 de la API) devolverá la compra más reciente que hizo el usuario para cada elemento, independientemente de si la compra venció, se canceló o se consumió. El método listPurchaseHistory() devuelve una lista de PurchaseDetails que contiene los campos itemId y purchaseToken para cada compra, que deberás usar con la API de Google Play Developer en tu servidor de backend para recuperar más información.

Compras fuera de la app

Las compras fuera de la app son aquellas que no se realizan en el flujo normal de compras directas desde la app. Por lo general, estas compras se realizan en Play Store en lugar de en tu app. Hay dos formas principales en que los usuarios pueden realizar compras fuera de la app:

Canje de un código promocional: En el menú de usuario de Play Store, en “Ofertas y notificaciones” -> “Canjear código promocional” o en “Pagos y suscripciones” -> “Canjear código de regalo”.
Cómo volver a suscribirse: En el menú de usuario de Play Store, en “Pagos y suscripciones” -> “Suscripciones”. Aquí, los usuarios pueden administrar todas sus suscripciones en diferentes apps. En el caso de las suscripciones vencidas o canceladas, los usuarios tienen la opción de “Volver a suscribirse”.

Cuando los usuarios se vuelven a suscribir desde Play Store, sus compras no se confirman automáticamente, lo que puede provocar que se les reembolse. Este comportamiento es intencional, ya que solo se debe cobrar a los usuarios por su suscripción si abren la app para usarla. El usuario puede ver un mensaje como “Confirmar suscripción” que le recuerde que debe abrir la app.

Se les solicita a los usuarios que confirmen su suscripción abriendo la app para confirmar la compra.

Como desarrollador, es tu responsabilidad implementar el reconocimiento de estos elementos una vez que el usuario inicie la app. Por eso, recomendamos verificar las compras existentes (por lo general, cuando se inicia la app por primera vez) y reconocer las compras que aún no se hayan reconocido.

Permite que los usuarios administren las suscripciones

Para brindar una buena experiencia del usuario, es importante que los usuarios puedan administrar y cancelar sus suscripciones en la app. Te recomendamos que crees un vínculo directo en una página o un menú de configuración que redireccione al usuario a la página de administración de suscripciones de Play Store para tu app. Reemplaza la siguiente URL por los valores adecuados de "sub-product-id" y "app-package-name":

https://play.google.com/store/account/subscriptions?sku=sub-product-id&package=app-package-name

Próximos pasos

Estos flujos de usuarios y fragmentos de código son una implementación básica para demostrar cómo usar la API de Digital Goods y la API de Payment Request en tu PWA para implementar la Facturación de Play. Debes utilizar las APIs según tenga sentido en el contexto y los casos de uso de tu app. Para ver un ejemplo de implementación de extremo a extremo, consulta nuestra muestra de código abierto.

Luego, consulta cómo implementar componentes cruciales de Play Billing en tu servidor de backend para mantener tu app segura y siempre actualizada con los derechos de los usuarios.

Implementa la Facturación Play en tu PWA Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.