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

André Cipriani Bandarra

Se o app for distribuído pelo Google Play e você quiser vender produtos 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 base na Play Store que já é familiar para seus usuários.

Para apps criados usando Atividades da Web confiáveis e distribuídos pela Google Play Store, agora é possível usar a API Payment Request e a API Digital Goods para fazer a integração com o Google Play Faturamento. Ela está disponível no Chrome 101 e versões mais recentes para Android e ChromeOS.

Neste guia, você vai aprender a adicionar o suporte ao Google Play Faturamento ao seu PWA e empacotar para distribuição na Google Play Store para ChromeOS e Play Store.

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

Como gerar receita com aplicativos na Play Store

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

  • As compras no app permitem vender bens virtuais duráveis e consumíveis, como recursos adicionais ou a 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á de:

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á tiver o Bubblewrap, atualize para a versão 1.8.2 ou mais recente.

O Bubblewrap também tem o recurso atrás de uma flag. Para ativá-lo, modifique a configuração do projeto no twa-manifest.json, localizado na raiz do projeto, e ative o 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 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 a PWA está sendo executada em uma Trusted Web Activity. É possível detectar se ela está disponível verificando se getDigitalGoodsService está 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 um back-end de loja específico é compatível, é necessário 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 oferece getDetails(), que permite recuperar informações como o título do produto, a descrição e, mais importante, o preço do back-end de pagamentos.

Você pode então usar essas informações em sua 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 de pagamento.

Ao entrar na Atividade na Web confiável, você precisa usar a forma de pagamento do Google Play Faturamento, definindo https://play.google.com/billing como o identificador e adicionando a 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,
       }
   }];

   ...
}

Mesmo que os detalhes de pagamento sejam obrigatórios, o Play Faturamento vai ignorar esses valores e usar os valores definidos ao criar a SKU no Play Console para que eles possam 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 de solicitação de pagamento para iniciar o fluxo de pagamento. Se a promessa for bem-sucedida, o pagamento será concluído. Se falhar, é provável que o usuário tenha abortado o pagamento.

Se a promessa for bem-sucedida, você vai precisar verificar e confirmar a compra. Para se proteger contra fraudes, essa etapa precisa ser implementada usando seu back-end. Consulte 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 vai receber um reembolso e o Google Play vai 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.

Juntando tudo, um método de compra tem a seguinte aparência:

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 de 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 feitas, seja em outro dispositivo, de uma instalação anterior, resgatadas de um código promocional ou apenas da última vez que o app foi aberto.


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:

  • Confira se você está usando o Android 9 ou uma versão mais recente com o modo de desenvolvedor ativado.
  • Instale o Chrome 101 ou mais recente.
  • Para ativar as seguintes sinalizações no Chrome, acesse chrome://flags e pesquise a sinalização pelo nome:
    • #enable-debug-for-store-billing
  • Verifique se o site está hospedado usando um protocolo https. O uso de http vai fazer 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 na Play Store no dispositivo.
  • Verifique se o site está hospedado usando 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 recursos para testes, incluindo contas de teste de usuários e SKUs de teste. Confira a documentação de teste do Google Play Faturamento para mais informações.

Para onde vamos agora?

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