Skip to main content
Una tienda del juego normalmente implica tres operaciones básicas:
  1. Determinar lo que los usuarios pueden comprar
  2. Evaluar qué productos posee el usuario o a cuáles tiene derecho
  3. Comprar productos aptos
En este artículo se muestra código de ejemplo para cada operación, derivado del ejemplo InGameStore, que se actualiza continuamente para reflejar los procedimientos recomendados.

Preparación para llamar a las API de XStore

Todas las API de XStore funcionan sobre un XStoreContextHandle creado mediante XStoreCreateContext. Este contexto le permite realizar operaciones de la tienda en el contexto del usuario especificado en la consola y del usuario predeterminado disponible en un PC. En la consola, un evento de suspensión o de reanudación rápida invalida el contexto. Para controlar estas condiciones de forma segura, cierre el XStoreContextHandle y vuelva a crearlo cada vez que el juego se reanude desde un estado suspendido.

1. Determinar lo que los usuarios pueden comprar

Lo que un juego suele ofrecer para su compra son sus complementos. El código siguiente muestra la llamada básica a la API XStoreQueryAssociatedProductsAsync necesaria para que el juego sepa qué productos están disponibles. Esta consulta devuelve automáticamente solo los complementos que se pueden comprar asociados al juego. Los productos no relacionados asociados al mismo publicador (es decir, configurados con la misma cuenta de Partner Center) también pueden devolverse en esta llamada siempre que el juego tenga establecida una relación de tipo “can sell” con ese producto en la sección Product relationship setup de Partner Center. Para obtener más información sobre cómo configurar relaciones de productos, consulte Configurar relaciones de productos para un juego.

Aspectos que se deben tener en cuenta

  • Con XStoreQueryAssociatedProductsAsync solo se devuelven los productos que se pueden comprar; los productos que solo se conceden en lotes o que, por otros motivos, no están configurados para poder comprarse de forma independiente no se devuelven. Para estos últimos, use XStoreQueryProductsAsync.
  • No se conoce de antemano el número de productos que se devuelven, por lo que el recuento debe acumularse.

Paginación

El control de la paginación no es opcional al consultar productos asociados o derechos. El número de páginas devuelto por el servicio, y el número de elementos devueltos por página, pueden variar según el entorno y la carga del servicio. Para ver un ejemplo de cómo controlar la paginación, consulte XStoreQueryAssociatedProductsAsync.

Otras opciones

XStoreQueryProductsAsync se puede usar para consultar productos específicos, si se conoce el storeId o si se desean otros actionFilters. Las “acciones” son escenarios de uso que se aplican a un producto e incluyen verbos como Purchase, License, Gift y Redeem. XStoreQueryAssociatedProductsForStoreIdAsync se puede usar para consultar los productos asociados de otros juegos, lo que puede ser útil para hacer ventas cruzadas de los complementos de otro título. XStoreQueryProductForCurrentGameAsync sirve para consultar únicamente el producto del juego que se está ejecutando actualmente. XStoreShowAssociatedProductsUIAsync lleva al usuario a la aplicación Microsoft Store, a una vista de los productos asociados, filtrados por tipo de producto. Esta API es una alternativa a tener que enumerar los productos disponibles para presentarlos en una interfaz del juego.

2. Evaluar qué productos posee el usuario o a cuáles tiene derecho

Este paso implica gran parte del mismo código mostrado anteriormente, pero con estos reemplazos: Las API QueryEntitledProducts devuelven los productos a los que el usuario tiene derecho. Tener derecho significa que el usuario posee directamente el producto, satisface el derecho a través de otros productos (como lotes y suscripciones) u obtiene el derecho mediante un derecho compartido de otro usuario. Además, los resultados de XStoreQueryAssociatedProductsAsync (y funciones relacionadas) determinan el derecho. La estructura XStoreProduct contiene un campo isInUserCollection que se establece en true cuando el usuario tiene derecho.

Propiedad de consumibles

La cantidad de consumibles se indica en XStoreProduct.skus[i].collectionData.quantity. Normalmente, solo hay una SKU para un producto consumible. También puede usar XStoreQueryConsumableBalanceRemainingAsync para consultar la cantidad, pero evite usarlo individualmente para un gran número de consumibles, ya que cada llamada implica una llamada al servicio. Para mantener la integridad de los ecosistemas basados en consumibles, use la validación y el canje de consumibles en el lado del servicio. Para obtener más información, consulte Ecosistemas basados en consumibles.

Propiedad de duraderos

No basta con comprobar si la cuenta posee el producto para determinar que debería tener derecho a usar el producto dentro del juego. Los productos duraderos deben cumplir la directiva de uso compartido de contenido que se describe en Modelo de uso compartido de productos para juegos. Use XStoreAcquireLicenseForPackageAsync para un duradero con un paquete a fin de determinar si se puede licenciar según las reglas de uso compartido de contenido. Use XStoreAcquireLicenseForDurablesAsync para un duradero sin un paquete con el mismo fin. Use XStoreQueryAddOnLicensesAsync para un juego con licencia digital a fin de devolver la lista de productos duraderos sin paquete que se pueden licenciar. Para obtener más información, consulte Administrar y licenciar contenido descargable y Cómo usar un duradero sin un paquete.

3. Comprar productos aptos

Para mostrar el flujo de compra de un producto que se puede comprar, pase el storeId a la API XStoreShowPurchaseUIAsync:
Los jugadores también pueden realizar compras fuera del juego cambiando explícitamente a Microsoft Store, en Xbox.com, PC, aplicaciones móviles u otros puntos de venta. Por lo tanto, proporcione un lugar en su juego que actualice de forma confiable la propiedad de los productos a petición. El flujo inicial de inicio de sesión es un lugar perfecto, pero agregue también la actualización como parte de la transición a la tienda del juego o en algún lugar de la configuración.

Documentación de referencia de la API

Consulte también

Información general sobre comercio Habilitación del desarrollo y las pruebas de XStore Referencia de la API de XStore
Última modificación el 1 de septiembre de 2026