사용자 ID 및 XUser

XBOX One은 XUser 개체로 게임과 상호 작용하는 사용자의 ID를 관리합니다. 각 XUser 인스턴스는 게임에 로그인된 사용자를 나타냅니다. 각 사용자는 XUserHandle로 표현됩니다. 게임은 XUserHandle을 사용하여 다음을 수행할 수 있습니다.

• XBOX 서비스 로그인 상태 조회
• 사용자의 게이머 태그 가져오기
• 사용자의 게이머 그림 가져오기
• 사용자의 연령대 확인
• 실시간 통신에 참여하거나 멀티플레이어 세션에 참여할 수 있는 사용자에게 허용되는 권한 확인
• 인증된 토큰 가져오기

​

XUser 식별자

지정된 XUser와 연결된 두 가지 다른 식별자가 있습니다. 로컬 ID와 XBOX 서비스 ID(XUID)입니다. _로컬 ID_는 게임 세션 내에서 그 사용자의 수명 동안 사용자와 함께 유지되는 식별자입니다. 게임이 생성하는 모든 프로세스 또는 게임이 XLaunchNewGame을 호출할 때 로컬 ID를 사용하세요. 그러나 게임 세션 간에 사용자를 식별하기 위해
로컬 ID를 사용하지 마세요. 사용자의 로컬 ID를 얻으려면 XUserGetLocalId 함수를 사용하세요. _Xbox 서비스 ID(XUID)_는 XBOX 서비스와 통신하거나 title-callable UI(TCUI)를 호출할 때 사용해야 하는 식별자입니다. 사용자의 XUID를 얻으려면 XUserGetId 함수를 사용하세요. XUID를 얻는 데 사용자 동의가 필요할 수 있습니다. 이 동의가 필요하고 부여되지 않은 경우 XUserGetId는 E_GAMEUSER_RESOLVE_USER_ISSUE_REQUIRED를 반환합니다. 문제를 해결하고 동의를 수집하려면 게임은 XUserResolveIssueWithUiAsync를 호출해야 합니다.

​

XUser 상태

사용자는 세 가지 상태 중 하나에 있을 수 있습니다. XBOX 서비스에 로그인되어 있거나, XBOX 서비스에서 로그아웃 중이거나, 완전히 로그아웃된 상태입니다. 게임은 XUserGetState 함수를 사용하여 지정된 사용자의 이 상태를 쿼리할 수 있습니다. 게임은 또한 XUserRegisterForChangeEvent 함수를 사용하여 변경 알림에 등록할 수 있습니다. XUser 상태를 기반으로 네트워크 연결을 판단하지 마세요. XUserState가 SignedIn인 경우, 이는 어느 시점에 사용자가 XBOX 서비스로 인증되었고 활성 사용자로 취급될 수 있음을 나타냅니다. 그러나 네트워크가 연결되어 있지 않을 수 있습니다.

​

게임에 사용자 추가 또는 제거

XBOX One ERA의 모델과 달리, 게임은 XUserAddAsync 함수를 호출하여 게임이 요청한 사용자와만 상호 작용할 수 있습니다. 예를 들어, 콘솔에 두 명의 사용자, 사용자 A와 사용자 B가 로그인되어 있다고 가정해 봅니다.

1. 누군가가 게임을 실행합니다. 이 시나리오에서는 누가 실행했는지 중요하지 않습니다.
2. 게임은 XUserRegisterForChangeEvent를 사용하여 사용자 상태 변경에 등록합니다.
3. 게임이 XUserAddAsync를 호출하고 사용자 A가 게임에 로그인합니다.
4. 이제 게임에는 사용자 A를 나타내는 XUserHandle이 있습니다.
5. 가이드에서 사용자 B가 로그아웃하기로 선택합니다.
6. 게임에 로그인 변경 이벤트가 발생하지 않습니다. 게임은 사용자 B에 대해 전혀 몰랐습니다.
7. 가이드에서 사용자 A가 로그아웃하기로 선택합니다.
8. 게임은 먼저 사용자 A가 로그아웃 중임을 나타내는 변경 이벤트를 받고, 최종적으로 사용자 A가 이제 로그아웃되었음을 나타내는 다른 이벤트를 받습니다.

게임은 게임에 사용자를 추가할 수 있지만, 사용자를 제거하는 방법에는 다음 중 하나를 사용하는 몇 가지 방법만 있습니다.

• 게임은 XUserCloseHandle 함수를 사용하여 사용자를 나타내는 모든 핸들을 닫을 수 있습니다.
• 사용자가 가이드를 사용하여 콘솔에서 로그아웃합니다.
• 사용자가 다른 장치에 로그인합니다.

