- Determinar lo que los usuarios pueden comprar
- Evaluar qué productos posee el usuario o a cuáles tiene derecho
- Comprar productos aptos
Preparación para llamar a las API de XStore
Todas las API deXStore 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
XStoreQueryAssociatedProductsAsyncsolo 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, useXStoreQueryProductsAsync. - 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 elstoreId 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:- XStoreQueryAssociatedProductsAsync → XStoreQueryEntitledProductsAsync
- XStoreQueryAssociatedProductsResult → XStoreQueryEntitledProductsResult
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 enXStoreProduct.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 elstoreId a la API XStoreShowPurchaseUIAsync:
Documentación de referencia de la API
- XStore (contenido de la API)
- Funciones
- XStoreCreateContext
- XStoreQueryAssociatedProductsAsync
- XStoreQueryProductsAsync
- XStoreQueryAssociatedProductsForStoreIdAsync
- XStoreQueryProductForCurrentGameAsync
- XStoreShowAssociatedProductsUIAsync
- XStoreQueryEntitledProductsAsync
- XStoreQueryAssociatedProductsResult
- XStoreQueryEntitledProductsResult
- XStoreQueryConsumableBalanceRemainingAsync
- XStoreAcquireLicenseForPackageAsync
- XStoreAcquireLicenseForDurablesAsync
- XStoreQueryAddOnLicensesAsync
- XStoreShowPurchaseUIAsync
- Estructuras
- Funciones
