> ## Documentation Index > Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Operações básicas da loja > Implemente uma loja no jogo com as APIs XStore, incluindo determinar o que os usuários podem comprar, verificar direitos e concluir compras. Uma loja no jogo normalmente envolve três operações básicas: 1. [Determinar o que os usuários podem comprar](#1-determining-what-users-can-purchase) 2. [Avaliar quais produtos o usuário possui ou aos quais tem direito](#2-evaluating-what-products-the-user-owns-or-is-entitled-to) 3. [Comprar produtos qualificados](#3-purchasing-eligible-products) 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](/pt-BR/reference/system/xstore/xstore_members). 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](/pt-BR/reference/system/xstore/xstore_members) 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](/pt-BR/publishing/game-publishing/tutorial-xbox-managed/how-to-create-product-relationships). ```cpp theme={null} bool CALLBACK ProductEnumerationCallback(const XStoreProduct* product, void* context) { // Handle adding the product to the game printf("%s %s %u\n", product->title, product->storeId, product->productKind); return true; } void QueryCatalog() { auto async = new XAsyncBlock{}; async->queue = m_asyncQueue; async->callback = [](XAsyncBlock* async) { XStoreProductQueryHandle queryHandle = nullptr; HRESULT hr = XStoreQueryAssociatedProductsResult(async, &queryHandle); if (SUCCEEDED(hr)) { hr = XStoreEnumerateProductsQuery(queryHandle, async->context, ProductEnumerationCallback); if (SUCCEEDED(hr)) { // TODO: Check for more pages to process printf("Enumeration complete\n"); } XStoreCloseProductsQueryHandle(queryHandle); delete async; } }; XStoreProductKind typeFilter = XStoreProductKind::Consumable | XStoreProductKind::Durable | XStoreProductKind::Game; HRESULT hr = XStoreQueryAssociatedProductsAsync( m_xStoreContext, typeFilter, UINT8_MAX, // placeholder maximum, see Paging async) if (FAILED(hr)) { delete async; } } ``` ### 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](/pt-BR/reference/system/xstore/xstore_members). ### Outras opções [XStoreQueryProductsAsync](/pt-BR/reference/system/xstore/xstore_members) 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](/pt-BR/reference/system/xstore/xstore_members) 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](/pt-BR/reference/system/xstore/xstore_members) serve para consultar apenas o produto do jogo em execução no momento. [XStoreShowAssociatedProductsUIAsync](/pt-BR/reference/system/xstore/xstore_members) 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: * [XStoreQueryAssociatedProductsAsync](/pt-BR/reference/system/xstore/xstore_members) → [XStoreQueryEntitledProductsAsync](/pt-BR/reference/system/xstore/xstore_members) * [XStoreQueryAssociatedProductsResult](/pt-BR/reference/system/xstore/xstore_members) → [XStoreQueryEntitledProductsResult](/pt-BR/reference/system/xstore/xstore_members) 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](/pt-BR/reference/system/xstore/xstore_members) (e funções relacionadas) determinam o direito. A struct [XStoreProduct](/pt-BR/reference/system/xstore/xstore_members) 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](/pt-BR/reference/system/xstore/xstore_members) 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](/pt-BR/publishing/xstore-commerce/xstore-consumables). ### 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](/pt-BR/publishing/xstore-commerce/xstore-product-sharing). Use [XStoreAcquireLicenseForPackageAsync](/pt-BR/reference/system/xstore/xstore_members) 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](/pt-BR/reference/system/xstore/xstore_members) para um **durável sem pacote** para fazer o mesmo. Use [XStoreQueryAddOnLicensesAsync](/pt-BR/reference/system/xstore/xstore_members) 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](/pt-BR/publishing/xstore-commerce/xstore-dlc) e [Como usar um durável sem pacote](/pt-BR/publishing/xstore-commerce/xstore-dwob). ## 3. Comprar produtos qualificados Para mostrar o fluxo de compra de um produto comprável, passe o `storeId` para a API [XStoreShowPurchaseUIAsync](/pt-BR/reference/system/xstore/xstore_members): ```cpp theme={null} void MakePurchase(const char* storeId) { auto async = new XAsyncBlock{}; async->context = &storeId; async->queue = m_asyncQueue; async->callback = [](XAsyncBlock *async) { const char* = reinterpret_cast(async->context); HRESULT hr = XStoreShowPurchaseUIResult(async); if (SUCCEEDED(hr)) { printf("Purchase succeeded (%s)\n", storeId); // Refresh ownership and update game } else { printf("Purchase failed (%s) 0x%x\n", storeId, hr); if (hr == E_GAMESTORE_ALREADY_PURCHASED) { printf("Already own this\n"); } } delete async; }; HRESULT hr = XStoreShowPurchaseUIAsync( m_xStoreContext, storeId, nullptr, // Can be used to override the title bar text nullptr, // Can be used to provide extra details to purchase async); if (FAILED(hr)) { delete async; printf("Error calling XStoreShowPurchaseUIAsync : 0x%x\n", hr); return; } } ``` 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 * [XStore (conteúdo da API)](/pt-BR/reference/system/xstore/xstore_members) * Funções * [XStoreCreateContext](/pt-BR/reference/system/xstore/xstore_members) * [XStoreQueryAssociatedProductsAsync](/pt-BR/reference/system/xstore/xstore_members) * [XStoreQueryProductsAsync](/pt-BR/reference/system/xstore/xstore_members) * [XStoreQueryAssociatedProductsForStoreIdAsync](/pt-BR/reference/system/xstore/xstore_members) * [XStoreQueryProductForCurrentGameAsync](/pt-BR/reference/system/xstore/xstore_members) * [XStoreShowAssociatedProductsUIAsync](/pt-BR/reference/system/xstore/xstore_members) * [XStoreQueryEntitledProductsAsync](/pt-BR/reference/system/xstore/xstore_members) * [XStoreQueryAssociatedProductsResult](/pt-BR/reference/system/xstore/xstore_members) * [XStoreQueryEntitledProductsResult](/pt-BR/reference/system/xstore/xstore_members) * [XStoreQueryConsumableBalanceRemainingAsync](/pt-BR/reference/system/xstore/xstore_members) * [XStoreAcquireLicenseForPackageAsync](/pt-BR/reference/system/xstore/xstore_members) * [XStoreAcquireLicenseForDurablesAsync](/pt-BR/reference/system/xstore/xstore_members) * [XStoreQueryAddOnLicensesAsync](/pt-BR/reference/system/xstore/xstore_members) * [XStoreShowPurchaseUIAsync](/pt-BR/reference/system/xstore/xstore_members) * Estruturas * [XStoreProduct](/pt-BR/reference/system/xstore/xstore_members) ## Confira também [Visão geral do comércio](/pt-BR/publishing/xstore-commerce/xstore-commerce-overview) [Habilitando o desenvolvimento e o teste do XStore](/pt-BR/publishing/xstore-commerce/xstore-product-testing-setup) [Referência da API XStore](/pt-BR/reference/system/xstore/xstore_members) ## Related topics - [Visão geral do XBOX Series X|S](/pt-BR/paths/series-xs/overview.md) - [Visão geral do Unity](/pt-BR/paths/unity/overview.md) - [Visão geral do Unreal Engine](/pt-BR/paths/unreal/overview.md) - [Visão geral do Windows & ROG XBOX Ally](/pt-BR/paths/windows/overview.md) - [Visão geral do Play Anywhere (Console + PC)](/pt-BR/paths/play-anywhere/overview.md)