서비스의 소모성 제품 관리

아티클
06/20/2024

타이틀이 소모품 기반 에코시스템을 사용하면 타이틀 내에서 소모성 트랜잭션을 검증하고 관리하는 백엔드 서비스를 개발하는 것이 가장 좋습니다. 이를 통해 신뢰할 수 있는 서비스와 Xbox 스토어 서비스 API 간의 소모품에 대한 안전한 통신 및 관리가 가능합니다. 이러한 트랜잭션을 관리하기 위해 클라이언트에 의존하는 것은 에코시스템을 속이는 공격 벡터로서 위험을 초래합니다. 예를 들어 사용자는 트래픽을 조작하거나 클라이언트에서 패킷을 삭제하여 소비 호출에 문제를 일으킬 수 있습니다. 이전의 경우에는 게임 서비스에서 직접 관리되고 통제되지 않는 소모품의 도난이나 조작을 초래했습니다.

이 문서에서는 소모성 에코시스템을 관리하기 위해 강력하고 안전한 서비스를 빌드하는 방법을 간략하게 설명합니다. 또한 이 문서에서는 소모성 콘텐츠의 사기와 도난을 막기 위해 소모품의 사용자 환불을 감지하고 관리하는 방법도 설명하고 있습니다.

소모품을 관리하고 환불을 처리하기 위해 서비스에서 다음 Microsoft Store API를 호출합니다. 결과 호출 및 구문 분석에 대한 자세한 내용은 설명서 페이지를 참조하십시오.

Microsoft Store API	함수
collections.mp.microsoft.com/v8.0/collections/consume	사용자가 소유하고 있는 소모품을 사용하거나 충족합니다.
purchase.mp.microsoft.com/v8.0/b2b/orders/query	구매 주문 - 지난 90일 동안 사용자가 구매한 소모품을 보고합니다.
purchase.mp.microsoft.com/v8.0/b2b/clawback/sastoken	제품과 관련된 환불 이벤트에 대해 Clawback 이벤트 서비스 메시지 큐를 쿼리하는 데 사용되는 SAS 토큰을 제공합니다.

Microsoft.StoreServices .NET 라이브러리 및 샘플 활용

이 문서에 설명된 원칙과 흐름을 보여 주기 위해 다음을 제공하는 Microsoft.StoreServices 샘플을 검토합니다.

Microsoft.StoreServices 라이브러리를 사용한 인증 관리 및 Microsoft Store Services 호출.
소모성 제품 관리, 보류 중인 소비 요청 추적, 환불된 구매 조정, 만료된 사용자 저장소 ID 갱신 등에 대한 예제 논리.
이 인증 방법에 대한 Microsoft Entra ID를 구성하고 설정하는 방법에 대한 이 문서의 단계를 포함하는 구성 가이드.
Microsoft.StoreServices(GitHub)
Microsoft.StoreServices 샘플(GitHub)

소모품 관리

소모품 관리 서비스에 권장되는 개요

강력한 소모품 관리 시스템은 다음 기능으로 구성됩니다.

클라이언트로부터 소모성 통화로 게임 내 항목을 사용 또는 구매하라는 요청을 받습니다.
Microsoft Store 서비스 API를 사용하여 인증
Microsoft Store에서 제품의 사용자 잔액 확인
사용자가 트랜잭션에 대해 충분한 소모성 통화를 가지고 있는지 확인합니다(서버 관리됨 또는 스토어 관리됨)
사용자의 잔액 일부를 소비 또는 충족
충족하는지 확인하기 위해 필요한 경우 소비 요청 추적 및 다시 시도
클라이언트의 트랜잭션 요청을 완료합니다.
트랜잭션에서 얻은 결과 또는 항목을 게임 클라이언트에 다시 보고
환불된 소모성 트랜잭션 조정

서비스와 Microsoft Store를 비교하여 사용자 잔액 관리

매장 관리 소모품은 Microsoft Store에서 0이 아닌 잔액을 사용하여 게임 서비스에서 완전히 관리할 수 있습니다. 또는 Microsoft Store에서 사용자가 게임 내 경제에서 무엇을 구매할 때 필요한 수량만 소비하는 방식으로 사용자의 사용가능한 잔액을 관리할 수 있습니다. 단, 개발자가 관리하는 소모품은 게임 서비스에서 관리해야 합니다. 올바른 제품 유형 선택에서 개발자 관리형 및 Microsoft 스토어 관리형 소모품에 대해 자세히 알아보세요.

