Implementar o Google Play Faturamento no seu PWA

Se o PWA estiver listado no Google Play e você quiser gerar receita com ele vendendo produtos ou assinaturas no app, a política do Google Play vai exigir que você implemente o Play Faturamento. Há duas APIs que você precisa implementar no seu PWA: a API Digital Goods e a API Payment Request.

API Digital Goods

A API Digital Goods é uma interface entre seu app e o Google Play. Ele permite recuperar os produtos digitais e os detalhes que você inseriu para produtos no app e assinaturas no Play Console, além de compras feitas por um usuário. Se você ainda não adicionou produtos no app ou assinaturas no Play Console, siga a configuração do Play Console para o Google Play Faturamento.

Em 30 de novembro de 2021, o ChromeOS 96 foi lançado com a implementação da API Digital Goods 2.0.

O teste de origem da primeira versão da API Digital Goods terminou em 30 de janeiro de 2022. Por isso, ela foi descontinuada, e apenas a v2 da API está disponível.

Em 23 de junho de 2022, o ChromeOS 103 foi lançado com a implementação da API Digital Goods 2.1. Esta versão não tem mudanças significativas e inclui apenas novos métodos e campos adicionais: listPurchaseHistory() e itemType.

Inscrever-se no teste de origem

Observação:no momento, a API Digital Goods está disponível por um teste de origem, um mecanismo que permite aos desenvolvedores acesso antecipado a novas APIs da Web. Você precisará se registrar no teste de origem da API Digital Goods v2 e solicitar um token, que precisará ser fornecido em todas as páginas da sua origem.

Ao se registrar para o teste de origem, você vai ver uma data "Válida até", que é quando seu token tem garantia de funcionamento. Não se esqueça de renovar seus tokens quando a data se aproximar para continuar participando do teste. As APIs oferecidas como teste de origem estão sujeitas a mudanças. Por isso, fique por dentro das atualizações mais recentes de qualquer teste de origem em que você esteja participando. Em caso de problemas, consulte a documentação da API Digital Goods.

API Payment Request

A API Payment Request processa a transação de pagamento real quando uma compra é feita. Ela usa os detalhes do item fornecidos pela API Digital Goods para fazer a compra no app com a forma de pagamento adequada, que, no nosso caso, é o Google Play Faturamento.

Detectar recursos da API Digital Goods

Para detectar se você ativou corretamente a API no seu site pela origem do teste, verifique o método getDigitalGoodsService no objeto window.

if ('getDigitalGoodsService' in window) {
  // Digital Goods API is supported!
} else {
  console.log('DigitalGoodsService is not available.');
  // Use another payment method
}

Conectar-se ao serviço do Google Play Faturamento

A API Digital Goods foi projetada para ser compatível com vários navegadores e lojas digitais, assim como a API Payment Request é independente de navegador e pode ser usada com diferentes provedores de pagamento. Para receber uma instância do serviço associado ao Google Play Faturamento, transmita a string "https://play.google.com/billing" como a forma de pagamento para getDigitalGoodsService().

Se o método gerar um erro, a forma de pagamento do Google Play Faturamento não estará disponível (por exemplo, o usuário está acessando seu PWA pelo navegador). Em vez disso, ofereça outra forma de pagamento para transações.

if ('getDigitalGoodsService' in window) {
  // Digital Goods API is supported!
  try {
    const service = await window.getDigitalGoodsService('https://play.google.com/billing');
    // Google Play Billing service is available
  } catch (error) {
    // Google Play Billing service is not available. Use another payment flow.
  }
}

Receber detalhes do item

Depois de conectar o serviço de produtos digitais ao Google Play, você pode usar a API para recuperar informações sobre produtos e compras.

O método getDetails() permite que você receba informações sobre os itens configurados no Play Console. Informações como título, descrição e preço do produto precisam ser mostradas ao usuário na interface do app para que ele saiba o que está disponível para compra e por quanto.

O método getDetails() precisa de uma lista de IDs de itens que correspondem aos IDs de produtos no app e assinaturas criadas no Play Console.

const itemDetails = await service.getDetails(['product_1', 'product_2', 'product_3']);
for (const item of itemDetails) {
  // Display item information to user
  displayItem(item.title, item.description, item.price);
}

Para receber o preço adequado à localidade do usuário, você precisa fazer mais algumas formatações:

const localePrice = new Intl.NumberFormat(navigator.language, {
  style: 'currency',
  currency: item.price.currency,
}).format(item.price.value);

