Recibe pagos a través de la Facturación Google Play con la API de Digital Goods y la API de Payment Request

André Cipriani Bandarra
André Cipriani Bandarra
Twitter GitHub Glitch Mastodon Página principal

Si tu app se distribuye en Google Play y quieres ofrecer suscripciones o vender artículos digitales, debes usar la Facturación Google Play. La Facturación Google Play ofrece herramientas para administrar tu catálogo, precios y suscripciones, informes útiles y un flujo de confirmación de la compra potenciado por Play Store que tus usuarios ya conocen.

En el caso de las apps compiladas con Trusted Web Activities y publicadas a través de Google Play Store, ahora puedes usar la API de Payment Request y la API de Digital Goods para integrarlas con la Facturación Google Play. Está disponible en Chrome 101 y versiones posteriores para Android y ChromeOS.

En esta guía, aprenderás a agregar compatibilidad con la Facturación Google Play a tu AWP y empaquetarla para distribuirla en Google Play Store en ChromeOS y Play Store.

Usarás dos APIs de plataformas web para agregar compatibilidad con Facturación Play a tu AWP. La API de Digital Goods se usa para recopilar información de SKU y verificar compras y derechos de Play Store. La API de Payment Request se usa para configurar Google Play Store como la forma de pago y completar el flujo de compra.

Cómo monetizar aplicaciones en Play Store

Puedes monetizar tu aplicación de dos maneras con la Facturación Google Play en Play Store:

  • Las compras directas desde la aplicación permiten vender bienes virtuales duraderos y consumibles, como funciones adicionales, o quitar anuncios.
  • Las suscripciones ofrecen a los usuarios acceso continuo a contenido o servicios por una tarifa recurrente, como suscripciones a noticias o membresías.

Requisitos

Para configurar la Facturación Google Play, necesitarás lo siguiente:

Cómo actualizar el proyecto Bubblewrap

Si no tienes el envoltorio instalado, deberás instalarlo. Consulta la Guía de inicio rápido para obtener detalles sobre cómo comenzar. Si ya tienes Bubblewrap, asegúrate de actualizarlo a la versión 1.8.2 o una posterior.

Burbujas también tiene la función detrás de una marca. Para habilitarla, deberás modificar la configuración del proyecto en twa-manifest.json, ubicado en la raíz del proyecto, y habilitar alphaDependencies y la función playBilling:

  ...,
  "enableNotifications": true,
  "features": {
    "playBilling": {
      "enabled": true
    }
  },
  "alphaDependencies": {
    "enabled": true
  },
  ...

Con el archivo de configuración actualizado, ejecuta bubblewrap update para aplicar la configuración al proyecto, seguido de bubblewrap build para generar un nuevo paquete de Android y subirlo a Play Store.

Función que detecta la API de Digital Goods y la disponibilidad de la Facturación Google Play

Actualmente, la API de Digital Goods solo es compatible con Chrome cuando la AWP se ejecuta dentro de una actividad web de confianza, y es posible detectar si está disponible si se verifica getDigitalGoodsService en el objeto window:

if ('getDigitalGoodsService' in window) {
 // Digital Goods API is supported!
}

La API de Digital Goods puede estar disponible en cualquier navegador y admitir diferentes tiendas. A fin de verificar si se admite un backend de tienda en particular, deberás invocar a getDigitalGoodsService() y pasar el ID de tienda como parámetro. Google Play Store se identifica con la cadena https://play.google.com/billing:

if ('getDigitalGoodsService' in window) {
  // Digital Goods API is supported!
  try {
    const service =
        await window.getDigitalGoodsService('https://play.google.com/billing');
    // Google Play Billing is supported!

  } catch (error) {
    // Google Play Billing is not available. Use another payment flow.
    return;
  }
}

Recupera los detalles de un SKU

La API de Digital Goods proporciona getDetails(), que permite recuperar información del backend de pagos, como el título del producto, la descripción y, lo que es más importante, el precio.

Luego, puedes usar esta información en la interfaz de uso y proporcionarle más detalles al usuario:

const skuDetails = await service.getDetails(['shiny_sword', 'gem']);
for (item of skuDetails) {
  // Format the price according to the user locale.
  const localizedPrice = new Intl.NumberFormat(
      navigator.language,
      {style: 'currency', currency: item.price.currency}
    ).format(item.price.value);

  // Render the price to the UI.
  renderProductDetails(
        item.itemId, item.title, localizedPrice, item.description);
}

Crea el flujo de compra

El constructor de una PaymentRequest toma dos parámetros: una lista de formas de pago y una lista de detalles de pago.

Cuando estás dentro de Trusted Web Activity, debes usar la forma de pago de Facturación Google Play. Para ello, debes configurar https://play.google.com/billing como el identificador y agregar el SKU del producto como miembro de los datos:

async function makePurchase(service, sku) {
   // Define the preferred payment method and item ID
   const paymentMethods = [{
       supportedMethods: "https://play.google.com/billing",
       data: {
           sku: sku,
       }
   }];

   ...
}

Si bien los detalles del pago son obligatorios, la Facturación Play ignorará esos valores y usará los establecidos cuando se cree el SKU en Play Console, de modo que se puedan completar con valores falsos:

const paymentDetails = {
    total: {
        label: `Total`,
        amount: {currency: `USD`, value: `0`}
    }
};

const request = new PaymentRequest(paymentMethods, paymentDetails);