권장되고 가장 일반적으로 사용되는 방법은 게임 서비스 내에서 사용자의 가용 잔액을 추적하고 관리하는 것입니다. 여기에는 사용자가 게임 소모품의 0이 아닌 잔액을 가지고 있는지 여부를 확인하기 위해 Microsoft Store에 쿼리하는 것이 포함되며, 이러한 양을 0으로 줄이고 게임 서비스에서 추적되는 사용자의 잔액에 해당하는 게임 내 통화를 추가하는 것이 포함됩니다. 이를 통해 파트너는 사용자의 현재 잔액을 확인하고 일단 충족되면 Microsoft Store API에 추가 호출 없이 관리할 수 있습니다. 교차 플랫폼 시나리오에서 이것은 여러 스토어 전면에서 구입한 소모품을 함께 결합하여 허용되는 경우 여러 플랫폼에서 사용할 수 있는 가장 좋은 방법이기도합니다. 또 다른 이점은 사용자에게 문제가 있거나 고객 서비스에 연락해야 하는 경우 코드를 관리하거나 Microsoft Store 내 제품에 부여하지 않고 필요에 따라 서버에서 사용자 잔액에 직접 수량을 추가할 수 있다는 것입니다. 이 방법을 사용하여 스토어 관리 소모품은 일반적으로 사용자 구매당 1개의 양을 부여하도록 구성됩니다. 그런 다음 해당 수량은 해당 제품과 관련이 있는 게임 내 통화 단위 수로 변환됩니다. 예: 사용자가 '500 코인' 소모품을 구매할 때 Microsoft Store API에서 해당 제품의 사용자 수량은 1만큼 증가합니다. 서비스에서 소비되면 수량이 0으로 떨어지고 서비스에서 사용자의 계정 잔액에 500개의 게임 내 코인이 추가됩니다.

또한 스토어 관리 소모품을 구매 시 사용자의 수량에 지정된 값을 부여하도록 구성할 수도 있습니다. 예를 들어 위에서 언급한 '500 코인' 옵션을 설정하여 Microsoft Store API의 사용자 수량을 구매할 때마다 500씩 늘릴 수 있습니다. 사용자가 더 많은 소모성 통화를 구입하고 사용자가 소모품 에코시스템에서 게임 내 아이템을 구매할 때 서비스가 잔액에서 수량을 공제하기 때문에 이 방식으로 스토어가 사용자의 잔액을 관리합니다.

소비 확인을 위해 중복 시스템으로 TrackingIds 사용

서비스에서 제품을 충족 또는 소비할 때 사용자는 소비 요청에 TrackingId를 포함합니다. 이 TrackingId는 트랜잭션 요청이 성공적으로 완료되고 Microsoft Store Services에서 존중되는지 확인하기 위해 중복 폴백으로 사용할 수 있습니다. 예를 들어 서비스에서 소비 요청을 보내지만 응답을 받지 못하면 사용자의 잔액이 요청에서 변경되었는지 여부를 알 수 있는 방법이 없습니다. 이 시나리오에서 서비스는 사용자에게 소모품 아이템을 제공해야하는지 여부를 알 수 없습니다. 동일한 TrackingId, 제거해야 하는 수량 및 productId를 사용하여 동일한 사용자 계정에 대한 요청을 다시 발급하여 Microsoft Store Service가 소비 트랜잭션 결과에 응답하게 할 수 있습니다. 다음은 서비스에서 소모품을 충족시키는 권장 흐름 예제입니다. 이 흐름은 TrackingId를 사용하고 필요한 경우 요청 결과를 확인할 수 있도록 보류 중인 소비 트랜잭션 목록을 유지합니다.

제품 1(500개의 게임 내 코인)은 각 구매와 함께 1개의 수량을 부여하기 위해 구성된 소모품으로, 이것은 우리 서비스 내에서 500 개의 코인으로 바뀝니다.

쿼리 서비스를 호출할 때 사용자는 제품 1을 구입하고 이제 해당 제품에 대해 1개의 수량을 갖습니다.
게임의 서비스 쿼리는 Microsoft Store 쿼리 API 내 사용자의 소모품 잔액이며 사용자의 잔액이 '1'임을 확인합니다.
게임 서비스는 TrackingID를 생성하고, 1개의 제품 수량을 소비하기 위한 소비 요청을 생성하고, 요청 정보를 보류 중인 트랜잭션 목록에 추가합니다.
게임 서비스에서 Microsoft Store 소비 API에 요청 보내기
어떤 현상이 발생하고 게임 서비스에서 소비 API로부터 전혀 응답을 받지 못합니다. 네트워크 패킷 손실, 서비스 중단, 정전 등과 같은 것이 원인일 수 있습니다.

