XBOX 서비스 사용자 권한의 클라이언트 측 사용

​

목차

• 사전 준비 사항
• 권한 및 업셀에 대한 클라이언트 측 처리 및 플레이어 경험
• 앱 측 권한 처리에 대한 모범 사례
• 게임에서 권한 기반 접근 제어 테스트
• 확인할 권한 ID

​

사전 준비 사항

​

권한 및 업셀에 대한 클라이언트 측 처리 및 플레이어 경험

1. 플레이어에게 멀티플레이어 세션을 시작하는 옵션이 표시되고, UI에서 적절한 옵션을 선택하여 경기 시작을 시도합니다.
2. 게임은 XUserCheckPrivilege API를 사용하여 “힌트”를 확인합니다.
   • 힌트가 있으면 플레이어에게 권한이 있다고 가정하고 진행합니다.
   • 힌트가 없으면 다음 단계로 이동합니다.

   [!NOTE] XBOX 서비스 API는 XToken에 권한이 없어 기능에 대한 접근이 거부되면 상태 코드 403(HTTP_E_STATUS_FORBIDDEN)을 반환합니다. XBOX 서비스의 모든 엔드포인트는 필요에 따라 권한 기반 접근 제어를 시행합니다.

3. 실패 코드에 대한 응답으로, 게임은 해결하려는 권한에 대한 적절한 권한 ID로 XUserResolvePrivilegeWithUiAsync를 호출합니다. 이 함수는 XBOX 서비스를 호출하여 플레이어에게 권한이 있는지 확인한 다음, 플레이어에게 작업이 실패한 이유를 알리거나 이를 해결하기 위한 UI를 플레이어에게 표시합니다. 이 API 호출로 인해 다음과 같은 결과가 발생할 수 있습니다.
   • XBOX 서비스 정책 및 시행 조정자가 발행한 플레이어의 시행 상태와 관련된 UI를 표시합니다.
   • 자녀 보호 설정과 관련된 UI를 표시합니다.
   • XBOX Game Pass Essential 구독과 같은 해당 구독 서비스를 홍보합니다.
   • 게임에 결과를 반환합니다(성공 또는 이유가 포함된 실패).

   [!NOTE] XBOX 서비스 또는 네트워크에 연결할 수 없는 경우 XUserResolvePrivilegeWithUiAsync가 실패합니다. 이 실패는 플레이어에게 권한이 없는 것처럼 처리해야 합니다.

4. XUserResolvePrivilegeWithUiAsync에서 반환될 때:
   1. 실패가 반환되면 게임은 플레이어가 계속 버튼을 선택할 수 있도록 허용해야 합니다. 왜냐하면 (예를 들어) 플레이어의 차단이 만료되거나 자녀 보호 설정이 변경될 수 있기 때문입니다.
   2. 성공이 반환되면 플레이어의 문제가 해결된 것이므로 게임에서 작업을 다시 시도할 수 있습니다. 플레이어의 토큰은 XUserResolvePrivilegeWithUiAsync가 수행한 해결의 일부로 필요한 권한을 포함합니다.

타이틀에 적용되는 권한에 대한 자세한 내용은 정책 및 XBOX 요구 사항 항목의 XR-015를 참조하십시오.

​

예제 코드

XUserPrivilegeDenyReason reason;
bool hasPrivilege = false;

// check the Multiplayer (254) privilege
HRESULT hr = XUserCheckPrivilege(userHandle, XUserPrivilegeOptions::None, XUserPrivilege::Multiplayer, &hasPrivilege, &reason);

// error with the user such that we can't yet check privileges
if(E_GAMEUSER_RESOLVE_USER_ISSUE_REQUIRED == hr)
{
      asyncBlock.callback = [](XAsyncBlock *async)
      {
         HRESULT hr = XUserResolveIssueWithUiResult(async);
         // if SUCCEEDED(hr), the issue is resolved, try the privilege check again
         // if FAILED(hr), the issue is not resolved, the title should deny access to the user, and perhaps try again later
      };

      hr = XUserResolveIssueWithUiAsync(userHandle, nullptr, &asyncBlock);
}

// user doesn't have the requested privilege, try to resolve the issue
else if(!hasPrivilege)
{
      asyncBlock.callback = [](XAsyncBlock *async)
      {
         HRESULT hr = XUserResolvePrivilegeWithUiResult(async);
         // if SUCCEEDED(hr), all privilege issues are now resolved, the user has the privilege,
         //    and the title should continue. It is not necessary to call XUserCheckPrivilege again.
         // if FAILED(hr), the user did not resolve all privileges, the title should deny access to the user and perhaps try again later
      };

      hr = XUserResolvePrivilegeWithUiAsync(userHandle, XUserPrivilegeOptions::None, XUserPrivilege::Multiplayer, &asyncBlock);
}
else if(hasPrivilege)
{
      // the user has the privilege, continue!
}

