Pular para o conteúdo principal

​
Integração de marketplace: Microsoft Store

Este tutorial mostra como resgatar compras no aplicativo da Microsoft Store (incluindo XBOX) por meio do PlayFab Economy v2 usando a API RedeemMicrosoftStoreInventoryItems. Ao final deste tutorial, você terá:
  • Criado um complemento no Partner Center
  • Definido as configurações necessárias do Partner Center e do PlayFab
  • Vinculado seu produto da Microsoft Store a um Bundle do catálogo do PlayFab
  • Chamado a API Redeem e verificado os itens no inventário do jogador

​
Pré-requisitos

  1. Uma conta do Partner Center com acesso ao seu aplicativo.
  2. Um aplicativo já criado no Partner Center.
  3. Um título já criado no Game Manager.
  4. O jogador que chama a API Redeem deve estar autenticado no PlayFab usando uma identidade do XBOX Live (por exemplo, via LoginWithXbox). Jogadores autenticados com outros tipos de identidade (como CustomID ou email) não têm o contexto do XBOX necessário para esse fluxo.

​
Tipos de produto compatíveis

A API RedeemMicrosoftStoreInventoryItems é compatível com os seguintes tipos de produto da Microsoft Store:
  • Consumível gerenciado pelo desenvolvedor — Produtos que podem ser comprados, usados e comprados novamente (por exemplo, pacotes de moeda do jogo). O serviço do jogo é responsável por rastrear o atendimento.
  • Durável — Produtos comprados uma vez e de propriedade permanente (por exemplo, DLC, pacotes de expansão, passes de temporada ou itens cosméticos).
Consumíveis gerenciados pela Store não são compatíveis. O PlayFab Economy v2 não pode resgatar consumíveis gerenciados pela Store. Se o seu complemento estiver configurado como um consumível gerenciado pela Store, a API Redeem retornará uma resposta HTTP 200 com resultados vazios e nenhum erro, o que torna o problema difícil de diagnosticar.

​
Etapa 1: Criar seu complemento no Partner Center

  1. Entre no Partner Center e navegue até seu aplicativo.
  2. Em Complementos, selecione Criar um novo complemento.
  3. Selecione o tipo de produto apropriado:
    • Consumível gerenciado pelo desenvolvedor para itens que podem ser comprados novamente (moeda, pacotes consumíveis).
    • Durável para compras únicas (DLC, passes de temporada, desbloqueios cosméticos).
  4. Conclua a configuração do complemento (preços, descrições e assim por diante) e envie-o.
Ao criar um consumível gerenciado pelo desenvolvedor, o Partner Center exibe um aviso que diz: “O XBOX exige que os consumíveis sejam gerenciados, portanto, não use esta opção e crie um complemento de ‘consumível gerenciado’. Se você tiver alguma dúvida, entre em contato com seu representante da Microsoft.”* Esse aviso reflete as diretrizes gerais da plataforma XBOX e não se aplica ao fluxo de resgate do PlayFab. Consumíveis gerenciados pelo desenvolvedor funcionam corretamente no XBOX quando usados com a API RedeemMicrosoftStoreInventoryItems do PlayFab. Você pode prosseguir com segurança com esse tipo de produto.
  1. Depois de criar seu complemento, anote a Store ID — a cadeia alfanumérica (por exemplo, 9NBLGGH42CFD) mostrada no Partner Center. Use esse valor para o PlayFab, não a Product ID definida pelo desenvolvedor nem o nome do complemento.
Para obter mais informações sobre tipos de produto, consulte Escolhendo o tipo de produto certo.

​
Etapa 2: Configurar o Product Group, o Dev Studio e a Business Partner ID

Esta etapa configura o fluxo de token delegado do XBOX Security Token Service (XSTS) que o PlayFab usa para consultar a API Collections da Microsoft Store em nome do jogador.
A configuração do Product Group, do Dev Studio e da Business Partner ID é a etapa esquecida com mais frequência. Sem ela, a chamada à API Redeem é bem-sucedida (HTTP 200), mas a API Collections retorna zero itens, resultando em matrizes Succeeded, Failed e TransactionIds vazias, sem nenhuma mensagem de erro.
  1. No Partner Center, navegue até Developer Settings > XBOX Live > Web Services e gere um Business Partner Certificate, caso ainda não tenha feito isso.
  2. Navegue até Developer Settings > XBOX Live > Business Partner e anote a Business Partner ID que corresponde ao serviço Web ao qual sua terceira parte confiável está vinculada.
  3. Crie um Dev Studio (ou use um existente) e defina a Dev Studio ID dele para corresponder à Business Partner ID da etapa 2. Se o Dev Studio já tiver uma ID diferente, crie um novo Dev Studio em vez de alterar o valor existente. Alterá-lo pode interromper serviços existentes.
  4. Crie um Product Group e atribua-o ao Dev Studio da etapa 3.
  5. Adicione seu produto de jogo e todos os seus complementos à lista Included in this product group. Os itens devem ser movidos explicitamente do lado “available” para o lado “included”.
  6. Selecione Save.
  7. Navegue até a página XBOX Settings do seu jogo e confirme se o Business Partner vinculado corresponde ao da etapa 2.
  8. Publique novamente seu produto de jogo e todos os complementos na Microsoft Store na sandbox de destino ou no ambiente RETAIL.
Para obter o passo a passo completo da configuração, consulte Configurar produtos com autenticação delegada (tokens XSTS).