이 시점에서 게임 서비스는 Microsoft 측에서 해당 수량이 실제로 소비되었는지 여부를 알지 못합니다. 재고를 다시 쿼리하면 수량은 여전히 1일 수 있지만 트랜잭션이 이루어지지 않았음을 의미하지는 않습니다. 소비가 성공하여 수량이 0이 될 수 있지만 정전으로 인해 사용자가 다시 소모품을 구입하여 수량을 다시 1로 늘렸을 수 있습니다. 트랙잭션이 진행되었는지 확인하기 위해 위에 추가된 보류 중인 트랜잭션 목록을 사용해야 합니다.

게임 서비스에서 소비 요청을 언제 다시 시도해야 하는지를 확인합니다.
게임 서비스는 동일한 사용자, ProductId, TrackingId 및 수량을 사용하여 소비 요청을 다시 생성합니다.
게임 서비스에서 Microsoft Store 소비 API에 요청을 보냅니다.
게임 서비스는 소비가 성공적이었고 새로운 사용자의 잔액이 '0'이라는 응답을 받습니다.
게임 서비스는 해당 서버에서 추적된 사용자의 통화 잔액에 500 코인을 추가합니다.
게임 서비스는 현재 해당 아이템이 소비 및 검증되고 사용자가 해당 서비스에서 올바른 게임 내 통화를 부여했기 때문에 보류 중인 트랜잭션 목록에서 소비 요청을 제거합니다

이전 트랜잭션 요청을 확인할 때 Microsoft Store 소비 API 동작

소비 API가 이전에 수신되는 요청을 본 적이 없으면(TrackingID, 사용자, 수량, ProductID) 이것을 새로운 수신 요청으로 간주하며 시스템 내 사용자의 현재 소모품 잔액에 따라 적절하게 완료합니다.

소비 API가 이것을 이전에 소비된 트랜잭션(동일한 TrackingId, 사용자, 수량, ProductId)의 재시도라고 판단하면 사용자의 잔액에서 해당 아이템을 두 번 소비하지 않습니다. 그러나 서비스는 요청된 소비가 완료되었으며 사용자의 현재 잔여 잔액을 나타내는 형식으로 다시 응답합니다. 따라서 응답을 받지 않은 경우 소비 요청을 다시 시도하거나 다시 재생하여 전달되었는지 확인하는 것이 항상 안전합니다. 하지만 사용자, TrackingId, 수량, 제품이 이전 호출과 정확하게 같은지 확인해야 합니다. X-토큰 인증을 소비 API에 사용하는 경우 이전 요청과 동일한 Xbox 사용자에 대한 새로운 X-토큰이 있는 한, 새로운 X-토큰을 업데이트하고 얻을 수 있습니다. X-Token은 새 토큰을 받기 전에 4시간 동안만 유효하기 때문에 필요할 수 있습니다.

Clawback 이벤트 서비스로 소모품 반품 및 환불 사기 완화

소모성 제품의 남용 및 사기성 반품/환불을 방지하려면 서비스를 Clawback 이벤트 서비스와 통합하는 것이 좋습니다. 이렇게 하면 사용자가 구매한 소모성 제품이 반환되거나 환불된 경우 서비스에서 이벤트를 받을 수 있으므로 서비스는 서비스 쪽에서 소모품의 부가 가치를 제거해야 합니다.

Clawback 이벤트에 대한 작업을 수행하려면 collections.mp.microsoft.com/v8.0/collections/consume에 대한 소비 요청에서 "includeOrderIds": TRUE 옵션을 사용해야 합니다. 그러면 소모성 관리 서비스에서 시스템, OrderID, LineItemOrderId, ProductID 및 기타 유용한 정보를 포함한 트랜잭션 레코드를 유지해야 합니다. 그런 다음, 다시 게시 이벤트의 OrderID 및 LineItemOrderID 쌍을 사용하여 완료된 트랜잭션에서 일치하는 항목을 검색할 수 있습니다.

자세한 내용은 서비스에서 환불 및 차지백 관리를 참조하세요.