​

앱 측 권한 처리에 대한 모범 사례

​

앱에서 권한 해결 빈도

• 비디오 플레이어와 같은 미디어 스트리밍 앱의 경우, 재생 버튼을 선택할 때마다(스트림 시작) 또는 재생 목록(음악 재생 목록과 같은 여러 스트림)의 시작 시 권한 확인을 해결하십시오.
• 메시징 앱의 경우, 처음 전송되는 메시지에 대해 한 번 권한을 확인하십시오.
• 타사 매치 서비스를 사용하는 멀티플레이어 게임의 경우, 모든 세션(매치) 시작마다 권한 확인을 해결하십시오.

​

사용자의 구독 등급을 절대 가정하지 마십시오

​

오프라인 모드

​

올바른 플레이어를 대상으로 지정

​

UI 없이 또는 UI가 포커스 밖에 있는 상태에서 확인

​

게임에서 권한 기반 접근 제어 테스트

• 플레이어의 유효한 구독 자격
• 장치의 유효한 권한 자격
• 클라이언트 플랫폼의 유효한 권한 자격
• 현재 게임의 유효한 권한 자격
  • 게임의 모든 플레이어가 실행 중인 게임에서 사용할 수 있도록 이러한 권한을 자동으로 얻도록 게임을 권한 컬렉션과 함께 패키징할 수 있습니다. 게임에 이 기능이 필요한 경우 Microsoft 계정 관리자에게 문의하십시오.
• 부모가 가족의 자녀에 대해 추가하거나 제거할 권한을 결정하기 위한 자녀 보호 설정
• XBOX 조정자는 서비스 남용으로 확인된 플레이어 또는 장치의 권한을 금지할 수 있습니다.

​

플레이어 권한 및 사용 권한 관리 및 확인

• PC에서: https://aka.ms/XboxPrivSettings로 이동합니다.
• XBOX에서: 설정 -> 일반 -> 온라인 안전 및 가족 -> 개인정보 및 온라인 안전 -> XBOX 개인정보로 이동합니다.

​

XUserCheckPrivilege로 확인되는 권한

XUserPrivilege::CrossPlay

• 설명: 플레이어가 XBOX 서비스에 로그인하지 않은 다른 실제 사용자와 게임 플레이 세션에 참여할 수 있도록 허용합니다. 시나리오에는 동일한 세션에서의 동기식 플레이어 대 플레이어 게임 플레이, 비동기식 턴제 게임 플레이, 팀 기반 게임 플레이, 사용자 시작 매치메이킹, 초대 전송 또는 수락, 진행 중 참여 세션 등이 포함됩니다.
• 요구 사항: XR-045 - XBOX 서비스 및 계정 권한
• 권한 ID: 185
• PC 설정: XBOX 서비스 외부의 사람들과 플레이할 수 있습니다.
• XBOX 설정: 크로스 네트워크 플레이에 참여할 수 있습니다.

XUserPrivilege::Sessions

• 설명: 플레이어가 공유 환경에서 연결된 싱글 플레이어 경험에 참여할 수 있도록 허용하거나, 타이틀이 F2P와 유료 멀티플레이어 하이브리드이고 이 권한을 사용하여 XBOX 콘솔에서 해당 경험을 게이팅하는 시나리오에 사용됩니다. 싱글 플레이어 경험은 권한 252 또는 254(각각 통신 및 멀티플레이어)에서 다루는 기능을 포함해서는 안 됩니다. 이 권한의 사용은 플랫폼 승인이 필요한 타이틀 기능입니다.
• 요구 사항: XR-045 - XBOX 서비스 및 계정 권한
• 권한 ID: 189
• PC 설정: 멀티플레이어 게임에 참여할 수 있습니다.
• XBOX 설정: 멀티플레이어 게임에 참여할 수 있습니다.

XUserPrivilege::Multiplayer

• 설명: 플레이어가 실제 사용자(봇 아님)와 온라인 멀티플레이어 게임 플레이 세션에 참여할 수 있도록 허용합니다. 시나리오에는 동일한 세션에서의 동기식 플레이어 대 플레이어 게임 플레이, 비동기식 턴제 게임 플레이, 팀 기반 게임 플레이, 사용자 시작 매치메이킹, 초대 전송 또는 수락, 진행 중 참여 세션 등이 포함됩니다. 이 권한은 동일한 장치에서 실행되는 로컬 멀티플레이어 게임에는 적용되지 않습니다.
• 요구 사항: XR-045 - XBOX 서비스 및 계정 권한
• 권한 ID: 254
• PC 설정: 멀티플레이어 게임에 참여할 수 있습니다.
• XBOX 설정: 멀티플레이어 게임에 참여할 수 있습니다.

