사용 권한
사용 권한은 게임, 구독, 추가 기능을 포함한 디지털 제품에 액세스하고 사용할 수 있는 고객의 권리를 나타냅니다. Microsoft Store에서 이루어진 모든 구매 또는 리딤은 Microsoft의 collections 서비스에서 추적하는 하나 이상의 사용 권한을 발생시킵니다. 사용 권한과 함께 작동하는 제품 유형에 대한 자세한 내용은 올바른 제품 유형 선택을 참고하세요. 제품 사용 권한은 플레이어의 제품 직접 구매, 충족 제품(예: 번들 또는 구독) 구매, 또는 다른 사용자의 공유 사용 권한을 통해 부여될 수 있습니다. 사용 권한은 active, inactive, expired, revoked의 여러 상태를 지원합니다. 게임 클라이언트와 서비스는 플레이어의 사용 권한을 쿼리할 수 있지만 결과는 다를 수 있습니다.- 클라이언트 API는 활성 상태의 사용 권한만 반환할 수 있지만 모든 사용 권한 유형(direct, shared, satisfying)을 반환할 수 있습니다. 그러나 사용 권한의 유형은 클라이언트에는 보이지 않습니다.
- 서비스 API는 모든 상태의 사용 권한을 반환할 수 있지만, 디바이스 컨텍스트가 없으므로 공유 사용 권한을 반환할 수 없습니다. 그러나 직접 사용 권한과 충족 사용 권한을 구분할 수 있습니다.
사용 권한 공유 및 오프라인 가용성
- 제품을 소유한 계정이 현재 디바이스를 오프라인 디바이스(콘솔에서는 Home XBOX, PC에서는 오프라인 권한(Offline permissions))로 지정하면 디바이스의 다른 계정과 소모품이 아닌 사용 권한을 공유합니다.
- 소모품 사용 권한은 구매 계정에 연결된 직접 사용 권한이며 디바이스의 다른 계정과 공유할 수 없습니다.
- 모든 사용 권한 쿼리는 온라인 연결이 필요합니다. 오프라인 상태일 때 플레이어의 액세스 권한을 결정하는 데 사용 권한을 사용하지 마세요. 대신 라이선싱을 사용하세요.
게임 클라이언트에서 사용 권한 사용
클라이언트가 카탈로그 요청을 보낼 때마다 반환된 각 XStoreProduct의IsInUserCollection 속성을 채우기 위해 collections 서비스에 해당 호출을 보냅니다. IsInUserCollection이 true이면 플레이어에게 제품 사용 권한이 있음을 나타냅니다. 인게임 스토어프런트에서 어떤 제품이 구매 가능하거나 이미 플레이어에게 ‘소유된’ 것으로 표시될지 결정할 때 이 값을 사용하세요.
다음 방법을 통해 추가 기능 콘텐츠에 대한 XStoreProduct 세부 정보를 검색할 수 있습니다.
- XStoreQueryAssociatedProductsAsync / Result - 구매 가능한 제품만 반환합니다. 결과에는 숨겨져 있거나 번들에서만 사용 가능하거나 Microsoft Store에서 더 이상 구매할 수 없는 제품은 포함되지 않습니다.
- XStoreQueryProductsAsync / Result - 특정 제품을 쿼리하는 데 사용됩니다. 단일 제품 또는 제품 하위 집합의 사용 권한 변경을 확인하려면 이 함수를 사용하세요.
게임 서비스에서 사용 권한 사용
게임 서비스를 사용하면 사용 권한을 쿼리하고 관리하기 위한 더 고급 옵션을 사용할 수 있습니다. 다음은 가능한 것의 작은 예입니다.- 전체 게시자 카탈로그 전반에 걸쳐 사용자의 사용 권한을 쿼리합니다.
- 직접 사용 권한과 충족 사용 권한을 구분하여 플레이어가 콘텐츠를 획득하는 방법을 더 잘 이해합니다.
- 미래 시작 날짜가 있는 비활성 사용 권한을 쿼리해 아직 사전 예약 상태인 구매를 감지합니다.
- 강력한 크로스 플랫폼 소모품 생태계를 관리합니다(소모품 기반 생태계 참고).
- Clawback 서비스로 제품이 환불될 때를 감지합니다(서비스에서 환불 및 charge-back 관리 참고).
- XBOX Game Pass 구독 상태를 감지해 게임에서 구독자에게 특전을 부여합니다(서비스에서 XBOX Game Pass 구독 액세스 감지 참고).
사용 권한 관련 고려 사항
- PC의 개발자 샌드박스에서 작업할 때 클라이언트는 XBOX App에 로그인한 계정을 대신하여 모든 사용 권한 쿼리를 수행합니다.
- PC의 RETAIL에서 작업할 때 클라이언트는 Microsoft Store에 로그인한 계정을 대신하여 모든 사용 권한 쿼리를 수행합니다. 게임에 로그인한 계정이 Microsoft Store에 로그인한 계정과 일치하지 않을 때 계정 불일치 시나리오가 발생할 수 있습니다(자세한 내용은 스토어 계정 불일치 처리 참고).
라이선싱
라이선스는 사용자가 디바이스의 콘텐츠에 액세스할 권리를 확인하는 디지털 키입니다. 사용자는 라이선스가 획득되기 전에 제품 사용 권한이 있거나 제품(게임 및 패키지가 있는 Durable)이 포함된 디스크를 삽입해야 합니다. Durable(패키지 유무에 관계없이)로 작업할 때는 공유, 동시성, 오프라인 가용성에 대한 기대를 충족하기 위해 라이선싱을 사용하세요(게임의 제품 공유 모델 참고). 라이선스는 게임에서 사용하는 라이선스 모델에 따라 디바이스 제한과 동시성 검사를 받습니다(개방형 및 제한적 라이선싱 참고). 플레이어가 제품에 대한 활성 사용 권한이 있더라도 디바이스에서 사용할 유효한 라이선스를 획득하지 못할 수 있습니다.라이선스 공유 및 오프라인 가용성
다음 조건 중 하나 이상이 참이면 디바이스에서 라이선스 공유가 발생합니다.- 소유자 계정이 로그인되어 있고 온라인 연결이 설정된 상태에서 게임이 라이선스를 획득했습니다.
- 게임이 소유자 계정이 오프라인 디바이스(콘솔에서는 Home XBOX, PC에서는 오프라인 권한)로 설정된 상태에서 오프라인 라이선스를 획득했습니다. 이 시나리오에서는 라이선스를 디바이스의 다른 계정과 공유하기 위해 소유 계정이 디바이스에 로그인할 필요가 없습니다.
- 플레이어가 DLC가 포함된 디스크를 삽입하고(패키지가 있는 Durable) DLC가 디바이스에 설치되어 있습니다.
- 제품을 소유한 계정이 현재 디바이스를 ‘오프라인’ 디바이스(콘솔에서는 Home XBOX, PC에서는 오프라인 권한)로 지정합니다. 오프라인 지정이 활성화된 후 게임은 온라인 상태에서 Durable 제품의 라이선스를 획득해야 합니다. 다음번 게임 실행 시 오프라인 지원 라이선스가 획득됩니다.
- 플레이어가 DLC가 포함된 디스크를 삽입하고(패키지가 있는 Durable) DLC가 디바이스에 설치되어 있습니다.
게임 클라이언트에서 라이선스 사용
다음 흐름을 사용해 Durable(패키지 유무에 관계없이)에 대한 라이선스를 부여할 수 있습니다.- XStoreCanAcquireLicenseForStoreIdAsync / Result는 동시성 검사 없이 라이선스를 미리 봅니다. XStoreCanLicenseStatus가
Licensable이면 게임이 durable 라이선스를 획득할 수 있습니다. 이 미리 보기 검사는 온라인 연결이 필요합니다. - XStoreAcquireLicenseForDurablesAsync / Result는 디바이스에 라이선스가 없거나 현재 라이선스가 만료된 경우 라이선스를 획득하기 위해 라이선싱 서비스를 호출합니다. 디바이스에 이미 제품에 대한 활성 라이선스가 있거나 이 API가 오프라인에서 호출된 경우 캐시된 라이선스가 반환됩니다. 캐시된 라이선스가 반환된 경우 현재 플레이어에게 유효하지 않을 수 있습니다.
- 게임에서 콘텐츠를 잠금 해제하기 전에 항상 XStoreIsLicenseValid를 호출해 라이선스가 유효한지 확인하세요.
- 유효한 라이선스를 획득한 경우 XStoreRegisterPackageLicenseLost를 사용해 라이선스 손실 이벤트를 수신합니다. 라이선스가 손실되면 라이선스를 다시 획득해 보세요. 라이선스를 다시 획득할 수 없는 경우 플레이어의 콘텐츠 액세스를 차단할지 여부(게임 디자인에 따라)와 시점을 결정하세요.
- 라이선스 손실 이벤트를 처리한 후 XStoreUnregisterPackageLicenseLost를 호출하고 XStoreCloseLicenseHandle를 호출해 이전 라이선스 핸들을 해제합니다.
게임 서비스에서 라이선스 사용
라이선스는 디바이스에 연결되어 있으며 게임 서비스에서 쿼리할 수 없습니다. 그러나 클라이언트는 XStoreQueryLicenseTokenAsync / Result를 호출해 게임 서비스를 사용한 추가 유효성 검사를 제공할 수 있습니다. 자세한 내용은 라이선스 토큰 사용을 참고하세요.라이선싱 관련 고려 사항
- 구매가 완료된 시점과 새 라이선스를 획득할 수 있는 시점 사이에 지연이 있을 수 있습니다. 사용자의 사용 권한 변경을 확인하고 Durable 제품에 대한 새 사용 권한이 추가된 후 라이선스를 획득하세요.
- 사이드로드된 패키지를 배포할 때는 패키지가 있는 Durable에 대해 테스트 라이선스가 자동으로 부여됩니다. 패키지가 있는 Durable에 대한 라이선싱 시나리오를 테스트하려면 대신 라이선스 재정의 또는 스토어 설치된 패키지를 사용하세요. 자세한 내용은 라이선스 테스트 활성화를 참고하세요.
- 게임이 Durable 라이선스를 획득하면 라이선스가 디바이스에 캐시됩니다. 시스템이 라이선스 새로 고침을 트리거할 때까지 라이선스는 캐시에서 가져옵니다(강제 새로 고침을 할 수 있는 API는 없음). XStoreAcquireLicense*에 대한 반복 호출은 서비스가 아닌 디바이스 캐시를 확인합니다.
- 라이선스 손실 콜백은 시스템이 다른 계정에 속한 캐시된 라이선스를 현재 플레이어에게 잘못 반환하는 경우를 감지하는 데 도움이 될 수 있습니다. 이러한 경우 라이선스 손실 이벤트가 즉시 발생하고, XStoreAcquireLicense*가 다시 호출되면 새로운 라이선스가 제공됩니다.
- 라이선스 공유 및 캐싱으로 인해 테스트 시스템이 깨끗하지 않은 상태로 남을 수 있습니다. 자세한 내용은 XStore 개발 문제 해결을 참고하세요.
샘플 리소스
플레이어의 사용 권한을 쿼리하고 durable 라이선스를 획득하는 방법을 시연하는 샘플 코드는 다음 리소스를 참고하세요.- InGameStore Sample (GitHub): 제품 검색, 구매, 사용 권한, Durables 라이선싱을 포함한 XStore 기능을 시연하는 C++ 샘플입니다.
- DownloadableContent Sample (GitHub): 패키지된 Durables 열거 및 라이선싱을 포함한 XStore 및 XPackage 기능을 시연하는 C++ 샘플입니다.
- UnityInGameStore Sample (GitHub): Unity 게임 엔진과 ‘Microsoft GDK API 패키지’를 사용해 XStore 기능을 시연하는 C# 샘플입니다.
참조 API 문서
- XStore (API 내용)
- 함수
- XStoreQueryAssociatedProductsAsync
- Result
- XStoreQueryProductsAsync
- Result
- XStoreQueryEntitledProductsAsync
- Result
- XStoreCanAcquireLicenseForStoreIdAsync
- Result
- XStoreAcquireLicenseForDurablesAsync
- Result
- XStoreIsLicenseValid
- XStoreRegisterPackageLicenseLost
- XStoreUnregisterPackageLicenseLost
- XStoreCloseLicenseHandle
- XStoreCanAcquireLicenseForPackageAsync
- Result
- XStoreAcquireLicenseForPackageAsync
- Result
- XStoreQueryLicenseTokenAsync
- Result
- 구조체
- 함수
- XPackage (API 내용)
참고
커머스 개요XStore API 참조