Fornecer compras no aplicativo com a API de Produtos Digitais

Se o PWA (Aplicativo Web Progressivo) estiver listado na Microsoft Store, você poderá fornecer assinaturas e produtos no aplicativo usando a API de Produtos Digitais e a API de Solicitação de Pagamento.

API de Bens Digitais

A API de Produtos Digitais é uma interface entre seu aplicativo PWA e a Microsoft Store. A API de Produtos Digitais dá suporte a:

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

Confira:

API da Solicitação de Pagamento

A API de Solicitação de Pagamento lida com a transação de pagamento real quando uma compra é feita por um usuário. A API de Solicitação de Pagamento usa os detalhes do item que a API de Produtos Digitais fornece para fazer a compra no aplicativo usando qualquer forma de pagamento de cobrança que o usuário configurou na Microsoft Store.

Confira:

Habilitar a API de Produtos Digitais

No momento, a API de Produtos Digitais está disponível para todos os canais no Microsoft Edge. Para testar a API, verifique se sua versão do Edge é 134.0.3124.51 ou superior.

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

Para detectar se você tem acesso à API em seu site, 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:

Conectando-se ao serviço de Cobrança da Microsoft Store (window.getDigitalGoodsService método)

Use o getDigitalGoodsServicewindow método do objeto para se conectar ao serviço de Cobrança da Microsoft Store. Uma interface DigitalGoodsService é retornada.

A API de produtos digitais foi projetada para ser compatível com vários navegadores e lojas digitais, semelhante à forma como a API de solicitação de pagamento é independente do navegador e pode ser usada com diferentes provedores de pagamento. Para recuperar uma instância do serviço de cobrança da Microsoft Store, passe a cadeia de caracteres "https://store.microsoft.com/billing" como a forma de pagamento para o getDigitalGoodsService método.

Se o método gerar um erro, a forma de pagamento de cobrança da Microsoft Store não estará disponível (por exemplo, quando o usuário estiver acessando seu PWA pelo navegador). Como alternativa, considere fornecer uma forma 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;
}

Esta forma getDigitalGoodsService("https://store.microsoft.com/billing") de pagamento está disponível apenas para um PWA instalado da Microsoft Store, no Windows. Nenhuma outra configuração é necessária.

Veja também:

Consultando detalhes do item (getDetails método)

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

Depois de conectar o serviço de Produtos Digitais à Microsoft Store, você poderá usar a API para acessar informações sobre produtos e compras. O getDetails método permite obter informações sobre os itens configurados no Partner Center. Exiba informações como título, descrição e preço do produto na interface do usuário do aplicativo, para que o usuário saiba o que está disponível para compra.

O getDetails método usa uma lista de IDs de item, que correspondem às IDs de produto dos produtos no aplicativo e assinaturas que você criou no Partner Center.

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 retornada 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 houver uma correspondência 1:1 entre a lista de entrada e a lista de saída).

A ID do item é uma cadeia de caracteres que representa a chave primária dos itens. Na Microsoft Store, a ID do item é InAppOfferToken. Não há função para obter uma lista de IDs de item; As IDs de item devem ser codificadas no código do cliente ou buscadas em seu próprio servidor (o servidor do desenvolvedor).

O item price é um PaymentCurrencyAmount que contém o preço atual do item na região e moeda atuais do usuário. O price foi projetado para ser formatado para a localidade atual do usuário usando Intl.NumberFormat, como mostrado acima.

Confira também

Especificação da API de bens digitais

Desenvolvimento de aplicativos do Windows App:

W3C:

MDN:

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

Depois que seus produtos e detalhes forem exibidos para o usuário, implemente o fluxo de compra usando a API de Solicitação de Pagamento. Para comprar um item, primeiro construa uma solicitação que contenha os detalhes do item usando o PaymentRequest construtor e, em seguida, use o showPaymentRequest método do 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:

  • No membro, especifique Cobrança da supportedMethods Microsoft Store como a forma de pagamento, como a cadeia de caracteres 'https://store.microsoft.com/billing'.
  • data No membro, passe o itemId como o 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 showPaymentRequest método do objeto para iniciar o fluxo de pagamento:

const response = await request.show();

Isso exibe a interface do usuário de compra da Store para o usuário, onde o usuário pode exibir detalhes sobre o produto que está tentando comprar. Durante esse processo, a sessão atual do navegador é temporariamente desabilitada até que o fluxo de compra seja concluído. O usuário pode cancelar a transação ou prosseguir com o pagamento:

  • Se o usuário cancelar o pagamento, a promessa retornada pelo show método será rejeitada com um erro.

  • Se o usuário pagar com sucesso e concluir a compra, a promessa será resolvida com um PaymentResponse. details Na propriedade da resposta de pagamento, um token de compra é retornado.

Veja também:

Consumindo uma compra (consume método)

Use o consumeDigitalGoodsService método da interface para consumir uma compra.

Uma compra de consumível é uma compra projetada para ser comprada várias vezes. Uma compra consumível geralmente precisa ser marcada como "consumida" antes que a compra possa ser comprada novamente pelo usuário. Um exemplo de compra de consumível é um power-up no jogo que torna o jogador mais forte por um curto período de tempo.

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

digitalGoodsService.consume(purchaseToken);

Veja também:

  • consume() da DigitalGoodsService interface.

Verificando compras existentes (listPurchases método)

Use o listPurchasesDigitalGoodsService método da interface para marcar compras existentes. Esse método retorna informações sobre as compras existentes do usuário. Esse método permite que um cliente obtenha uma lista de itens que atualmente pertencem ao usuário ou que foram comprados pelo usuário. Isso pode ser necessário para seguir um destes procedimentos:

  • Verifique se há direitos, como se uma assinatura, código promocional ou atualização permanente está ativo.

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

O listPurchases método retorna IDs de item e tokens de compra. Antes de conceder um direito, você deve verificar a ID do item retornado ou o token de compra retornado, usando uma API direta de desenvolvedor para provedor, 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 retorna produtos consumidos ou assinaturas expiradas.

Veja também:

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

Use o listPurchaseHistoryDigitalGoodsService método da interface para obter o histórico de compras.

Esse método retorna uma lista de PurchaseDetails contendo o itemId e purchaseToken para cada compra. A lista inclui a compra mais recente feita pelo usuário para cada item, independentemente de a compra ter expirado, sido cancelada ou consumida.

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

GitHub:

MDN:

W3C:

Desenvolvimento de aplicativos do Windows App:

  • Last updated on