​

사용자 유형

XBOX One은 두 가지 유형의 사용자를 지원합니다. XBOX 플레이어와 게스트입니다. _Xbox 플레이어_는 시스템에서 사용자로서의 모든 기능을 갖습니다. 처음에는 사용자를 로그인하기 위한 시스템 제공 UI인 계정 선택기(Account Picker)에서 새 계정을 추가하여 만들어집니다. XBOX 플레이어는 설정 앱으로 명시적으로 제거될 때까지 콘솔에 유지됩니다. _Xbox 게스트_는 콘솔에서 단일 세션을 갖습니다. 이들은 계정 선택기에서 게스트로 플레이하기로 선택할 때 만들어지며 다른 로그인된 XBOX 플레이어의 후원을 받습니다. 게스트는 로그아웃할 때까지, 후원하는 XBOX 플레이어가 로그아웃할 때까지, 또는 콘솔이 꺼질 때까지 유지됩니다. 게스트를 허용하려는 게임은 XUserAddAsync를 호출할 때 AllowGuest 옵션을 지정해야 합니다.

​

사용자 추가 패턴

게임은 항상 초기 사용자를 설정하려고 시도해야 합니다. 이를 달성하는 두 가지 주요 방법이 있습니다.

​

옵션 1: UI를 표시하지 않고 가능한 한 빨리 사용자 결정하기

1. AddDefaultUserSilently를 사용하여 XUserAddAsync를 호출합니다. 이 함수는 UI를 표시하지 않고 누가 게임을 실행했는지 결정하려고 시도합니다.
2. XUserAddAsync에 대한 호출이 E\_GAMEUSER\_NO\_DEFAULT\_USER로 실패할 수 있습니다. 이 경우 게임이 처음 실행될 때 로그인된 사람이 없었습니다. 초기 사용자를 설정하려면 게임은 AddDefaultUserSilently 플래그를 사용하지 않고 XUserAddAsync를 호출해야 합니다. “silent” 옵션과 달리, 이 호출은 동의와 관련된 모든 문제가 완전히 해결되도록 보장하며, 호출이 성공하면 사용자가 XBOX 서비스에 로그인됩니다. 게임은 그 사용자에 대한 XBOX 컨텍스트를 만들 수 있습니다.

​

옵션 2: UI 표시 가능성이 있는 사용자 결정하기

AddDefaultUserAllowingUI를 사용하여 XUserAddAsync를 호출합니다. 이전 옵션(“silent” 사용)과 마찬가지로, 이 함수는 누가 게임을 실행했는지 결정하려고 시도합니다. 이전 옵션과 달리, 기본 사용자를 결정할 수 없으면 플레이어가 로그인하거나 자신을 선택할 수 있는 UI를 표시합니다. XUserAddResult가 성공하면 게임에는 XBOX 서비스에 완전히 로그인된 사용자가 있으며 게임은 그 사용자에 대한 XBOX 컨텍스트를 만들 수 있습니다. 이러한 단계를 보여주는 샘플 코드는 How to: 사용자 로그인 모범 사례를 참조하세요.

​

XUserHandle 관리

각 XUserHandle은 사용자를 나타냅니다. 그러나 여러 개의 그런 핸들이 각각 동일한 사용자를 나타낼 수 있습니다. 게임은 다음 기본 패턴을 사용해야 합니다.

1. 게임이 관심을 갖는 사용자 컬렉션을 나타내는 XUserHandle 인스턴스 컬렉션을 유지합니다.
2. XUserRegisterForChangeEvent를 호출하여 XUser 상태 변경에 등록합니다. 사용자가 로그아웃되고 있음을 발견하면 사용자 컬렉션을 업데이트합니다.
3. XUserAddAsync에서 새 XUserHandle을 받으면 이것이 새 사용자를 나타내는지 반드시 확인하세요. XUserCompare를 사용하여 핸들과 직접 비교할 수 있습니다. XUserGetLocalId를 호출하여 찾은 로컬 ID를 사용하여 비교할 수도 있습니다.
4. 동일한 사용자를 나타내는 여러 XUserHandle 인스턴스가 있는 경우 XUserCloseHandle을 사용하여 추가 인스턴스를 제거합니다.

_로컬 ID_는 게임 세션 내에서 그 사용자의 수명 동안 사용자와 함께 유지되는 식별자입니다. 게임이 생성하는 모든 프로세스 또는 게임이 XLaunchNewGame을 호출할 때 로컬 ID를 사용하세요. 그러나 게임 세션 간에 사용자를 식별하기 위해 로컬 ID를 사용하지 마세요.