Observação:a API Digital Goods não oferece um método para receber uma lista de IDs de itens. Em vez disso, você precisa codificá-los no cliente ou buscá-los no servidor de back-end. A API Google Play Developer permite consultar a lista de IDs de itens de um back-end. Saiba mais sobre como implementar os principais componentes do Google Play Faturamento no seu servidor de back-end. Seja qual for a solução escolhida, mantenha os IDs dos itens consistentes com o que você tem no Play Console.

Na v2.1 da API, um dos campos retornados por getDetails() é itemType. É uma enumeração em que o valor é ”product” ou ”subscription” para indicar se o item correspondente é um produto no app ou uma assinatura, respectivamente. Diferenciar os dois tipos de produtos pode ser útil se você precisar aplicar tratamentos diferentes a cada tipo. Por exemplo, você pode ter uma página específica para os usuários se inscreverem e outra para os outros produtos que não são por assinatura. Também é útil para saber o recurso REST da API Google Play Developer adequado para usar no seu back-end (purchases.products ou purchases.subscriptions).

Comprar um item

Depois que os produtos e detalhes forem mostrados ao usuário, você poderá criar o fluxo de compra com a API Payment Request. Quando usada com a API Digital Goods, apenas um parâmetro de entrada é necessário: methodData.

O Play Faturamento permite apenas a compra de um item por vez. O preço e os detalhes do item já são conhecidos pelo servidor do Google Play, então o parâmetro details não é necessário. Consulte a explicação para mais detalhes.

Use o membro supportedMethods do parâmetro methodData no PaymentRequest para identificar o Google Play Faturamento como a forma de pagamento com a string "https://play.google.com/billing". Em seguida, no membro data, transmita o ID do item como sku.

const paymentMethodData = [
  {
    supportedMethods: 'https://play.google.com/billing',
    data: {
      sku: item.itemId,
    },
  },
];

Em seguida, crie a solicitação de pagamento e chame show() para iniciar o fluxo de pagamento:

const request = new PaymentRequest(paymentMethodData);
const paymentResponse = await request.show();

Isso vai mostrar a interface de compra do Google Play para o usuário, onde ele vai ver os detalhes sobre o produto que está tentando comprar. Eles podem abandonar a transação ou continuar com o pagamento. Se o usuário cancelar o pagamento, a promessa retornada por show() será rejeitada com um erro. Se o pagamento for feito e a compra concluída, a promessa será resolvida com um PaymentResponse. Na propriedade details da resposta de pagamento, um token de compra é retornado.

Para evitar fraudes, é fundamental verificar a compra e o token de compra no servidor de back-end. Também é uma boa ideia acompanhar os usuários e os tokens de compra associados a eles. Saiba como implementar a verificação no servidor de back-end.

Depois de validar a compra, chame complete() na resposta de pagamento para concluir o fluxo de pagamento e fechar a interface de faturamento. Também é possível transmitir uma string result opcional para indicar o estado do processo de pagamento. Cabe ao navegador indicar ou não esse resultado ao usuário. O Chrome não cria dicas visíveis para o usuário. Por isso, recomendamos que você mostre suas próprias mensagens de erro ou sucesso no PWA.

/* Changes were recently made so that the PaymentResponse `details` property returns the purchase token as `purchaseToken` instead of `token`. Note that `token` will be deprecated at some point in the future. To ensure that your app won't be affected by this, make the change to `purchaseToken` in your client code and use the latest version of Bubblewrap (v1.13.5 and later) to update and generate a new app package to upload to the Play Console. */
const { purchaseToken } = paymentResponse.details;

let paymentComplete;
if (validatePurchaseOnBackend(purchaseToken)) {
  paymentComplete = await paymentResponse.complete('success');
  // Let user know their purchase transaction has successfully completed and been verified
} else {
  paymentComplete = await paymentResponse.complete('fail');
  // Let user know their purchase transaction failed to verify
}

Upgrades e downgrades de assinaturas

Esse fluxo de compra é o mesmo para produtos no app e assinaturas. No entanto, para assinaturas, o Google Play tem outras opções de compra que você pode implementar: upgrade e downgrade. Ao criar o data para a forma de pagamento, você precisará transmitir o seguinte para iniciar um fluxo de upgrade ou downgrade:

  • sku: o ID do item da nova assinatura para fazer upgrade ou downgrade.
  • oldSku: o ID do item da assinatura atual do usuário.
  • purchaseToken: o token de compra da assinatura atual do usuário. Como observado anteriormente, é uma boa ideia acompanhar os tokens de compra no back-end. Para esse e outros cenários, você também precisa associar um usuário às compras e aos tokens de compra atuais.
  • prorationMode: é assim que a nova assinatura será cobrada quando substituir a assinatura atual do usuário.
