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 ou ofertas digitais 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 tecnologia do Google Play Loja que os usuários já conhecem.

Para apps criados com Atividades confiáveis na Web e fornecidos pela Google Play Store, você agora podem usar a API Payment Request e a API Digital Goods para integraçã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 do Google Play Faturamento ao seu PWA e empacotá-lo para na Google Play Store para o ChromeOS e a Play Store.

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

Como gerar receita com apps 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 outros ou remover 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 a Guia de início rápido para conferir detalhes sobre como começar. Se você já tem o protetor de bolhas, atualize para a versão 1.8.2 ou superior.

O bolhas também tem o recurso por trás de uma sinalização. Em para ativá-lo, você terá que modificar a configuração do projeto em twa-manifest.json, localizados na raiz do projeto e ative alphaDependencies e playBilling Atributo:

  ...,
  "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 deste 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 em um Atividade na Web Confiável e é possível detectar se ela 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 verifique se um back-end de armazenamento específico é compatível, você vai 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, descrição e, mais importante, 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 acessar a 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 ignorará esses valores e usará o definidos na criação da SKU no Play Console para que 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 da solicitação de pagamento para iniciar o fluxo de pagamento. Se a promessa for bem-sucedida o pagamento foi bem-sucedido. Em caso de falha, é provável que o usuário tenha cancelado 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 o 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 sejam comprados novamente.

Juntando tudo, um método de compra é semelhante ao 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 de compras existentes

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

Também é um bom momento para verificar compras que foram feitas anteriormente, mas não foram confirmadas. Recomendamos confirmar as compras o mais rápido possível para garantir que direitos sejam refletidas de modo adequado 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 de produtos e softwares digitais 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 mais recente.
  • Para ativar as seguintes sinalizações no Chrome, acesse chrome://flags e pesquise o sinalizar 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. Na Enquanto isso, é possível testar a API de produtos e softwares digitais:

  • Instale o app pela Play Store no dispositivo.
  • 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 tem affordances para testes, incluindo contas e SKUs de teste de usuários. Consulte a documentação do teste do Google Play Faturamento para mais informações.

O que fazer em seguida?

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