Skip to main content
Uma loja no jogo normalmente envolve três operações básicas:
  1. Determinar o que os usuários podem comprar
  2. Avaliar quais produtos o usuário possui ou aos quais tem direito
  3. Comprar produtos qualificados
Este artigo ilustra código de exemplo para cada operação, derivado do exemplo InGameStore, que é continuamente atualizado para refletir as práticas recomendadas.

Preparação para chamar as APIs XStore

Todas as APIs XStore operam sobre um XStoreContextHandle criado usando XStoreCreateContext. Esse contexto permite que você execute operações da loja no contexto do usuário especificado no console e do usuário padrão disponível em um PC. No console, um evento de suspensão ou de Quick Resume invalida o contexto. Para lidar com essas condições com segurança, feche o XStoreContextHandle e recrie-o sempre que o jogo for retomado de um estado suspenso.

1. Determinar o que os usuários podem comprar

O que um jogo geralmente oferece para compra são seus complementos. O código a seguir demonstra a chamada básica da API XStoreQueryAssociatedProductsAsync necessária para que o jogo saiba quais produtos estão disponíveis. Essa consulta retorna automaticamente apenas os complementos compráveis associados ao jogo. Produtos não relacionados associados ao mesmo editor (ou seja, configurados com a mesma conta do Partner Center) também podem ser retornados nessa chamada, desde que o jogo esteja definido com uma relação “pode vender” com esse produto na seção Configuração de relação de produtos no Partner Center. Para saber mais sobre como configurar relações de produtos, confira Configurar relações de produtos para um jogo.

Observações

  • Somente produtos compráveis são retornados com XStoreQueryAssociatedProductsAsync; produtos que são concedidos apenas em pacotes ou que, de outra forma, não estão definidos para serem comprados de forma independente não são retornados. Para estes últimos, use XStoreQueryProductsAsync.
  • Não há conhecimento prévio do número de produtos retornados; portanto, a contagem deve ser acumulada.

Paginação

Lidar com a paginação não é opcional ao consultar produtos associados ou direitos. O número de páginas retornadas pelo serviço e o número de itens retornados por página podem variar entre ambientes e de acordo com a carga do serviço. Para ver um exemplo de como lidar com a paginação, confira XStoreQueryAssociatedProductsAsync.

Outras opções

XStoreQueryProductsAsync pode ser usada para consultar produtos específicos, se o storeId for conhecido ou se outros actionFilters forem desejados. “Ações” são cenários de uso que se aplicam a um produto, que incluem verbos como Purchase, License, Gift e Redeem. XStoreQueryAssociatedProductsForStoreIdAsync pode ser usada para consultar produtos associados de outros jogos, o que pode ser útil para fazer venda cruzada dos complementos de outro título. XStoreQueryProductForCurrentGameAsync serve para consultar apenas o produto do jogo em execução no momento. XStoreShowAssociatedProductsUIAsync leva o usuário ao aplicativo Microsoft Store, em uma exibição de produtos associados filtrados por tipo de produto. Essa API é uma alternativa a ter de enumerar os produtos disponíveis para apresentar em uma interface no jogo. Complementos para este jogo

2. Avaliar quais produtos o usuário possui ou aos quais tem direito

Esta etapa envolve grande parte do mesmo código mostrado anteriormente, mas com estas substituições: As APIs QueryEntitledProducts retornam os produtos aos quais o usuário tem direito. Ter direito significa que o usuário possui o produto diretamente, satisfaz o direito por meio de outros produtos (como pacotes e assinaturas) ou obtém o direito por meio de um direito compartilhado de outro usuário. Além disso, os resultados de XStoreQueryAssociatedProductsAsync (e funções relacionadas) determinam o direito. A struct XStoreProduct contém um campo isInUserCollection que é definido como true quando o usuário tem direito.

Propriedade de consumíveis

A quantidade do consumível é indicada em XStoreProduct.skus[i].collectionData.quantity. Normalmente, há apenas um SKU para um produto consumível. Você também pode usar XStoreQueryConsumableBalanceRemainingAsync para consultar a quantidade, mas evite usá-la individualmente para um grande número de consumíveis, pois cada chamada gera uma chamada de serviço. Para manter a integridade de ecossistemas baseados em consumíveis, use validação e resgate de consumíveis no lado do serviço. Para obter mais informações, confira Ecossistemas baseados em consumíveis.

Propriedade de duráveis

Não basta verificar se a conta possui o produto para determinar que ela deve ter direito a usar o produto no jogo. Produtos duráveis devem seguir a política de compartilhamento de conteúdo descrita em Modelo de compartilhamento de produtos para jogos. Use XStoreAcquireLicenseForPackageAsync para um durável com pacote para determinar se ele pode ser licenciado de acordo com as regras de compartilhamento de conteúdo. Use XStoreAcquireLicenseForDurablesAsync para um durável sem pacote para fazer o mesmo. Use XStoreQueryAddOnLicensesAsync para um jogo licenciado digitalmente para retornar a lista de produtos duráveis sem pacote licenciáveis. Para obter mais informações, confira Gerenciar e licenciar conteúdo para download e Como usar um durável sem pacote.

3. Comprar produtos qualificados

Para mostrar o fluxo de compra de um produto comprável, passe o storeId para a API XStoreShowPurchaseUIAsync:
Os jogadores também podem fazer compras fora do jogo, alternando explicitamente para a Microsoft Store, no Xbox.com, no PC, em aplicativos móveis ou em outros canais. Portanto, forneça um local no jogo que atualize de forma confiável a propriedade dos produtos sob demanda. O fluxo inicial de entrada é um ótimo lugar, mas também adicione a atualização como parte da transição para a loja no jogo ou em algum lugar nas configurações.

Documentação de referência da API

Confira também

Visão geral do comércio Habilitando o desenvolvimento e o teste do XStore Referência da API XStore
Last modified on October 6, 2026