Limitación del sandbox: al consumir productos consumibles administrados por el desarrollador en un sandbox de desarrollo, solo se admite la autenticación con tokens XSTS. La autenticación con User Store ID o Microsoft Entra ID no funciona para las llamadas de consumo de consumibles administrados por el desarrollador en entornos de sandbox. Planifique sus pruebas en consecuencia. Para obtener más información, consulte la sección Requisitos previos de la API Consume.
Uso de la biblioteca .NET Microsoft.StoreServices y del ejemplo
Para ayudar a ilustrar los principios y flujos descritos en este artículo, revise el ejemplo de Microsoft.StoreServices, que proporciona:- Uso de la biblioteca Microsoft.StoreServices para administrar la autenticación y realizar las llamadas a los servicios de Microsoft Store.
- Lógica de ejemplo para administrar productos consumibles, hacer el seguimiento de las solicitudes de consumo pendientes, conciliar compras reembolsadas, renovar User Store ID expirados y mucho más.
- Una guía de configuración que incluye los pasos de este artículo sobre cómo configurar su Microsoft Entra ID para este método de autenticación.
- Microsoft.StoreServices (GitHub)
- Ejemplo de Microsoft.StoreServices (GitHub)
Administración de consumibles
Esquema recomendado de un servicio de administración de consumibles
Use un único flujo de servidor para validar la propiedad, entregar el uso y conciliar los reembolsos. El esquema siguiente mantiene estas responsabilidades explícitas y seguras frente a reintentos.Administración del saldo del usuario en su servicio frente a Microsoft Store
Los productos consumibles administrados por la Store se pueden administrar completamente en el servicio de su juego consumiendo cualquier saldo distinto de cero de Microsoft Store. Como alternativa, el saldo de consumibles del usuario se puede administrar a través de Microsoft Store, consumiendo cantidad únicamente cuando se usa para artículos del juego. Los productos consumibles administrados por el desarrollador, sin embargo, requieren administración en un servicio de juego. Consulte Elección del tipo de producto correcto para obtener más información sobre los consumibles administrados por el desarrollador frente a los administrados por Microsoft Store. El enfoque más común es hacer el seguimiento del saldo de moneda efectivo del usuario en su servicio. En este diseño, su servicio consulta los saldos de consumibles distintos de cero, los consume y abona la moneda del juego equivalente en la cuenta del usuario. Este flujo reduce las llamadas repetidas a las API de la Store después de la entrega, simplifica la gestión del saldo entre plataformas y proporciona a los equipos de soporte un sistema central para los ajustes de saldo. Configuración típica: configure cada nivel de moneda como un consumible administrado por la Store independiente que otorga una cantidad de1 por compra y, a continuación, asigne cada producto a su valor en el juego. Ejemplo: un consumible de “500 monedas” aumenta la cantidad en la Store a 1; después del consumo, la cantidad en la Store vuelve a 0 y su servicio abona 500 monedas.
Los consumibles administrados por la Store pueden otorgar el valor completo directamente a la cantidad de la Store en la compra (por ejemplo, 500 por compra). En ese modelo, la Store hace el seguimiento del crecimiento del saldo y su servicio deduce cantidad cuando los usuarios gastan moneda en el juego. Sin embargo, colocar todos los niveles como SKU bajo un único identificador de producto limita características como los precios promocionales específicos de cada nivel y los tokens de canje 5x5. Consulte Procedimientos recomendados para ofrecer moneda del juego.
Uso de TrackingIds como sistema redundante para la validación de consumos
Incluya unTrackingId en cada solicitud de consumo. Si se pierde una respuesta, reintente con el mismo TrackingId, usuario, productId y cantidad para confirmar si el consumo original se realizó correctamente. Esta solicitud de reintento evita concesiones dobles y, al mismo tiempo, permite reintentos seguros.
El flujo siguiente muestra un patrón de consumo seguro frente a reintentos.
El producto A (500 monedas del juego) es un consumible configurado para otorgar una cantidad de 1 en la Store.
- El usuario compra el producto A y ahora tiene una cantidad de
1para el producto al llamar al servicio de consulta. - El servicio del juego consulta el saldo de consumibles del usuario mediante la API de consulta de Microsoft Store y ve que el saldo del usuario es
1. - El servicio del juego genera un TrackingID, crea una solicitud de consumo para consumir una unidad del producto y agrega la información de la solicitud a una lista de transacciones pendientes.
- El servicio del juego envía la solicitud a la API de consumo de Microsoft Store.
- El servicio del juego no obtiene respuesta de la API de consumo (pérdida de paquetes de red, interrupción del servicio, corte de energía, etc.). En este punto, el servicio no puede confirmar si la transacción se completó. Consultar el inventario por sí solo puede ser ambiguo si el usuario volvió a comprar durante la interrupción. Use la lista de transacciones pendientes y reintente con los mismos valores de la solicitud.
- El servicio del juego determina cuándo debe reintentar la solicitud de consumo.
- El servicio del juego vuelve a crear la solicitud de consumo con el mismo usuario, ProductId, TrackingId y cantidad.
- El servicio del juego envía la solicitud a la API de consumo de Microsoft Store.
- El servicio del juego recibe una respuesta que indica que la solicitud se realizó correctamente y que el nuevo saldo del usuario es “0”.
- El servicio del juego agrega 500 monedas al saldo de moneda del usuario del que se hace el seguimiento en el servidor.
- El servicio del juego quita la solicitud de consumo de la lista de transacciones pendientes, ya que el artículo se consumió y verificó, y al usuario se le otorgó la moneda del juego correcta en el servicio.
Comportamiento de la API de consumo de Microsoft Store al verificar solicitudes de transacción anteriores
Si llega una solicitud con valores diferentes, la API la trata como una nueva solicitud de consumo. Si la API detecta un reintento con el mismoTrackingId, usuario, cantidad y productId, no consume una segunda vez. En su lugar, devuelve una respuesta correcta con el saldo restante actual. Debido a este comportamiento, reproducir una solicitud que agotó el tiempo de espera es seguro siempre que los valores de la solicitud sean idénticos.
Si usa autenticación X-Token con la API de consumo, puede actualizar y obtener un nuevo X-Token siempre que el nuevo X-Token sea para el mismo usuario de XBOX que la solicitud anterior.
Mitigación del fraude por devoluciones y reembolsos de consumibles con el servicio de eventos de Clawback
Para ayudar a prevenir abusos y devoluciones o reembolsos fraudulentos de productos consumibles, su servicio debe usar el servicio de eventos de Clawback. Clawback permite a su servicio recibir eventos cuando un producto consumible se devuelve o se reembolsa. Su servicio debe quitar el valor agregado de la cuenta del usuario para ese consumible. Para tomar medidas sobre los eventos de Clawback, asegúrese de usar la opción"includeOrderIds": TRUE en su solicitud de consumo a collections.mp.microsoft.com/v8.0/collections/consume. Su servicio debe almacenar los datos de las transacciones de consumo de las respuestas de la API mediante las variables siguientes:
Configure esta base de datos de seguimiento pronto, preferiblemente antes de la incorporación a la cola de Clawback. Los datos tempranos le proporcionan transacciones históricas para futuras conciliaciones y una línea base limpia para medir los efectos del procesamiento de Clawback.
Para obtener más información, consulte Administración de reembolsos y contracargos desde su servicio.