다음을 통해 공유

사용자 ID 및 XUser

  • 아티클

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

  • Xbox 서비스 로그인 상태를 쿼리합니다.
  • 사용자의 게이머태그 가져오기.
  • 사용자의 게이머 사진 가져오기.
  • 사용자의 연령 그룹을 결정.
  • 실시간 통신에 참여하거나 멀티 플레이어 세션에 참가할 수 있는 사용자에게 부여되는 권한을 결정.
  • 인증된 토큰 가져오기.

참고 항목

다양한 XUserHandle 값이 동일한 사용자를 가리킬 수 있습니다. 두 개의 다른XUserHandle 값이 다른 사용자를 가리키는지 비교하려면 게임에서 XUserCompare 함수를 사용할 수 있습니다.

XUser 식별자

로컬 ID와 XUID(Xbox 서비스 ID)라는 지정된 XUser(와)과 관련된 두 개의 식별자가 있습니다.

로컬 ID는 게임 세션 내에서 해당 사용자의 수명 전반에 걸쳐 사용자와 함께 하는 식별자입니다. 로컬 ID는 게임이 생성하는 모든 프로세스에서 사용하거나 게임이 XLaunchNewGame(을)를 호출하는 경우에 사용합니다. 하지만
게임 세션 전반에 걸쳐 사용자를 식별하는 데 로컬 ID를 사용하지 마세요.

사용자에 대한 로컬 ID를 얻으려면 XUserGetLocalId 함수를 사용합니다.

XUID(Xbox 서비스 ID)는 Xbox 서비스와 통신하거나 TCUI(타이틀 호출 가능 UI)를 호출할 때 사용해야 하는 식별자입니다. 사용자에 대한 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 Live 플레이어는 시스템상의 사용자로서 모든 기능을 가집니다. 이러한 기능은 사용자 로그인을 위한 시스템 제공 UI인 계정 선택기에 새 계정을 추가하여 초기에 생성됩니다. Xbox Live 플레이어는 설정 앱에서 명시적으로 제거될 때까지 본체에서 유지됩니다.

Xbox 게스트는 본체에서 단일 세션을 갖습니다. 이들은 계정 선택기에서 게스트로 재생되도록 선택될 때 만들어지고 또 다른 로그인한 Xbox 플레이어의 지원을 받습니다. 게스트는 스스로 로그아웃할 때까지, 지원하는 Xbox 플레이어가 로그아웃할 때까지 또는 본체가 꺼질 때까지 유지됩니다.

게스트를 허용하려는 게임은 XUserAddAsync(을)를 호출할 때 반드시 AllowGuest 옵션을 지정해야 합니다.

사용자 추가 패턴

게임은 항상 초기 사용자를 설정하려고 합니다. 이 작업은 두 가지 기본 방법으로 수행할 수 있습니다.

옵션 1: UI를 표시하지 않고 최대한 빨리 사용자를 판단하기

  1. AddDefaultUserSilently(을)를 사용하여 XUserAddAsync(을)를 호출합니다. 이 함수는 UI를 표시하지 않고 게임을 시작한 사용자를 확인하려 합니다.
  2. XUserAddAsync 호출은 E\_GAMEUSER\_NO\_DEFAULT\_USER로 인해 실패할 수 있습니다. 이 경우 게임이 처음 시작되었을 때 아무도 로그인하지 않은 것입니다. 초기 사용자를 설정하려면 게임은 AddDefaultUserSilently 플래그를 사용하지 않고 XUserAddAsync(을)를 호출해야 합니다. “자동” 옵션과 달리 이 호출을 통해 모든 동의 관련 문제가 모두 해결되고 호출이 성공한 경우 사용자가 Xbox 서비스에 로그인되는지 확인합니다. 게임은 해당 사용자를 위해 Xbox 컨텍스트를 만들 수 있습니다.

옵션 2: UI가 표시될 가능성이 있는 사용자를 판단하기

AddDefaultUserAllowingUI(을)를 사용하여 XUserAddAsync(을)를 호출합니다. 이전의 ("자동") 옵션과 마찬가지로, 이 함수는 게임을 누가 시작했는지 판단하려고 시도합니다. 이전의 옵션과 달리, 기본 사용자를 판단하지 못하는 경우 UI를 표시하여 플레이어가 스스로 로그인하거나, 자신을 선택하도록 합니다. XUserAddResult(이)가 성공한 경우 Xbox 서비스에 사용자가 완전히 로그인되고 게임은 그 사용자를 위해 Xbox 컨텍스트를 만들 수 있습니다.

이러한 단계를 보여주는 샘플 코드는 방법: 사용자 로그인 모범 사례를 참조하십시오.

XUserHandle 관리

각 XUserHandle(은)는 사용자를 나타냅니다. 여러 개의 핸들이 각각 같은 사용자를 표시할 수 있습니다. 게임은 다음의 기본 패턴을 사용해야 합니다.

  1. 게임이 관심을 갖는 사용자 컬렉션을 나타내는 XUserHandle 인스턴스의 컬렉션을 유지합니다.

  2. XUserRegisterForChangeEvent(을)를 호출하여 XUser 상태 변경을 등록합니다. 사용자가 로그아웃하려는 것을 알게 되면 컬렉션 사용자를 업데이트합니다.

  3. XUserAddAsync에서 새 XUserHandle(을)를 가져올 때 이것이 새 사용자를 나타내는지 확인해야 합니다. XUserCompare(을)를 사용하여 핸들과 직접 비교할 수 있습니다. XUserGetLocalId(을)를 호출하여 찾은 로컬 ID를 사용하여 비교할 수도 있습니다.

  4. 같은 사용자를 나타내는 여러 개의 XUserHandle 인스턴스가 있는 경우 XUserCloseHandle(을)를 사용해 추가 인스턴스를 제거합니다.