- Determinar o que os usuários podem comprar
- Avaliar quais produtos o usuário possui ou aos quais tem direito
- Comprar produtos qualificados
Preparação para chamar as APIs XStore
Todas as APIsXStore 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, useXStoreQueryProductsAsync. - 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 ostoreId 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.

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:- XStoreQueryAssociatedProductsAsync → XStoreQueryEntitledProductsAsync
- XStoreQueryAssociatedProductsResult → XStoreQueryEntitledProductsResult
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 emXStoreProduct.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 ostoreId para a API XStoreShowPurchaseUIAsync:
Documentação de referência da API
- XStore (conteúdo da API)
- Funções
- XStoreCreateContext
- XStoreQueryAssociatedProductsAsync
- XStoreQueryProductsAsync
- XStoreQueryAssociatedProductsForStoreIdAsync
- XStoreQueryProductForCurrentGameAsync
- XStoreShowAssociatedProductsUIAsync
- XStoreQueryEntitledProductsAsync
- XStoreQueryAssociatedProductsResult
- XStoreQueryEntitledProductsResult
- XStoreQueryConsumableBalanceRemainingAsync
- XStoreAcquireLicenseForPackageAsync
- XStoreAcquireLicenseForDurablesAsync
- XStoreQueryAddOnLicensesAsync
- XStoreShowPurchaseUIAsync
- Estruturas
- Funções