Modo de cálculo proporcional Descrição

immediateAndChargeProratedPrice

A assinatura recebe upgrade imediatamente, e o ciclo de faturamento permanece o mesmo. A diferença de preço referente ao período restante é cobrada do usuário.

immediateAndChargeFullPrice

O upgrade ou downgrade da assinatura é feito e o usuário recebe a cobrança imediata do preço total pela nova titularidade. O valor restante da assinatura anterior é calculado de modo proporcional ao tempo da nova assinatura. Esse modo de rateio foi adicionado recentemente na versão 4.0 da Biblioteca Google Play Faturamento. Agora ele está disponível no Bubblewrap a partir da versão 1.13.5.

immediateWithoutProration

DESATIVADO TEMPORARIAMENTE: há um possível caminho de fraude com esse modo de rateio em que os usuários podem receber uma assinatura atualizada sem pagamento extra por um ciclo de faturamento. Desativamos temporariamente esse modo enquanto trabalhamos na correção.

immediateWithTimeProration

A assinatura recebe upgrade ou downgrade imediatamente. Qualquer tempo restante é ajustado com base na diferença de preço e creditado à nova assinatura, adiando a próxima data de faturamento. Esse é o comportamento padrão.

deferred

A assinatura só recebe upgrade ou downgrade quando ela é renovada. Isso é útil principalmente para downgrades.

unknownSubscriptionUpgradeDowngradePolicy

Nenhuma política definida. Isso não é recomendado.

Saiba mais sobre os diferentes modos de rateio na documentação de referência da Biblioteca Google Play Faturamento. Confira a documentação para desenvolvedores Android para saber mais sobre upgrades e downgrades de assinaturas e recomendações de modo de rateio.

O uso desses campos adicionais será parecido com isto:

const paymentMethod = [
  {
    supportedMethods: 'https://play.google.com/billing',
    data: {
      sku: item.itemId,
      oldSku: oldPurchase.itemId,
      purchaseToken: oldPurchase.purchaseToken,
      prorationMode: 'immediateAndChargeProratedPrice',
    },
  },
];

Aqui, item é o ItemDetails da nova assinatura para a qual o usuário está tentando fazer upgrade ou downgrade, e oldPurchase é o PurchaseDetails da assinatura atual do usuário.

Confirmar uma compra

Depois que um usuário compra um item, você precisa conceder a ele os direitos adequados (acesso ao item ou conteúdo que ele acabou de comprar). Em seguida, confirme a compra. Ao confirmar uma compra, você informa ao Google Play que recebeu e processou a compra corretamente.

Observação:se uma compra não for confirmada em até 72 horas após a compra, o pagamento será reembolsado ao usuário e a compra será revogada. O token de compra não será mais válido. Portanto, quando você consultar as compras atuais, a compra revogada não será retornada. Isso garante que um usuário não seja cobrado indevidamente em caso de um erro de rede que o impeça de receber o direito ao item.

Confirme as compras no servidor de back-end usando a API Google Play Developer. Recomendamos conceder direitos e confirmar a compra juntos no servidor de back-end.

  1. Depois que um usuário faz uma compra no lado do cliente, envie o token de compra e o ID do item em uma solicitação ao servidor de back-end.
  2. No back-end, para receber detalhes sobre a compra e verificar, chame:
  3. Conceda o direito adequado no banco de dados de back-end.
  4. Em seguida, confirme a compra chamando:

Consumir uma compra

Ao confirmar uma compra, você informa ao Google Play que o usuário agora é proprietário do item e não pode comprá-lo novamente. Se for um item que o usuário só precisa comprar uma vez e que será dele para sempre (por exemplo, uma skin de personagem de jogo), ele não é consumível.

Como alternativa, o item pode ser algo que você limita a um usuário por vez. Em seguida, o usuário precisa usar o item antes de comprar outro. Quando o usuário "usar" o item, chame o método consume() para informar ao Google Play que ele foi consumido. O Google Play vai disponibilizar o item para que o usuário possa comprar de novo.

Para itens que permitem que um usuário tenha vários, eles precisam poder ser comprados repetidamente sem precisar ser usados primeiro (chamamos esses itens de repetíveis). Da mesma forma, esses itens precisam ser "consumidos" antes que o Google Play permita que o usuário compre novamente. Portanto, mesmo que o usuário ainda não tenha usado o item, é necessário chamar o método consume() para marcar o item como consumido.

// After the user purchases the item, send the purchase token and item ID to your backend to grant the entitlement and acknowledge it right away

. . .
// When the user uses the item or if it is a repeatable item, consume it so it’s available for purchase again.
service.consume(purchaseToken);
}

Verificar compras

O último fluxo de usuário principal é verificar as compras atuais (produtos no app que ainda não foram consumidos e assinaturas em andamento) para informar aos usuários quais assinaturas ou itens eles têm. Essas compras foram feitas no Google Play em qualquer dispositivo, no app ou na Play Store. As compras feitas fora do app na Play Store são chamadas de compras fora do app.

Ao recuperar compras atuais, verifique também o status de confirmação e confirme as compras feitas anteriormente, mas que não foram confirmadas corretamente. Recomendamos que as compras sejam confirmadas o mais rápido possível para que os direitos do usuário estejam atualizados e sejam refletidos corretamente no app.

O método listPurchases() da API Digital Goods vai retornar uma lista de PurchaseDetails que contém o itemId e o purchaseToken para cada uma das compras. Você precisará usar a API Google Play Developer no servidor de back-end para verificar o estado das compras e confirmá-las adequadamente. O que você terá aprendido:

  1. Chame o método listPurchases() da API Digital Goods no lado do cliente para recuperar a lista de compras do usuário.
  2. Para cada compra, transmita o purchaseToken e o itemId ao seu back-end.
  3. Se for o caso, conceda o direito no banco de dados de back-end.
  4. Em seguida, chame:e verifique o acknowledgementState.
  5. Se o valor for 0 (ainda não confirmado), chame:

Saiba mais sobre como verificar compras no servidor de back-end antes de conceder direitos.

Histórico de compras

Embora listPurchases retorne informações sobre as compras atuais do usuário, o método listPurchaseHistory() (na v2.1 da API) retorna a compra mais recente feita pelo usuário para cada item, independente de a compra estar expirada, cancelada ou consumida. O método listPurchaseHistory() retorna uma lista de PurchaseDetails contendo o itemId e o purchaseToken de cada compra. Você precisará usar isso com a API Google Play Developer no seu servidor de back-end para recuperar mais informações.

Compras fora do app

As compras fora do app são aquelas que não são feitas no fluxo normal de compras no app. Essas ações geralmente ocorrem na Play Store, e não no app. Há duas maneiras principais de os usuários fazerem uma compra fora do app:

  • Resgatar um código promocional: no menu do usuário da Play Store, em Ofertas e notificações > Resgatar código promocional ou em Pagamentos e assinaturas > Resgatar código vale-presente.
  • Renovação da assinatura: no menu do usuário da Play Store, em Pagamentos e assinaturas -> Assinaturas. Aqui, os usuários podem gerenciar todas as assinaturas em diferentes apps. Para assinaturas expiradas ou canceladas, os usuários têm a opção de "Assinar novamente".

Quando os usuários reativam a assinatura na Play Store, as compras não são confirmadas automaticamente, o que pode resultar em um reembolso. Esse comportamento é intencional, porque os usuários só devem receber cobranças pela assinatura se abrirem o app para usar. O usuário pode ver uma mensagem "Confirmar assinatura" como esta, lembrando de abrir o app.

Os usuários precisam abrir o app para confirmar a compra e a assinatura.

É responsabilidade do desenvolvedor implementar o reconhecimento dessas compras quando o usuário inicia o app. Por isso, recomendamos verificar as compras atuais (geralmente quando o app é iniciado pela primeira vez) e reconhecer as compras que ainda não foram reconhecidas.

Permitir que os usuários gerenciem assinaturas

Para uma boa experiência do usuário, é importante oferecer uma maneira para que os usuários gerenciem e cancelem as assinaturas no app. Recomendamos criar um link direto em uma página ou menu de configurações que redirecione o usuário para a página de gerenciamento de assinaturas do app na Play Store. Substitua o URL a seguir pelo "sub-product-id" e "app-package-name" adequados:

https://play.google.com/store/account/subscriptions?sku=sub-product-id&package=app-package-name

Próximas etapas

Esses fluxos de usuários e snippets de código são uma implementação básica para demonstrar como usar a API Digital Goods e a API Payment Request no seu PWA para implementar o Google Play Faturamento. Use as APIs conforme fizer sentido no contexto e nos casos de uso do seu app. Para conferir um exemplo de implementação completa, consulte nossa amostra de código aberto.

Em seguida, confira como implementar componentes cruciais do Google Play Faturamento no servidor de back-end para manter seu app seguro e sempre atualizado com os direitos do usuário.