샌드박스 제한 사항: 개발 샌드박스에서 개발자 관리형 소모품 제품을 소비할 때는 XSTS 토큰 인증만 지원됩니다. User Store ID 또는 Microsoft Entra ID 인증은 샌드박스 환경의 개발자 관리형 소모품 소비 호출에서 작동하지 않습니다. 이에 따라 테스트를 계획하세요. 자세한 내용은 Consume API의 사전 요구 사항 섹션을 참고하세요.
Microsoft.StoreServices .NET 라이브러리 및 샘플 활용
이 문서에서 설명하는 원칙과 흐름을 보여주는 데 도움이 되도록 다음을 제공하는 Microsoft.StoreServices 샘플을 검토하세요.- 인증을 관리하고 Microsoft Store 서비스를 호출하기 위한 Microsoft.StoreServices 라이브러리 사용.
- 소모품 제품 관리, 대기 중인 소비 요청 추적, 환불된 구매 조정, 만료된 User Store ID 갱신 등을 위한 예제 로직.
- 이 인증 방법에 대한 Microsoft Entra ID를 구성하고 설정하는 방법에 대한 이 문서의 단계를 포함한 구성 가이드.
- Microsoft.StoreServices (GitHub)
- Microsoft.StoreServices Sample (GitHub)
소모품 관리
소모품 관리 서비스의 권장 개요
소유권 검증, 사용 이행, 환불 조정을 위해 단일 서버 흐름을 사용하세요. 다음 개요는 이러한 책임을 명시적이고 재시도에 안전하게 유지합니다.서비스와 Microsoft Store에서 사용자 잔액 관리
스토어 관리형 소모품 제품은 Microsoft Store에서 0이 아닌 잔액을 소비하여 게임 서비스에서 완전히 관리할 수 있습니다. 또는 사용자의 소모품 잔액을 Microsoft Store를 통해 관리하고 인게임 아이템에 사용될 때만 수량을 소비할 수도 있습니다. 그러나 개발자 관리형 소모품 제품은 게임 서비스에서 관리해야 합니다. 개발자 관리형과 Microsoft 스토어 관리형 소모품에 대한 자세한 내용은 올바른 제품 유형 선택을 참고하세요. 가장 일반적인 접근 방식은 서비스에서 사용자의 실제 통화 잔액을 추적하는 것입니다. 이 설계에서 서비스는 0이 아닌 소모품 잔액을 쿼리하고, 이를 소비하고, 동등한 인게임 통화를 사용자 계정에 크레딧합니다. 이 흐름은 이행 후 반복적인 스토어 API 호출을 줄이고, 크로스 플랫폼 잔액 처리를 단순화하며, 지원 팀에 잔액 조정을 위한 중앙 시스템을 제공합니다. 일반적인 설정: 각 통화 등급을 구매당 수량1을 부여하는 별도의 스토어 관리형 소모품으로 구성한 다음, 각 제품을 인게임 값에 매핑합니다. 예: “500 coin” 소모품은 스토어 수량을 1로 증가시킵니다. 소비 후 스토어 수량은 0으로 돌아가고 서비스는 500 코인을 크레딧합니다.
스토어 관리형 소모품은 구매 시 스토어 수량에 전체 값을 직접 부여할 수 있습니다(예: 구매당 500). 해당 모델에서는 스토어가 잔액 증가를 추적하고, 사용자가 게임에서 통화를 지출할 때 서비스가 수량을 차감합니다. 그러나 모든 등급을 단일 제품 ID 아래의 SKU로 두는 것은 등급별 프로모션 가격 및 5x5 리딤 토큰과 같은 기능을 제한합니다. 인게임 통화 제공 모범 사례를 참고하세요.
소비 검증을 위한 중복 시스템으로 TrackingId 사용
각 소비 요청에TrackingId를 포함하세요. 응답이 손실되는 경우 동일한 TrackingId, 사용자, productId, 수량으로 재시도하여 원래 소비가 성공했는지 확인합니다. 이 재시도 요청은 안전한 재시도를 허용하면서 이중 부여를 방지합니다.
다음 흐름은 재시도 안전한 소비 패턴을 보여줍니다.
Product A(500 인게임 코인)는 스토어 내에서 수량 1을 부여하도록 구성된 소모품입니다.
- 사용자가 Product A를 구매하고 이제 쿼리 서비스를 호출할 때 제품 수량이
1이 됩니다. - 게임 서비스가 Microsoft Store 쿼리 API 내에서 사용자의 소모품 잔액을 쿼리하고 사용자의 잔액이
1임을 확인합니다. - 게임 서비스가 TrackingID를 생성하고, 제품 수량 하나를 소비하기 위한 소비 요청을 만들고, 요청 정보를 보류 중인 트랜잭션 목록에 추가합니다.
- 게임 서비스가 요청을 Microsoft Store 소비 API에 전송합니다.
- 게임 서비스가 소비 API 응답을 얻지 못합니다(네트워크 패킷 손실, 서비스 중단, 전원 손실 등). 이 시점에서 서비스는 트랜잭션이 완료되었는지 확인할 수 없습니다. 사용자가 중단 중에 재구매한 경우 인벤토리만 쿼리하는 것은 모호할 수 있습니다. 보류 중인 트랜잭션 목록을 사용하고 동일한 요청 값으로 재시도합니다.
- 게임 서비스가 소비 요청을 재시도해야 할 시점을 결정합니다.
- 게임 서비스가 동일한 사용자, ProductId, TrackingId, 수량을 사용해 소비 요청을 다시 만듭니다.
- 게임 서비스가 요청을 Microsoft Store 소비 API에 전송합니다.
- 게임 서비스가 요청이 성공했고 새 사용자 잔액이 ‘0’이라는 응답을 받습니다.
- 게임 서비스가 서버에서 추적되는 사용자의 통화 잔액에 500 코인을 추가합니다.
- 게임 서비스가 소비, 검증, 사용자에게 올바른 인게임 통화 부여가 완료되었으므로 보류 중인 트랜잭션 목록에서 소비 요청을 제거합니다.
이전 트랜잭션 요청을 검증할 때의 Microsoft Store Consume API 동작
다른 값으로 요청이 도착하면 API는 이를 새 소비 요청으로 처리합니다. 동일한TrackingId, 사용자, 수량, productId로 재시도가 감지되면 API는 두 번째로 소비하지 않습니다. 대신 현재 남은 잔액과 함께 성공 응답을 반환합니다. 이러한 동작 때문에 요청 값이 동일한 한 시간 초과된 요청을 재생하는 것은 안전합니다.
소비 API에 X-Token 인증을 사용하는 경우, 새 X-Token이 이전 요청과 동일한 XBOX 사용자에 대한 것인 한 X-Token을 업데이트하고 새로 받을 수 있습니다.
Clawback 이벤트 서비스로 소모품 반품 및 환불 사기 완화
소모품 제품의 남용 및 사기 반품 또는 환불을 방지하기 위해 서비스에서 Clawback 이벤트 서비스를 사용해야 합니다. Clawback을 사용하면 소모품 제품이 반품 또는 환불될 때 서비스가 이벤트를 받을 수 있습니다. 서비스는 해당 소모품에 대한 사용자 계정의 추가된 값을 제거해야 합니다. Clawback 이벤트에 대해 조치를 취하려면 collections.mp.microsoft.com/v8.0/collections/consume 소비 요청에서"includeOrderIds": TRUE 옵션을 사용해야 합니다. 서비스는 다음 변수를 사용해 API 응답의 소비 트랜잭션 데이터를 저장해야 합니다.
이 추적 데이터베이스는 Clawback 큐 온보딩 이전에 조기에 설정하세요. 조기 데이터는 향후 조정을 위한 이력 트랜잭션과 Clawback 처리 효과를 측정하기 위한 깨끗한 기준선을 제공합니다.
자세한 내용은 서비스에서 환불 및 charge-back 관리를 참고하세요.