Skip to main content
타이틀이 Game Pass에 참여하는 경우, 서비스는 collections.mp.microsoft.com/v9.0/collections/publisherQuery API를 사용해 활성 구독자 상태를 확인하고 인게임 보상 및 특전을 부여할 수 있습니다. Game Pass 상태를 쿼리하기 전에 게시자가 확인하려는 등급에 대해 권한을 부여받아야 합니다. Developer Partner Manager 또는 Microsoft 담당자를 통해 이 권한을 요청하세요.

클라이언트 라이선스 검사에서의 Game Pass 라이선스

Game Pass 사용 권한은 게임 클라이언트에서 감지할 수 없습니다. 사용자가 Game Pass를 통해 타이틀에 대한 사용 권한을 부여받은 경우, XStoreQueryGameLicenseAsync는 직접 구매와 마찬가지로 isActive = true인 라이선스를 반환합니다. XStoreGameLicense 구조체에는 라이선스 획득 방식을 식별하는 필드가 포함되어 있지 않습니다. 예를 들어 원격 분석 목적으로 사용자가 타이틀을 획득한 방식을 기록하려면, 클라이언트에서 자체 서비스로 사용자의 ID를 전송하세요. 그런 다음 서비스에서 publisherQuery API를 호출하고 acquisitionType을 확인합니다. 값이 Recurring이면 Game Pass 사용 권한을 나타내고, Single이면 직접 소유를 나타냅니다.

권한 있는 게시자와 권한 없는 게시자의 응답 데이터 동작

게시자가 권한이 없는 경우 Game Pass로 부여된 항목은 직접 소유한 사용 권한으로 표시됩니다. 예를 들어 acquisitionTypeSingle로 표시되고 satisfiedByProductIds에 Game Pass ProductId가 나타나지 않습니다. 권한이 있는 게시자의 경우 활성 Game Pass 구독만 반환됩니다. 사용자의 Game Pass 구독이 취소되거나 종료되면 이후 쿼리에 더 이상 Game Pass 정보가 포함되지 않습니다. 또한 EndDate는 최대값으로 정규화되어 구독 종료 감지에 사용할 수 없습니다.

서버 간 사용 권한 결과에서의 Game Pass 출시일 지연

타이틀 또는 추가 기능이 Game Pass에 라이브되면 클라이언트 사용 가능성과 publisherQuery 가시성 사이에 지연이 예상됩니다. 이 동작은 스토어 시스템 전반에 걸친 서로 다른 캐시 새로 고침 간격 때문입니다. 실제로 로컬 라이선싱이 일반적으로 먼저 업데이트되고 publisherQuery는 2~3시간 늦어질 수 있습니다. Game Pass ProductId의 직접 확인은 영향을 받지 않으며, 지연은 주로 satisfying 사용 권한을 통해 부여된 항목에 대한 것입니다.

개발 샌드박스에서 Game Pass 구독 테스트

XBOX Game Pass 등급은 개발 샌드박스 내의 XBOX Store 앱에서 검색하여 활성화하고 액세스할 수 있어야 합니다. XBOX 테스트 계정은 테스트 신용카드로 만들어지며 샌드박스에서 Game Pass 등급을 구독할 수 있습니다. 샌드박스에서 Game Pass 등급을 찾을 수 없는 경우 Developer Partner Manager 또는 Microsoft 담당자에게 지원을 요청하세요.
Game Pass 구독 상태는 샌드박스 간에 이전되지 않습니다. 샌드박스의 테스트 계정에 Game Pass를 추가할 때, Game Pass 또는 기타 커머스 관련 테스트나 디버깅을 위해 해당 테스트 계정을 다른 샌드박스로 이동하지 마세요.

Game Pass 구독 상태 요청

사용자의 Game Pass 구독 상태를 요청하려면 표에서 확인할 권한이 있는 구독 등급의 해당 ProductId를 쿼리 요청의 productSkuIds 목록에 추가합니다. 사용자가 요청한 등급의 구독을 보유하고 있는 경우, 쿼리 응답에 해당 Game Pass 구독 등급의 ProductId를 가진 항목이 포함됩니다.

상위 등급에 포함된 등급 요청 동작

일부 Game Pass 등급은 구독자가 상위 등급을 보유한 경우 포함됩니다. 상위 등급에 포함된 권한 있는 등급은 사용자가 상위 등급을 구독할 때 반환됩니다. 예: 게시자가 XBOX Game Pass Essential에 대한 권한이 있습니다. 사용자가 XBOX Game Pass Ultimate를 보유한 경우 모든 Game Pass ProductId를 쿼리하면 publisherQuery는 XBOX Game Pass Essential에 대한 결과만 반환합니다. 게시자가 다른 등급을 볼 수 있는 액세스 권한이 있다면 해당 등급도 반환됩니다.
XBOX Game Pass (Starter Edition)는 상속에 대한 예외이며 독립 실행형 등급입니다. 다른 어떤 등급에도 포함되지 않습니다.

Game Pass 구독자에게 인게임 특전 부여

구독자에게 인게임 특전과 혜택을 부여하는 데 필요한 최하위 Game Pass 등급에 대한 액세스 권한을 요청하는 것을 권장합니다. 예: 콘솔의 모든 Game Pass 구독자에게 인게임 보상을 부여합니다. Premium 및 Ultimate에 Essential이 포함되어 있으므로 XBOX Game Pass Essential(CFQ7TTC0K5DJ)에 대한 액세스만 있으면 됩니다.

satisfiedByProductIds로 Game Pass 구독을 통해 권한 있는 제품 감지

권한 부여 후에는 satisfiedByProductIdsacquisitionType 값을 확인해 Game Pass에서 파생된 사용 권한을 식별합니다. Game Pass 기반 사용 권한은 acquisitionTypeRecurring이고, satisfiedByProductIds에는 권한 있는 가장 높은 Game Pass 등급의 ProductID가 포함됩니다.
excludeDuplicates 필터 옵션을 사용하는 경우, 사용자가 타이틀을 직접 소유하고 있으면 Game Pass 관련 사용 권한이 필터링됩니다.
Game Pass productID에 대해 항목의 satisfiedByProductIds를 확인하면 항목이 Game Pass를 통해 부여된 것인지 알 수 있지만, 사용자가 Game Pass 회원인지 판단하기에는 충분하지 않습니다. 따라서 사용자의 Game Pass 구독 상태를 확인할 때는 요청의 productSkuIds에 Game Pass ProductId 값을 포함하는 것이 가장 좋습니다.

XBOX Game Pass를 사용한 중복 항목 예

사용자가 동일한 제품에 대한 직접 소유권과 Game Pass 사용 권한을 모두 갖고 있는 경우, excludeDuplicatesfalse일 때 두 개의 항목이 나타날 수 있습니다. excludeDuplicatestrue일 때는 직접 구매 항목이 반환됩니다. 전체 중복 해결 규칙 및 소스 우선순위 동작에 대해서는 응답에서 중복 항목 이해하기를 참고하세요.

XBOX Game Pass Essential 구독 상태 요청 예

XBOX Game Pass Essential 응답 예

Game Pass Essential 구독을 통해 부여된 게임의 요청 예

Game Pass Essential 구독을 통해 부여된 게임의 응답 예

참고

커머스 개요 XStore API 참조
마지막 수정일 2026년 8월 31일