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

Si tu app se distribuye a través de Google Play y quieres vender artículos digitales o ofrecer suscripciones, 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 potenciado por Play Store que ya conocen tus usuarios.

En el caso de las apps compiladas con Actividades web de confianza 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 a empaquetarla para su distribución en Google Play Store para ChromeOS y Play Store.

Usarás dos APIs de la plataforma web para agregar compatibilidad con la Facturación Play a tu AWP. La API de Digital Goods se usa para recopilar información de SKU y verificar compras y derechos desde 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

Existen dos formas en que tu aplicación puede monetizar 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.
  • Suscripciones: Ofrece 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:

Actualiza el proyecto Bubblewrap

Si no tienes instalado Bubblewrap, deberás hacerlo. Consulta la Guía de inicio rápido para obtener más información para comenzar. Si ya tienes Bubblewrap, asegúrate de actualizarlo a la versión 1.8.2 o una posterior.

Bubblewrap también tiene la función detrás de una marca. Para habilitarlo, deberás modificar la configuración del proyecto en twa-manifest.json, que se encuentra 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, Chrome solo admite la API de Digital Goods cuando la AWP se ejecuta dentro de una actividad web confiable, y es posible detectar si está disponible buscando getDigitalGoodsService en el objeto window:

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

Es posible que la API de Digital Goods esté disponible en cualquier navegador y admita diferentes tiendas. Para verificar si se admite un backend de tienda en particular, deberás invocar a getDigitalGoodsService() y pasar el ID de la 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;
  }
}

Cómo recuperar los detalles de un SKU

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

Luego, puedes usar esta información en tu interfaz de usuario y proporcionar 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);
}

Cómo crear el flujo de compra

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

Cuando estés en la actividad web confiable, debes usar la forma de pago de la facturación de Google Play. Para ello, configura https://play.google.com/billing como el identificador y agrega el SKU del producto como miembro de 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,
       }
   }];

   ...
}

Aunque los detalles del pago son obligatorios, la Facturación Google Play ignorará esos valores y usará los valores establecidos cuando se creó el SKU en Play Console, por lo que se pueden 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 abortado el pago.

Si la promesa se realiza correctamente, deberás verificar y confirmar la compra. Para protegerte contra fraudes, este paso se debe implementar con tu backend. Consulta la documentación de Play Billing 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 revocará la compra.

...
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 agotada y permitir que se vuelva a comprar.

Si juntamos 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
    }
}

Verifica el estado de las compras existentes

La API de Digital Goods te permite verificar si el usuario tiene derechos existentes (compras integradas en la app que aún no se consumieron o suscripciones en curso) de compras anteriores que ya realizó, ya sea en otro dispositivo, desde una instalación anterior, canjeadas con 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}`);
}

Este también es un buen momento para buscar compras que se hayan realizado anteriormente, pero que no se hayan confirmado. Se recomienda confirmar las compras lo antes posible para garantizar que los derechos de los usuarios se reflejen correctamente 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

Para realizar pruebas, puedes habilitar la API de Digital Goods en un dispositivo Android de desarrollo:

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

En un dispositivo ChromeOS

La API de Digital Goods estará disponible en ChromeOS estable a partir de la versión 89. Mientras tanto, puedes 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. El uso de HTTP hará que la API sea undefined.

Con usuarios de prueba y equipos de control de calidad

Play Store proporciona indicaciones visuales para las pruebas, incluidas las cuentas de prueba de los usuarios y los SKU de prueba. Consulta la documentación de prueba de la Facturación Google Play para obtener más información.

¿Adónde ir después?

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.