Llama a show() en el objeto de solicitud de pago para iniciar el flujo de pago. Si la promesa se realiza correctamente, es posible que el pago se haya realizado correctamente. Si falla, es probable que el usuario haya anulado el pago.

Si la promesa se cumple correctamente, tendrás que verificar y confirmar la compra. Para brindar protección contra fraudes, debes implementar este paso mediante tu backend. Consulta la documentación de Facturación Play para obtener información sobre cómo implementar la verificación en tu backend. Si no confirmas la compra, después de tres días, el usuario recibirá un reembolso y Google Play la revocará.

...
const request = new PaymentRequest(paymentMethods, paymentDetails);
try {
    const paymentResponse = await request.show();
    const {purchaseToken} = paymentResponse.details;

    // Call backend to validate and acknowledge the purchase.
    if (await acknowledgePurchaseOnBackend(purchaseToken, sku)) {
        // Optional: tell the PaymentRequest API the validation was
        // successful. The user-agent may show a "payment successful"
        // message to the user.
        const paymentComplete = await paymentResponse.complete('success');
    } else {
        // Optional: tell the PaymentRequest API the validation failed. The
        // user agent may show a message to the user.
        const paymentComplete = await paymentResponse.complete('fail');
    }
} catch(e) {
    // The purchase failed, and we can handle the failure here. AbortError
    // usually means a user cancellation
}
...

De manera opcional, se puede llamar a consume() en un purchaseToken para marcar la compra como usada y permitir que se vuelva a comprar.

Al juntar todo, un método de compra se ve de la siguiente manera:

async function makePurchase(service, sku) {
    // Define the preferred payment method and item ID
    const paymentMethods = [{
        supportedMethods: "https://play.google.com/billing",
        data: {
            sku: sku,
        }
    }];

    // The "total" member of the paymentDetails is required by the Payment
    // Request API, but is not used when using Google Play Billing. We can
    // set it up with bogus details.
    const paymentDetails = {
        total: {
            label: `Total`,
            amount: {currency: `USD`, value: `0`}
        }
    };

    const request = new PaymentRequest(paymentMethods, paymentDetails);
    try {
        const paymentResponse = await request.show();
        const {purchaseToken} = paymentResponse.details;

        // Call backend to validate and acknowledge the purchase.
        if (await acknowledgePurchaseOnBackend(purchaseToken, sku)) {
            // Optional: consume the purchase, allowing the user to purchase
            // the same item again.
            service.consume(purchaseToken);

            // Optional: tell the PaymentRequest API the validation was
            // successful. The user-agent may show a "payment successful"
            // message to the user.
            const paymentComplete =
                    await paymentResponse.complete('success');
        } else {
            // Optional: tell the PaymentRequest API the validation failed.
            // The user agent may show a message to the user.
            const paymentComplete = await paymentResponse.complete('fail');
        }
    } catch(e) {
        // The purchase failed, and we can handle the failure here.
        // AbortError usually means a user cancellation
    }
}

Cómo verificar el estado de las compras existentes

La API de Digital Goods te permite verificar si el usuario tiene derechos existentes (compras directas desde la aplicación que aún no se consumieron o suscripciones en curso) de compras anteriores que haya realizado, ya sea en otro dispositivo, de una instalación anterior, canjeados de un código promocional o solo la última vez que abrió la app.


const service =
     await window.getDigitalGoodsService('https://play.google.com/billing');
...
const existingPurchases = await service.listPurchases();
for (const p of existingPurchases) {
    // Update the UI with items the user is already entitled to.
    console.log(`Users has entitlement for ${p.itemId}`);
}

También es un buen momento para verificar las compras que se realizaron anteriormente, pero que no se confirmaron. Te recomendamos que confirmes las compras lo antes posible para asegurarte de que los derechos de los usuarios se reflejen de forma correcta en tu app.

const service =
     await window.getDigitalGoodsService("https://play.google.com/billing");
...
const existingPurchases = await service.listPurchases();
for (const p of existingPurchases) {
    await verifyOrAcknowledgePurchaseOnBackend(p.purchaseToken, p.itemId);

    // Update the UI with items the user is already entitled to.
    console.log(`Users has entitlement for ${p.itemId}`);
}

Cómo probar tu integración

En un dispositivo Android de desarrollo

Es posible habilitar la API de Digital Goods en un dispositivo Android de desarrollo para realizar pruebas:

  • Asegúrate de usar Android 9 o versiones posteriores con el modo de desarrollador habilitado.
  • Instala Chrome 101 o una versión más reciente.
  • Para habilitar las siguientes marcas en Chrome, navega a chrome://flags y busca la marca por su nombre:
    • #enable-debug-for-store-billing
  • Asegúrate de que el sitio esté alojado con un protocolo HTTPS. Usar HTTP hará que la API sea undefined

En un dispositivo ChromeOS

La API de Digital Goods estará disponible en la versión estable de ChromeOS a partir de la versión 89. Mientras tanto, es posible probar la API de Digital Goods:

  • Instala la app desde Play Store en el dispositivo.
  • Asegúrate de que el sitio esté alojado con un protocolo HTTPS. Usar HTTP hará que la API sea undefined

Con usuarios de prueba y equipos de QA

Play Store ofrece indicaciones para realizar pruebas, como cuentas de prueba de usuario y SKU de prueba. Consulta la documentación de prueba de la Facturación Google Play para obtener más información.

¿Qué debo hacer ahora?

Como se explica en este documento, la API de Play Billing tiene componentes del cliente, que administra la API de Digital Goods, y componentes del servidor.