XUserPrivilege::UserGeneratedContent

• 설명: 플레이어가 다른 사용자의 UGC를 온라인으로 보거나, 다른 사용자의 UGC를 다운로드하거나, 자신의 UGC를 온라인으로 공유할 수 있도록 허용합니다. 이는 이전에 다운로드한 UGC의 사용을 제한하지 않습니다.
• 요구 사항: XR-045 - XBOX 서비스 및 계정 권한
• 권한 ID: 247
• PC 설정: 커뮤니티 창작물을 보고 업로드할 수 있습니다.
• XBOX 설정: 커뮤니티 창작물을 보고 업로드할 수 있습니다.

XUserPrivilege::SocialNetworkSharing

• 설명: XBOX 콘솔 전용: 플레이어가 게임 진행 상황, Kinect 생성 콘텐츠, 게임 클립 등 정보를 XBOX 네트워크 외부로 공유할 수 있도록 허용합니다.
• 요구 사항: XR-045 - XBOX 서비스 및 계정 권한
• 권한 ID: 220
• XBOX 설정: XBOX 외부에서 공유할 수 있습니다.

XUserPrivilege::Communications

• 설명: 플레이어가 음성 또는 텍스트를 통해 다른 XBOX 서비스 사용자와 통신할 수 있도록 허용합니다.
• 요구 사항: XR-045 - XBOX 서비스 및 계정 권한
• 권한 ID: 252
• PC 설정: 다른 사람이 음성, 텍스트 또는 초대로 통신할 수 있습니다.
• XBOX 설정: 다른 사람이 음성, 텍스트 또는 초대로 통신할 수 있습니다.

​

XblPrivacyCheckPermissionAsync로 확인되는 권한

XblPermission::CommunicateUsingText

• 설명: 플레이어가 대상 사용자에게 텍스트 내용이 있는 메시지를 보낼 수 있는지 여부를 확인합니다. 이 값은 플레이어가 대상 사용자를 음소거한 경우에도 변경되지 않습니다. 대신 CommunicateUsingVoice를 사용하십시오. 예를 들어, 통신을 친구로만 설정하고 대상이 친구가 아닌 경우 이 값은 false가 됩니다. 대상 플레이어가 나를 차단한 경우 이 값은 false가 됩니다. 통신 설정을 차단됨으로 설정한 경우 이 값은 false가 됩니다.
• 요구 사항: XR-015 - 플레이어 통신 관리
  • 다른 XBOX 서비스 사용자를 확인할 때
    • PC 설정: 다른 사람이 음성, 텍스트 또는 초대로 통신할 수 있습니다.
    • XBOX 설정: 다른 사람이 음성, 텍스트 또는 초대로 통신할 수 있습니다.
  • 익명 사용자를 확인할 때
    • PC 설정: 음성 및 텍스트로 XBOX 서비스 외부에서 통신할 수 있습니다.
    • XBOX 설정: 음성 및 텍스트로 XBOX 외부에서 통신할 수 있습니다.

XblPermission::CommunicateUsingVoice

• 설명: 플레이어가 대상 사용자와 음성을 사용하여 통신할 수 있는지 여부를 확인합니다. 플레이어가 대상 사용자를 음소거한 경우 false가 됩니다.
• 요구 사항: XR-015 - 플레이어 통신 관리
  • 다른 XBOX 서비스 사용자를 확인할 때
    • PC 설정: 다른 사람이 음성, 텍스트 또는 초대로 통신할 수 있습니다.
    • XBOX 설정: 다른 사람이 음성, 텍스트 또는 초대로 통신할 수 있습니다.
  • 익명 사용자를 확인할 때
    • PC 설정: 음성 및 텍스트로 XBOX 서비스 외부에서 통신할 수 있습니다.
    • XBOX 설정: 음성 및 텍스트로 XBOX 외부에서 통신할 수 있습니다.

​

구독으로 제공되는 권한 테스트

​

실행 중인 게임에서 제공되는 권한 테스트

​

자녀 보호 설정으로 제거된 권한 테스트

​

확인할 권한 ID

​

권한 계산 로직

​

장치 유형에 따른 권한 자격

​

구독에 따른 유효한 권한 자격

• 플레이어가 구독 제품을 구매했습니다.
• 동일한 장치에서 다른 활성 플레이어가 구독 제품을 구매했습니다.
• 구독 제품이 플레이어가 현재 사용 중인 장치에 연결되어 있습니다.

​

프로모션 자격

​

후원 게스트 계정에 대해 제거된 권한

​

온라인 안전 및 Microsoft 시행

​

자녀 보호 설정

​

XBOX Game Pass Essential 구독자를 위한 권한

​

파트너 구독 및 권한

​

F2P 타이틀 및 멀티플레이어 권한

​

하이브리드 타이틀 및 멀티플레이어 권한

​

참고