Receba pagamentos pelo Google Play Faturamento com a API Digital Goods e a API Payment Request

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

Se o app for distribuído pelo Google Play e você quiser vender produtos e softwares digitais ou oferecer assinaturas, use o Google Play Faturamento. O Google Play Faturamento oferece ferramentas para gerenciar seu catálogo, preços e assinaturas, relatórios úteis e um fluxo de finalização de compra com a Play Store e que seus usuários já conhecem.

Para apps criados com Atividades confiáveis na Web e enviados pela Google Play Store, agora você pode usar a API Payment Request e a API Digital Goods para fazer a integração com o Google Play Faturamento. Ele está disponível no Chrome 101 e versões mais recentes para Android e ChromeOS.

Neste guia, você vai aprender a adicionar o suporte do Google Play Faturamento ao seu PWA e empacotá-lo para distribuição na Google Play Store do ChromeOS e da Play Store.

Você vai usar duas APIs da plataforma da Web para adicionar a compatibilidade com o Play Faturamento ao PWA. A API Digital Goods é usada para coletar informações de SKU e verificar compras e direitos da Play Store. A API Payment Request é usada para configurar a Google Play Store como forma de pagamento e concluir o fluxo de compra.

Como gerar receita com apps na Play Store

Existem duas maneiras de o aplicativo gerar receita com o Google Play Faturamento na Play Store:

  • As compras no app permitem a venda de bens virtuais duráveis e consumíveis, como recursos adicionais ou remoção de anúncios.
  • Com as assinaturas, seus usuários têm acesso contínuo a conteúdos ou serviços por uma taxa recorrente, como assinaturas de notícias ou assinaturas.

Requisitos

Para configurar o Google Play Faturamento, você precisará do seguinte:

Atualizar o projeto Bubblewrap

Se você não tiver o Bubblewrap instalado, será necessário instalá-lo. Consulte o Guia de início rápido para ver detalhes sobre como começar. Se você já tem o Bubblewrap, atualize para a versão 1.8.2 ou mais recente.

Essa opção também tem o recurso atrás de uma bandeira. Para ativá-lo, é necessário modificar a configuração do projeto no twa-manifest.json, localizado na raiz do projeto, e ativar alphaDependencies e o recurso playBilling:

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

Com o arquivo de configuração atualizado, execute bubblewrap update para aplicar a configuração ao projeto, seguido por bubblewrap build, para gerar um novo pacote do Android e fazer upload dele para a Play Store.

Recurso que detecta a disponibilidade da API Digital Goods e do Google Play Faturamento

No momento, a API Digital Goods só é compatível com o Chrome quando o PWA está sendo executado dentro de uma Atividade confiável na Web. É possível detectar se ele está disponível verificando getDigitalGoodsService no objeto window:

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

A API Digital Goods pode estar disponível em qualquer navegador e oferecer suporte a diferentes lojas. Para verificar se há suporte para um back-end de armazenamento específico, você precisará invocar getDigitalGoodsService() transmitindo o ID da loja como um parâmetro. A Google Play Store é identificada pela string 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;
  }
}

Recuperar detalhes de uma SKU

A API Digital Goods fornece getDetails(), que permite recuperar informações como o título do produto, a descrição e, o mais importante, o preço, do back-end de pagamentos.

Você pode usar essas informações na interface de uso e fornecer mais detalhes ao usuário:

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);
}

Criar o fluxo de compra

O construtor de uma PaymentRequest usa dois parâmetros: uma lista de formas de pagamento e uma lista de detalhes do pagamento.

Na Atividade confiável na Web, você precisa usar a forma de pagamento do Google Play Faturamento, definindo https://play.google.com/billing como o identificador e adicionando o SKU do produto como um membro de dados:

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

   ...
}

Embora os detalhes de pagamento sejam obrigatórios, o Play Faturamento ignora esses valores e usa os valores definidos ao criar a SKU no Play Console. Assim, eles podem ser preenchidos com valores falsos:

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

const request = new PaymentRequest(paymentMethods, paymentDetails);

Chame show() no objeto da solicitação de pagamento para iniciar o fluxo de pagamento. Se a promessa for bem-sucedida, isso vai indicar que o pagamento foi bem-sucedido. Se ela falhar, é provável que o usuário tenha cancelado o pagamento.

Se a promessa for concluída, você vai precisar verificar e confirmar a compra. Para se proteger contra fraudes, essa etapa precisa ser implementada usando seu back-end. Confira a documentação do Play Faturamento para saber como implementar a verificação no back-end. Se você não confirmar a compra, após três dias, o usuário receberá um reembolso e o Google Play revogará a 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
}
...

Opcionalmente, consume() pode ser chamado em um purchaseToken para marcar a compra como usada e permitir que ela seja comprada novamente.

Para resumir tudo, um método de compra se parece com o seguinte:

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

Verificar o status das compras existentes

A API Digital Goods permite verificar se o usuário tem direitos (compras no app que ainda não foram consumidas ou assinaturas em andamento) de compras anteriores que ele já fez, seja em outro dispositivo, em uma instalação anterior, resgatada usando um código promocional ou apenas na última vez em que abriu o 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}`);
}

Esse também é um bom momento para verificar compras que foram feitas anteriormente, mas não foram confirmadas. É recomendável confirmar as compras o mais rápido possível para garantir que os direitos dos usuários sejam refletidos corretamente no 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}`);
}

Testar sua integração

Em um dispositivo Android de desenvolvimento

É possível ativar a API Digital Goods em um dispositivo Android de desenvolvimento para testes:

  • Verifique se você está usando o Android 9 ou uma versão mais recente com o modo de desenvolvedor ativado.
  • Instale o Chrome 101 ou uma versão mais recente.
  • Ative as sinalizações a seguir no Chrome navegando até chrome://flags e procurando a sinalização pelo nome:
    • #enable-debug-for-store-billing
  • Verifique se o site está hospedado com o uso de um protocolo https. O uso de http fará com que a API seja undefined

Em um dispositivo ChromeOS

A API Digital Goods estará disponível no ChromeOS estável a partir da versão 89. Enquanto isso, é possível testar a API Digital Goods:

  • Instale o app no dispositivo pela Play Store.
  • Verifique se o site está hospedado com o uso de um protocolo https. O uso de http fará com que a API seja undefined

Com usuários de teste e equipes de controle de qualidade

A Play Store oferece affordances para testes, incluindo contas de teste do usuário e SKUs de teste. Confira a documentação de teste do Google Play Faturamento para mais informações.

O que fazer agora?

Conforme discutido neste documento, a API Play Billing tem componentes do lado do cliente, que são gerenciados pela API Digital Goods, e componentes do lado do servidor.