Limitação da sandbox: ao consumir produtos consumíveis gerenciados pelo desenvolvedor em uma sandbox de desenvolvimento, somente a autenticação por token XSTS tem suporte. A autenticação por User Store ID ou Microsoft Entra ID não funciona para chamadas de consumo de Dev-Managed Consumable em ambientes de sandbox. Planeje seus testes de acordo. Para obter mais informações, confira a seção Pré-requisitos da API Consume.
Utilizando a biblioteca .NET Microsoft.StoreServices e o exemplo
Para ajudar a demonstrar os princípios e fluxos descritos neste artigo, revise o Microsoft.StoreServices Sample, que fornece:- Uso da biblioteca Microsoft.StoreServices para gerenciar a autenticação e fazer as chamadas aos Microsoft Store Services.
- Lógica de exemplo para gerenciar produtos consumíveis, acompanhar solicitações de consumo pendentes, reconciliar compras reembolsadas, renovar User Store IDs expiradas e muito mais.
- Um guia de configuração que inclui as etapas deste artigo sobre como configurar o seu Microsoft Entra ID para esse método de autenticação.
- Microsoft.StoreServices (GitHub)
- Microsoft.StoreServices Sample (GitHub)
Gerenciando consumíveis
Estrutura recomendada de um serviço de gerenciamento de consumíveis
Use um único fluxo de servidor para validar a propriedade, atender o uso e reconciliar reembolsos. A estrutura a seguir mantém essas responsabilidades explícitas e seguras para novas tentativas.Gerenciando o saldo do usuário no seu serviço vs. na Microsoft Store
Os produtos consumíveis gerenciados pela loja podem ser totalmente gerenciados no serviço do seu jogo consumindo qualquer saldo diferente de zero da Microsoft Store. Como alternativa, o saldo de consumíveis do usuário pode ser gerenciado pela Microsoft Store, consumindo a quantidade somente quando usada para itens no jogo. Os produtos consumíveis gerenciados pelo desenvolvedor, no entanto, exigem gerenciamento em um serviço de jogo. Confira Escolhendo o tipo de produto certo para obter mais informações sobre consumíveis gerenciados pelo desenvolvedor vs. gerenciados pela Microsoft Store. A abordagem mais comum é acompanhar o saldo efetivo de moeda do usuário no seu serviço. Nesse design, seu serviço consulta saldos de consumíveis diferentes de zero, os consome e credita o valor equivalente em moeda do jogo na conta do usuário. Esse fluxo reduz chamadas repetidas à API da Store após o atendimento, simplifica o tratamento de saldos multiplataforma e oferece às equipes de suporte um sistema central para ajustes de saldo. Configuração típica: configure cada nível de moeda como um consumível gerenciado pela loja separado que concede a quantidade1 por compra e, em seguida, mapeie cada produto para seu valor no jogo. Exemplo: um consumível de “500 moedas” aumenta a quantidade na Store para 1; após o consumo, a quantidade na Store volta para 0 e seu serviço credita 500 moedas.
Os consumíveis gerenciados pela loja podem conceder o valor total diretamente à quantidade na Store no momento da compra (por exemplo, 500 por compra). Nesse modelo, a Store acompanha o crescimento do saldo e seu serviço deduz a quantidade quando os usuários gastam moeda no jogo. No entanto, colocar todos os níveis como SKUs em uma única ID de produto limita recursos como preços promocionais específicos por nível e tokens de resgate 5x5. Confira Práticas recomendadas para oferecer moeda do jogo.
Usar TrackingIds como um sistema redundante para validação de consumo
Inclua umaTrackingId em cada solicitação de consumo. Se uma resposta for perdida, repita com a mesma TrackingId, usuário, productId e quantidade para confirmar se o consumo original foi bem-sucedido. Essa nova tentativa evita concessões duplicadas e ainda permite repetições seguras.
O fluxo a seguir mostra um padrão de consumo seguro para novas tentativas.
O Produto A (500 moedas do jogo) é um consumível configurado para conceder uma quantidade de 1 na loja.
- O usuário compra o Produto A e agora tem uma quantidade de
1do produto ao chamar o serviço de consulta. - O serviço do jogo consulta o saldo de consumíveis do usuário na API de consulta da Microsoft Store e vê que o saldo do usuário é
1. - O serviço do jogo gera uma TrackingID, cria uma solicitação de consumo para consumir uma quantidade do produto e adiciona as informações da solicitação a uma lista de transações pendentes.
- O serviço do jogo envia a solicitação para a API de consumo da Microsoft Store.
- O serviço do jogo não recebe uma resposta da API de consumo (perda de pacotes de rede, interrupção do serviço, queda de energia e assim por diante). Nesse ponto, o serviço não consegue confirmar se a transação foi concluída. Consultar apenas o inventário pode ser ambíguo se o usuário tiver comprado novamente durante a interrupção. Use a lista de transações pendentes e repita com os mesmos valores de solicitação.
- O serviço do jogo determina quando deve repetir a solicitação de consumo.
- O serviço do jogo recria a solicitação de consumo usando o mesmo usuário, ProductId, TrackingId e quantidade.
- O serviço do jogo envia a solicitação para a API de consumo da Microsoft Store.
- O serviço do jogo recebe uma resposta de que a solicitação foi bem-sucedida e de que o novo saldo do usuário é ‘0’.
- O serviço do jogo adiciona 500 moedas ao saldo de moeda do usuário acompanhado no servidor.
- O serviço do jogo remove a solicitação de consumo da lista de transações pendentes, pois o item foi consumido, verificado e o usuário recebeu a moeda do jogo correta no serviço.
Comportamento da API de consumo da Microsoft Store ao verificar solicitações de transações anteriores
Se uma solicitação chegar com valores diferentes, a API a tratará como uma nova solicitação de consumo. Se a API detectar uma nova tentativa com a mesmaTrackingId, usuário, quantidade e productId, ela não consumirá uma segunda vez. Em vez disso, retornará uma resposta bem-sucedida com o saldo restante atual. Devido a esse comportamento, repetir uma solicitação que atingiu o tempo limite é seguro, desde que os valores da solicitação sejam idênticos.
Se você usar a autenticação X-Token na API de consumo, poderá atualizar e obter um novo X-Token, desde que o novo X-Token seja para o mesmo usuário XBOX da solicitação anterior.
Mitigando fraudes de devolução e reembolso de consumíveis com o serviço de eventos Clawback
Para ajudar a evitar abusos e devoluções ou reembolsos fraudulentos de produtos consumíveis, seu serviço deve usar o serviço de eventos Clawback. O Clawback permite que seu serviço receba eventos quando um produto consumível é devolvido ou reembolsado. Seu serviço deve remover o valor adicionado da conta do usuário para esse consumível. Para agir com base em eventos Clawback, use a opção"includeOrderIds": TRUE na sua solicitação de consumo para collections.mp.microsoft.com/v8.0/collections/consume. Seu serviço deve armazenar os dados das transações de consumo das respostas da API usando as seguintes variáveis:
Configure esse banco de dados de acompanhamento cedo, de preferência antes da integração com a fila Clawback. Dados antecipados fornecem transações históricas para reconciliações futuras e uma linha de base limpa para medir os efeitos do processamento do Clawback.
Para obter mais informações, confira Gerenciando reembolsos e estornos a partir do seu serviço.