서비스에서 Xbox Game Pass 구독 액세스 감지
사용자의 타이틀이 Xbox Game Pass 또는 PC Game Pass에 참여하고 있다면 타이틀 참여의 일환으로 Game Pass 가입자에게 특정 게임 내 혜택을 부여할 수 있습니다. collections.mp.microsoft.com/v9.0/collections/publisherQuery API는 사용자가 Xbox Game Pass 서비스 및 해당 구독 계층의 가입자인지 확인할 수 있는 능력을 제공합니다. 서비스가 사용자의 Xbox Game Pass 상태를 얻으려면 배급업체가 사용자가 액세스해야 하는 Xbox Game Pass의 계층에 따라 이 정보를 신청하고 인증을 받아야 합니다. Xbox Game Pass 구독 정보에 대한 사용 권한 요청은 승인 프로세스를 시작할 개발자 파트너 관리자 또는 Microsoft 담당자를 통해 수행됩니다.
권한 있는 배급업체 및 권한 없는 배급업체에 대한 응답 데이터 동작
배급업체가 Xbox Game Pass 구독 상태를 볼 수 있는 권한이 없는 경우 Game Pass를 통해 자격이 부여된 제품이 직접 소유한 디지털 자격으로 표시됩니다. acquisitionType은 'Single'이 되며 Game Pass ProductId는 satisfiedByProductIds 목록에 나타나지 않습니다.
권한 있는 배급업체의 경우 활성 Game Pass 구독만 반환됩니다. 사용자의 Game Pass 구독이 취소되거나 종료되면 쿼리 결과에 더 이상 Game Pass 정보가 포함되지 않습니다. 또한 StartDate 및 EndDate 값이 항상 최소값과 최대값이 되도록 각각 수정됩니다. 이 값을 사용하여 사용자의 구독이 언제 시작되었는지 또는 언제 종료되는지 알 수 없습니다.
서버-서버 권한 결과의 Game Pass 릴리스 일 지연
타이틀 또는 DLC가 Game Pass에 포함되도록 예약된 경우 사용자가 콘텐츠를 시작할 수 있는 순간과 PublisherQuery 호출 시 타이틀 또는 DLC에 대한 결과가 표시되는 시점 사이에 지연이 발생합니다. 이는 다른 저장소 시스템에서 사용하는 카탈로그 캐시가 서로 다른 간격으로 업데이트되기 때문입니다. Game Pass 변경 내용이 카탈로그에 게시되면 로컬 라이선스 서비스는 일반적으로 업데이트된 정보를 먼저 받은 다음 PublisherQuery에서 사용하는 캐시를 2~3시간 이내에 가져옵니다. 따라서 출시일에는 사용자에게 라이선스가 부여되고 클라이언트에서 게임을 시작할 수 있는 몇 시간이 있지만 PublisherQuery에 대한 서버 간 호출은 아직 특정 타이틀 제품에 대한 결과를 반환하지 않습니다. Game Pass 계층의 제품 ID를 확인하는 것은 이에 영향을 받지 않으며, 게임 패스에 만족스러운 자격 또는 포함된 항목으로 추가된 항목만 영향을 받습니다.
Game Pass 구독 상태 요청
사용자의 Xbox Game Pass 구독 상태를 요청하려면 해당 쿼리 요청의 productSkuIds 목록(아래 표 참조)에 볼 수 있는 권한이 있는 구독 계층의 ProductId를 추가하십시오.
| 구독 계층 | ProductID |
|---|---|
| Xbox Game Pass | CFQ7TTC0K6L8 |
| PC Game Pass | CFQ7TTC0KGQ8 |
| Xbox Game Pass Ultimate | CFQ7TTC0KHS0 |
사용자에게 귀하가 요청한 계층에 구독이 있는 경우 쿼리 응답에는 해당 Game Pass 구독 계층의 ProductId와 함께 항목이 포함됩니다. 중복 자격을 필터링하면 직접 구입한 항목 뒤에 Game Pass 자격이 표시되는 항목이 숨겨질 수 있으므로 사용자가 Game Pass 구독자인지를 정확하게 확인할 수 있는 권장 방법입니다.(다음 섹션의 예 참조).
Xbox Game Pass Ultimate 구독자는 세 가지 구독 계층을 모두 사용할 수 있으며 배급업체가 볼 수 있는 해당 계층 수준을 반환합니다.
예: 우리 배급업체는 PC Game Pass 계층 정보 전용만 사용할 수 있습니다. Xbox Game Pass Ultimate을 구독하는 사용자는 우리의 계층 액세스에 따라 PC Game Pass 결과 항목만 반환할 수 있습니다. 우리의 배급업체가 Xbox Game Pass Ultimate 정보를 볼 수 있는 권한도 있다면 쿼리 응답에 반환되는 항목에 Xbox Game Pass Ultimate ProductId가 있을 것입니다.
satisfiedByProductIds로 Xbox Game Pass 구독을 통해 자격을 얻은 제품 감지
배급업체가 Game Pass 구독 정보를 볼 수 있는 권한이 있으면, Xbox Game Pass를 통해 사용자에게 자격이 부여된 배급업체의 제품이 satisfiedByProductIds 및 acquisitionType 필드에 의해 식별될 수 있습니다. Xbox Game Pass 구독 계층을 통해 자격을 부여 받은 항목은 'Recurring(반복)' acquisitionType을 갖게 되며, 권한을 부여 받은 해당되는 Xbox Game Pass ProductId는 satisfiedByProductIds 목록에 속하게 됩니다.
그러나 excludeDuplicates 필터 옵션을 사용하면 사용자가 직접 타이틀을 소유하는 경우 Game Pass 관련 자격이 필터링됩니다. 따라서, 요청의 ProductSkuIds 배열에서 Xbox Game Pass ProductId를 항상 요청하는 것이 Xbox Game Pass 구독자를 확인할 때 권장되는 방법입니다.
Xbox Game Pass의 중복 항목 예제
배급업체는 쿼리 매개 변수에서 Game Pass 정보를 볼 수 있습니다. 사용자에게 게임 A에 대한 액세스 권한을 제공하는 활성 Xbox Game Pass 구독이 있습니다. 몇 주 동안 게임을 플레이한 후 사용자는 게임 A를 영구적으로 소유할 수 있도록 Xbox Game Pass 할인을 통해 게임 A를 구매하기로 결정합니다. 이렇게 하면 publisherQuery 결과에 Game A의 ProductId에 대한 두 개의 항목이 반환됩니다(동일한 SKU일 수 있음). 한 항목은 Game Pass ProductId(SafulByProductId에 Game Pass ProductId 포함)를 통해 자격이 부여되는 것으로 표시됩니다. AcquisitionType은 'Recurring(반복)'입니다. 다른 항목은 비어 있는 satisfiedByProductIds 목록을 가진 직접 구매를 나타내는 ‘Single(단일)’ acquisitionType을 갖게 됩니다(구입한 것이 게임 번들이 아닌 한).
요청 본문에서 excludeDuplicates가 활성화되어 있으면, 해당 항목의 직접 구매 버전만 직접 구매로 반환되거나 게임 번들이 구독 자격보다 우선하게 됩니다.
자세한 내용은 배급업체 쿼리 응답의 중복 항목 이해를 참조하십시오.
Xbox Game Pass 구독 상태 요청 예제
POST https://collections.mp.microsoft.com/v9.0/collections/PublisherQuery HTTP/1.1
{authorization header}
User-Agent: {identifier string of your service}
Content-Type: application/json;
Host: collections.mp.microsoft.com
{
"maxPageSize": 100,
"excludeDuplicates": true,
"validityType": "All",
"productSkuIds": [
{"productId": "CFQ7TTC0K6L8"}
],
"beneficiaries": [
{
"identitytype": "b2b",
"identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4N0YwNEFDQzIzRDdCQ0E2M...",
"localTicketReference": ""
}
],
"sbx":"XDKS.1"
}
Xbox Game Pass의 응답 예제
HTTP/1.1 200 OK
Date: Mon, 15 Aug 2022 18:40:32 GMT
Content-Type: application/json; charset=utf-8
Server: Kestrel
Content-Length: 602
MS-CorrelationId: 5ec99421-7fa8-457e-87c1-edf16297528e
MS-RequestId: a604aca2-f60d-4de5-993f-125a57dcabdd
MS-CV: pjtLxeR5BUOY5n.0
X-Content-Type-Options: nosniff
MS-ServerId: c9cf4cd5b-4dhs
{
"items": [
{
"acquiredDate": "2022-08-15T18:29:24.2131463+00:00",
"acquisitionType": "Recurring",
"endDate": "9999-12-31T23:59:59.9999999+00:00",
"id": "a1702e2c6cff4e0095b3c51d06d9fac9",
"modifiedDate": "2022-08-15T18:29:24.2153924+00:00",
"productId": "CFQ7TTC0K6L8",
"productKind": "Pass",
"quantity": 1,
"recurrenceData": "mdr:0:9ee54c66dc2a49ca81bd2c3eaf148826:a118bfe9-8175-4407-9d14-b2be4af30acd",
"satisfiedByProductIds": [],
"skuId": "",
"startDate": "2022-08-15T00:00:00+00:00",
"status": "Active",
"tags": [],
"transactionId": "a118bfe9-8175-4407-9d14-b2be4af30acd",
"trialData": {
"isInTrialPeriod": false,
"isTrial": false
}
}
]
}