​
Etapa 3: Habilitar o complemento XBOX Network no Game Manager

O complemento XBOX Network vincula seu produto do Partner Center ao seu título do PlayFab e habilita a validação de token do XBOX para resgate da Microsoft Store.
  1. Abra o Game Manager e selecione seu título.
  2. Selecione Add-ons no menu de navegação à esquerda.
  3. Localize e selecione o complemento XBOX Network (rotulado como Distribute for XBOX).
  4. Selecione a Seller ID correta na lista suspensa. Se você não vir a Seller ID correta, selecione Sign in with a different partner center account.
  5. Selecione sua Partner Center Product ID na lista suspensa e confirme se a XBOX Live Title ID (decimal) corresponde ao que você vê no Partner Center em XBOX services > XBOX Settings.
  6. Selecione Install XBOX Network para salvar a configuração.
Para obter mais detalhes, consulte Configuração do complemento XBOX Live.
O Game Manager também tem uma página separada para o complemento Microsoft Store (também em Add-ons). Embora não exija configuração, ela contém orientações úteis, incluindo a confirmação dos tipos de produto compatíveis e detalhes sobre a configuração da Dev Studio ID e da Business Partner ID.

​
Etapa 4: Criar um Bundle do PlayFab com Marketplace Mapping

Para vincular seu produto da Microsoft Store ao seu catálogo do PlayFab, crie um Bundle com um Marketplace Mapping (AlternateId).
  1. No Game Manager, navegue até Economy > Catalog (V2) > Bundles.
  2. Selecione New bundle (ou edite um existente).
  3. Na seção Marketplace Mapping, adicione um novo mapeamento:
    • Defina o Marketplace type como MicrosoftStore (diferencia maiúsculas de minúsculas, deve ser exatamente MicrosoftStore).
    • Defina o value como a Store ID exata do Partner Center (por exemplo, 9NBLGGH42CFD). Não use a Product ID definida pelo desenvolvedor nem o nome do complemento.
  4. Adicione os itens que você deseja que o jogador receba quando esse Bundle for resgatado (por exemplo, moeda do jogo, itens virtuais).
  5. Publique o Bundle. Bundles não publicados (rascunho) não são correspondidos durante o resgate.
Para obter mais informações sobre IDs alternativas, consulte IDs alternativas.

​
Etapa 5: Adquirir e fornecer o token do XBOX

Ao chamar a API RedeemMicrosoftStoreInventoryItems, você deve fornecer um token do XBOX válido no parâmetro XboxToken.
  • Se você estiver usando a API C do GDK, use:
Todos os três parâmetros (método, URL e corpo) devem ser fornecidos exatamente como mostrado. Um token obtido incorretamente faz com que a consulta à API Collections falhe silenciosamente, retornando resultados vazios sem nenhum erro.

​
Etapa 6: Testar a integração

Antes de considerar sua integração concluída, verifique o fluxo completo de ponta a ponta:
  1. Verifique se o seu complemento está publicado na sandbox ou no ambiente em que você está testando.
  2. Entre como um jogador de teste usando uma identidade do XBOX Live e faça uma compra de teste do complemento pela Microsoft Store. O jogador deve ter uma compra não resgatada na conta antes que a API Redeem tenha algo para detectar.
  3. Chame RedeemMicrosoftStoreInventoryItems com o XboxToken do jogador.
  4. Verifique se a resposta contém entradas na matriz Succeeded e se os itens correspondentes aparecem no inventário do PlayFab do jogador.
Atendimento de consumíveis gerenciados pelo desenvolvedor: depois que um consumível gerenciado pelo desenvolvedor é resgatado, o PlayFab o relata automaticamente como atendido (consumido) à Microsoft Store em seu nome. A etapa de atendimento é necessária para que o jogador possa comprar o consumível novamente. Se o consumível não aparecer como atendido após um resgate bem-sucedido, repita a chamada RedeemMicrosoftStoreInventoryItems. Se o problema persistir, encaminhe-o à equipe do PlayFab pelo seu canal de suporte. Para obter detalhes, consulte Gerenciando consumíveis e reembolsos.

​
Solução de problemas

Se a chamada RedeemMicrosoftStoreInventoryItems retornar com êxito (HTTP 200), mas as matrizes Succeeded, Failed e TransactionIds da resposta estiverem todas vazias, a API Collections da Microsoft Store não está encontrando nenhum item correspondente para resgatar. Normalmente, um problema de configuração causa esse comportamento. Verifique os seguintes itens: Se a API retornar um erro HTTP (como 400), verifique se a resposta de erro contém os seguintes códigos:
Se a chamada for bem-sucedida (HTTP 200), mas retornar resultados vazios e todas as outras configurações parecerem corretas, verifique primeiro a configuração do Product Group. A etapa do Product Group é a etapa esquecida com mais frequência.

​
Observação sobre títulos de PC / Windows

Este tutorial aborda o fluxo do XBOX, que usa tokens XSTS delegados (passados pelo parâmetro XboxToken). Para títulos de PC / Windows, a Microsoft recomenda usar User Store IDs com o Microsoft Entra ID para autenticação de serviço a serviço. Para obter mais informações, consulte Solicitando uma User Store ID para autenticação de serviço a serviço e Autenticando seu serviço — User Store IDs.

​
Confira também

Última modificação em 6 de outubro de 2026