Partilhar via

Fornecer compras via aplicação com a API de Bens Digitais

  • Artigo

Se a sua Aplicação Web Progressiva (PWA) estiver listada na Microsoft Store, pode fornecer produtos e subscrições na aplicação através da API de Bens Digitais e da API de Pedido de Pagamento.

API de Bens Digitais

A API de Bens Digitais é uma interface entre a sua aplicação PWA e a Microsoft Store. A API de Bens Digitais suporta:

  • Consultar os detalhes de um item digital a partir do back-end da Microsoft Store, como o nome, descrição e preço regional do item.
  • Consumir ou reconhecer compras.
  • Verificar os itens digitais que pertencem atualmente ao utilizador.
  • Verificar o histórico de compras do utilizador.

Confira:

API de Pedido de Pagamento

A API de Pedido de Pagamento processa a transação de pagamento real quando uma compra é efetuada por um utilizador. A API de Pedido de Pagamento utiliza os detalhes do item que a API de Bens Digitais fornece, para fazer a compra na aplicação utilizando o método de pagamento de faturação que o utilizador configurou na Microsoft Store.

Confira:

Ativar a API de Bens Digitais

A API de Bens Digitais está atualmente disponível para testes no Microsoft Edge. Para testar a API, utilize uma das seguintes formas:

Os detalhes encontram-se abaixo.

Utilizar um canal de pré-visualização suportado do Microsoft Edge no seu computador dev

Para testar a API de Bens Digitais localmente, antes de implementar a sua aplicação para produção, execute o Edge Dev ou o Edge Canary. Estas versões de pré-visualização do Edge têm a API ativada, como parte de uma experimentação em execução.

Para transferir um canal de pré-visualização (insider) do Microsoft Edge, consulte Tornar-se um Microsoft Edge Insider.

Registe-se na versão de avaliação de origem e, em seguida, utilize o token no seu site

Para testar a API de Bens Digitais em produção, com os seus utilizadores, utilize um token de avaliação de origem. Com esta abordagem, quando os seus utilizadores transferirem o seu PWA a partir da Microsoft Store, terão a API ativada.

Confira:

Verificar se a API de Bens Digitais está disponível

Para detetar se ativou corretamente a API no seu site com o token de avaliação de origem, marcar se o getDigitalGoodsService método existe no window objeto:

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

Veja também:

Ligar ao serviço de Faturação da Microsoft Store (window.getDigitalGoodsService método)

Utilize o getDigitalGoodsService método do window objeto para ligar ao serviço de Faturação da Microsoft Store. É devolvida uma interface DigitalGoodsService .

A API de Bens Digitais foi concebida para ser compatível com vários browsers e lojas digitais, semelhante à forma como a API de Pedido de Pagamento é agnóstica do browser e pode ser utilizada com diferentes fornecedores de pagamentos. Para obter uma instância do serviço para Faturação da Microsoft Store, transmita a cadeia "https://store.microsoft.com/billing" como o método de pagamento para o getDigitalGoodsService método .

Se o método emitir um erro, o método de pagamento de Faturação da Microsoft Store não está disponível (por exemplo, quando o utilizador está a aceder ao seu PWA através do browser). Em alternativa, considere fornecer um método de pagamento diferente para transações.

if (window.getDigitalGoodsService === undefined) {
  // The Digital Goods API isn't supported in this context.
  return;
}
try {
  const digitalGoodsService = await window.getDigitalGoodsService("https://store.microsoft.com/billing");
  // Use the service here.
  ...
} catch (error) {
  // The preferred service provider is not available.
  // Use a web-based payment flow instead.
  return;
}

Este método getDigitalGoodsService("https://store.microsoft.com/billing") de pagamento só está disponível para um PWA instalado a partir da Microsoft Store, no Windows. Não são necessárias outras definições.

Veja também:

Consultar detalhes do item (getDetails método)

Utilize o getDetails método da DigitalGoodsService interface para consultar os detalhes do item.

Depois de ligar o serviço de Bens Digitais à Microsoft Store, pode utilizar a API para aceder a informações de produtos e compras. O getDetails método permite-lhe obter informações sobre os itens que configurou no Centro de Parceiros. Apresentar informações como o título do produto, a descrição e o preço na IU da aplicação, para que o utilizador saiba o que está disponível para compra.

O getDetails método utiliza uma lista de IDs de itens, que correspondem aos IDs de produto dos produtos e subscrições na aplicação que criou no Centro de Parceiros.

const itemDetails = await digitalGoodsService.getDetails(['shiny_sword', 'gem', 'monthly_subscription']);

for (item of itemDetails) {
  const priceStr = new Intl.NumberFormat(
      locale,
      {style: 'currency', currency: item.price.currency}
    ).format(item.price.value);

  // Do something with the item's data, such as displaying it in the PWA's UI.
  displayProductItem(item.itemId, item.title, priceStr, item.description);
}

A sequência devolvida itemDetails pode estar em qualquer ordem e pode não incluir um item se o item não existir no servidor (ou seja, se não existir uma correspondência de 1:1 entre a lista de entrada e a lista de saída).

O ID do item é uma cadeia que representa a chave primária dos itens. Na Microsoft Store, o ID do item é InAppOfferToken. Não existe nenhuma função para obter uma lista de IDs de itens; os IDs de itens devem ser codificados no código de cliente ou obtidos a partir do seu próprio servidor (o servidor do programador).

O item é price um PaymentCurrencyAmount que contém o preço atual do item na região e moeda atuais do utilizador. O price foi concebido para ser formatado para a região atual do utilizador com Intl.NumberFormat, conforme mostrado acima.

Confira também

Especificação da API de Bens Digitais

Desenvolvimento Windows App:

W3C:

MDN:

Comprar um item (PaymentRequest construtor e show método)

Depois de os seus produtos e detalhes serem apresentados ao utilizador, implemente o fluxo de compra com a API de Pedido de Pagamento. Para comprar um item, crie primeiro um pedido que contenha os detalhes do item com o PaymentRequest construtor e, em seguida, utilize o show método do PaymentRequest objeto para iniciar o fluxo de pagamento.

Quando combinado com a API de Bens Digitais, o único parâmetro de entrada necessário para o PaymentRequest construtor é methodData. No parâmetro do construtor:

  • supportedMethods No membro, especifique a Faturação da Microsoft Store como método de pagamento, como a cadeia 'https://store.microsoft.com/billing'.
  • data No membro, passe o itemId como .sku
const details = await digitalGoodsService.getDetails(['monthly_subscription']);
const item = details[0];

const request = new PaymentRequest([
  {
    supportedMethods: 'https://store.microsoft.com/billing',
    data: { sku: item.itemId }
  }
]);

Em seguida, chame o show método do PaymentRequest objeto para iniciar o fluxo de pagamento:

const response = await request.show();

Esta ação apresenta a IU de compra da Loja ao utilizador, onde o utilizador pode ver detalhes sobre o produto que está a tentar comprar. Durante este processo, a sessão atual do browser é temporariamente desativada até que o fluxo de compra esteja concluído. O utilizador pode cancelar a transação ou prosseguir com o pagamento:

  • Se o utilizador cancelar o pagamento, a Promessa devolvida pelo show método será rejeitada com um erro.

  • Se o utilizador pagar com êxito e concluir a compra, a Promessa resolve com um PaymentResponse. details Na propriedade da resposta de pagamento, é devolvido um token de compra.

Veja também:

Consumir uma compra (consume método)

Utilize o consume método da DigitalGoodsService interface para consumir uma compra.

Uma compra consumível é uma compra concebida para ser comprada várias vezes. Normalmente, uma compra consumível tem de ser marcada como "consumida" antes de a compra poder ser comprada novamente pelo utilizador. Um exemplo de uma compra consumível é um powerup no jogo que torna o jogador mais forte por um curto período de tempo.

Para marcar uma compra como "consumida", utilize o consume método :

digitalGoodsService.consume(purchaseToken);

Veja também:

Verificar compras existentes (listPurchases método)

Utilize o listPurchases método da DigitalGoodsService interface para marcar compras existentes. Este método devolve informações sobre as compras existentes do utilizador. Este método permite que um cliente obtenha uma lista de itens que são atualmente propriedade ou comprados pelo utilizador. Isto pode ser necessário, para efetuar um dos seguintes procedimentos:

  • Verifique se existem elegibilidades, como se uma subscrição, código promocional ou atualização permanente está ativa.

  • Recupere de interrupções de rede durante uma compra, como quando o item é comprado, mas ainda não é reconhecido.

O listPurchases método devolve IDs de itens e tokens de compra. Antes de conceder uma elegibilidade, deve verificar o ID do item devolvido ou o token de compra devolvido, utilizando uma API direta de programador para fornecedor, conforme mostrado abaixo:

const purchaseList = await digitalGoodsService.listPurchases();

for (const purchase of purchaseList) {
  // Handle the purchase data in your PWA.
  verifyAndGrantEntitlement(purchase.itemId, purchase.purchaseToken);
}

O listPurchases método não devolve produtos consumidos ou subscrições expiradas.

Veja também:

Obter o histórico de compras (listPurchaseHistory método)

Utilize o listPurchaseHistory método da DigitalGoodsService interface para obter o histórico de compras.

Este método devolve uma lista de PurchaseDetails que contém e purchaseTokenitemId para cada compra. A lista inclui a compra mais recente efetuada pelo utilizador para cada item, independentemente de a compra ter expirado, cancelado ou consumido.

const purchaseList = await digitalGoodsService.listPurchaseHistory();

for (const purchase of purchaseList) {
  // Handle the expired purchase data in your PWA.
  verifyAndCheckExpiredEntitlement(purchase.itemId, purchase.purchaseToken);
}

Veja também:

Confira também

Avaliações de origem:

GitHub:

MDN:

W3C:

Desenvolvimento Windows App: