개요
XUser는 플랫폼 전반에 걸쳐 XBOX 사용자 계정과 인증을 관리하기 위한 Gaming Runtime API입니다. XBOX 콘솔, Windows PC 및 핸드헬드, 그리고 Steam Deck과 같은 비 Microsoft 플랫폼에서 게임이 사용자 로그인, ID 및 관련 사용자 흐름을 처리할 수 있는 통합 인터페이스를 제공합니다. GDK의 크로스 플랫폼 이니셔티브의 일환으로, XUser는 각 환경의 다양한 기능과 제약을 수용하면서 모든 플랫폼에서 일관된 API 표면을 제공합니다.통합 요구 사항
게임에서 XUser를 사용하려면 소스 파일에XUser.h를 포함하고 XGameRuntime.lib에 대해 링크하세요. 플랫폼 간의 주요 차이점은 런타임 종속성이 처리되는 방식입니다.
Windows의 XBOX 콘솔 및 Microsoft Store / Game Pass
게이밍 런타임은 OS에 내장되어 있고 스토어에서 처리됩니다. 게임은 시스템의 내장 서비스와 UI를 자동으로 사용합니다.Windows의 다른 스토어
- 게임은 OS의 내장 서비스와 UI를 사용합니다.
- 설치 프로그램은 Gaming Runtime Service가 설치되었는지 확인하기 위해 GamingRepair.exe를 실행해야 합니다.
- 게임 패키지에 도구 포함 –
[GDK]\bin\GamingRepair.exe에서 GDK에 포함되어 있습니다. - 사용자 지정 액션 추가 – 게임 설치 전에 도구를 실행합니다(예: start /wait “Installing Gaming Services” GamingRepair.exe scenarioExternal). 이는 누락된 Gaming Runtime 구성 요소를 확인, 다운로드, 설치 또는 복구합니다.
- 오류 처리 – 도구의 종료 코드를 확인합니다. 실패하면 사용자에게 알리고 수동 설치 지침을 제공합니다.
Steam 게임은 시스템 서비스가 없는 플랫폼(예: Steam Deck)을 지원하기 위해
XGameRuntime.dll과 그 종속성을 포함해야 합니다.
Steam Deck이나 다른 비 Microsoft 플랫폼에서는 Gaming Repair Tool을 사용할 수 없습니다. 대신 게임 패키지에 XGameRuntime.dll과 그 종속성을 번들로 포함하고 런타임에 로드될 수 있도록 실행 파일과 함께 배치하세요.플랫폼 차이 및 통합 API
XBOX와 Windows에서 운영 체제는 XBOX Live 로그인 및 사용자 관리를 기본적으로 처리하며, 사용자 자격 증명에 대한 시스템 UI와 안전한 저장소를 제공합니다. XUser는 이러한 플랫폼에서 이러한 내장 시스템 서비스를 활용합니다. Steam Deck이나 타사 환경과 같은 다른 게이밍 플랫폼에서는 이 네이티브 지원이 존재하지 않습니다. GDK 2510 릴리스부터 XUser는 시스템 지원을 사용할 수 없는 곳에서 게임이 필요한 UI와 데이터 처리를 제공할 수 있게 해주는 새로운 API와 이벤트 기반 패턴을 통해 두 유형의 플랫폼 모두에서 일관된 API로 원활하게 작동하도록 강화되었습니다.- 네이티브 지원이 있는 플랫폼(XBOX, Windows)에서 - XUser는 인증, UI 및 자격 증명 저장소를 위해 운영 체제의 내장 서비스를 사용합니다. 게임은 XUser API를 호출하고 시스템이 세부 사항을 자동으로 처리합니다.
- 네이티브 지원이 없는 플랫폼(Steam Deck 등)에서 - XUser는 동일한 핵심 API를 노출하지만, 게임은 필요한 UI(예: 로그인용 QR 코드 표시)와 데이터 저장소를 제공하기 위해 이벤트 핸들러를 구현해야 합니다. 이는 게임에 인증 경험에 대한 완전한 제어권을 제공합니다.
XUserHandle을 얻으며 이는 XBOX 인증을 지원하는 서비스(XBOX 서비스, PlayFab 서비스 등)에 사용될 수 있습니다.
새로운 크로스 플랫폼 기능
XUser에 도입된 새 API는 플랫폼 독립적인 로그인 흐름과 데이터 처리를 가능하게 하는 데 중점을 둡니다. 주요 기능은 다음과 같습니다.Remote Connect 인증
Steam Deck과 같은 장치에서 보조 장치를 사용하여 사용자가 XBOX 계정으로 로그인할 수 있게 해줍니다. 사용자는 QR 코드를 스캔하거나 웹사이트에서 일회성 코드를 입력하여 인증을 완료할 수 있습니다. 이는 코드 기반 로그인 프롬프트를 표시하고 닫기 위한 새로운 XUser 이벤트 핸들러를 통해 달성됩니다.단일 세션 시행(SPoP)
사용자가 동일한 게임을 여러 위치에서 동시에 실행하지 않도록 보장합니다. 충돌이 감지되면 사용자에게 “여기서 플레이(play here)” 또는 “계정 전환(switch account)” 중 선택하도록 요청합니다. 새 API를 사용하면 게임이 이 선택을 제시하고 그에 따라 응답할 수 있습니다.XBOX 콘솔과 Windows에서는 운영 체제가 대부분의 인증 작업을 자동으로 계속 처리합니다. 게임은 이러한 플랫폼에서 이러한 이벤트를 절대 볼 수 없을 수도 있습니다. 그러나 비 XBOX 플랫폼에서는 게임이 XUser의 콜백 메커니즘을 통해 완전한 제어권을 가질 수 있습니다.
교차 장치 로그인을 위한 Remote Connect
Remote Connect는 플레이어가 다른 장치(예: 휴대폰이나 PC)를 통해 인증하여 장치에서 XBOX 계정에 로그인할 수 있게 해주는 기능입니다. 이는 일반적으로 게임이 표시하는 짧은 코드나 QR 코드를 통해 수행됩니다.작동 방식
XBOX 콘솔에서는 이 “코드 흐름”이 시스템 UI에 의해 자동으로 처리됩니다. 그러나 Steam Deck이나 다른 타사 환경과 같은 플랫폼에서는 시스템 관리 XBOX 로그인 UI가 없습니다. XUser의 Remote Connect API는 게임이 이 흐름을 직접 촉진할 수 있게 해줍니다.흐름
-
이벤트 핸들러 등록 - 게임은
XUserPlatformRemoteConnectSetEventHandlers(...)를 사용하여 로그인을 시작하기 전에 Remote Connect 이벤트 핸들러를 등록합니다. 타이틀은 두 가지 주요 이벤트를 처리하기 위한 콜백을 제공합니다.- Show 이벤트 - XUser가 게임에 일회성 코드 또는 QR 코드를 표시해야 할 때 트리거됩니다. 핸들러는 코드와 지침(예: “이 QR 코드를 스캔하거나 xbox.com/play를 방문하여 코드 ABCD를 입력해 로그인하세요”)이 포함된 대화 상자 또는 오버레이를 표시합니다.
- Close 이벤트 - 원격 로그인 프로세스가 완료되거나 취소될 때 트리거되며, 게임에 코드 대화 상자를 숨기거나 닫도록 신호를 보냅니다.
-
사용자 로그인 시작 -
XUserAddAsync를 호출하여 새 사용자를 추가할 때 로컬 사용자가 이미 로그인되어 있지 않은 경우, XUser 시스템은 Remote Connect 흐름을 사용할 수 있습니다(특히 헤드리스 또는 타사 플랫폼에서). -
코드 표시 - XUser는 인증 코드 또는 URL을 제공하는 “show” 콜백을 호출합니다. 게임의 UI 핸들러(예:
OnRemoteConnectShow)는 QR 코드나 코드 문자열을 사용자에게 표시합니다. - 사용자 인증 - 플레이어는 휴대폰이나 웹 브라우저를 사용하여 제공된 코드로 로그인하고, XBOX 계정을 현재 세션에 연결합니다.
-
완료 - 백엔드에서 인증이 완료되면 XUser는 화면에서 코드를 제거할 수 있음을 알리는 “close” 콜백을 호출합니다. 이 시점에서 XUser는 사용자의 XBOX Live 토큰을 얻고
XUserHandle을 만듭니다. -
성공 -
XUserAddAsync작업이 성공적으로 반환되고 사용자가 장치에 자격 증명을 직접 입력하지 않고 로그인됩니다.
구현
Remote Connect를 사용하려면 두 개의 콜백 함수를 구현하고 등록하세요.XUserAddAsync를 호출하여 새 사용자를 추가합니다. OnRemoteConnectShow 핸들러에서 제공된 정보(XUser API를 통해 액세스 가능 — 일반적으로 URL과 코드)를 검색하고 이를 팝업 또는 오버레이로 사용자에게 렌더링합니다. OnRemoteConnectClose가 호출되면 로그인 프로세스가 완료된 것이므로 게임은 프롬프트를 숨겨야 합니다.
이러한 이벤트가 제대로 처리되도록 하려면
XUserAddAsync를 호출하기 전에(그리고 일반적으로 XUserInitialize 전에) XUserPlatformRemoteConnectSetEventHandlers를 호출하세요.사용자 경험 고려 사항
좋은 사용자 경험을 제공하려면 다음을 수행하세요.- 명확한 지침 - 코드를 표시할 때 사용자가 무엇을 해야 하는지 명확하게 설명하세요.
- 오류 처리 - 사용자가 원격 측에서 취소하거나 오류가 발생하면 XUser가 로그인 시도를 실패시킵니다. 이를
XUserAddAsync의 정상 완료 콜백에서 처리하세요. - 적시 해제 - 사용자의 혼란을 피하기 위해 close 이벤트가 발생하면 즉시 코드를 숨기세요.
- 시각적 디자인 - QR 코드와 지침이 대상 장치에서 충분히 크고 명확하게 보이도록 하세요.
단일 세션 시행(SPoP)
Single-Session Enforcement, 즉 SPoP(Single Point of Presence)은 단일 XBOX Live 사용자 프로필이 여러 장치에서 동시에 동일한 타이틀을 실행하지 않도록 보장하는 정책입니다. 예를 들어, XBOX에서 이미 계정 아래 실행 중인 상태에서 PC에서 게임을 실행하면 저장된 게임 충돌 및 기타 문제를 방지하기 위해 한 세션이 일시 중단되거나 로그아웃되어야 합니다. XBOX 콘솔에서는 이 시나리오가 사용자에게 게임이 이미 다른 곳에서 실행 중임을 알리고 계속할지(다른 장치에서 로그아웃됨) 묻는 시스템 대화 상자를 트리거합니다. 비 Microsoft 플랫폼에서는 이를 시행하는 내장 메커니즘이 없습니다. XUser SPoP 프롬프트 API를 사용하면 게임이 이 상황을 감지하고 플레이어에게 “여기서 플레이하거나 계정 전환(Play here or Switch account)” 선택을 제시할 수 있습니다.작동 방식
SPoP API는 Remote Connect와 유사한 이벤트 핸들러 패턴을 사용합니다. 로그인 충돌이 감지되면 XUser는 즉시 실패하는 대신 게임의 핸들러를 호출하여 게임이 사용자에게 옵션을 제시할 수 있게 합니다.흐름
-
이벤트 핸들러 등록 - 게임은
XUserPlatformSpopPromptSetEventHandlers(...)를 사용하여 로그인을 시작하기 전에 SPoP 프롬프트 이벤트 핸들러를 등록합니다. -
충돌 감지 -
XUserAddAsync를 호출하여 사용자를 추가할 때, XUser가 동일한 사용자가 동일한 타이틀의 다른 곳에서 이미 활성 상태임을 감지하면 SPoP 핸들러를 호출합니다. - 프롬프트 표시 - 게임의 핸들러는 사용자의 최신 게이머태그와 작업 핸들을 받습니다. 핸들러는 “[Gamertag]는 다른 장치에서 이미 플레이하고 있습니다. 여기서 대신 플레이(다른 곳에서 로그아웃됨)하시겠습니까, 아니면 다른 계정으로 전환하시겠습니까?”와 같은 UI 프롬프트를 “여기서 플레이(Play here)“와 “계정 전환(Switch account)” 옵션과 함께 표시해야 합니다.
- 사용자 선택 - 게임은 사용자가 선택할 때까지 기다립니다. 게임이 완료 API를 호출할 때까지 작업은 보류 상태로 유지됩니다.
-
작업 완료 - 사용자의 선택에 따라 게임은 적절한 결과와 함께
XUserPlatformSpopPromptComplete를 호출합니다.- 여기서 플레이 -
XUserPlatformSpopOperationResult::SignInHere- 이 장치에서 로그인하고 원격 세션을 종료합니다. - 계정 전환 -
XUserPlatformSpopOperationResult::SwitchAccount- 이 장치에서 로그인을 취소하여 사용자가 다른 계정을 선택할 수 있게 합니다. - 취소 -
XUserPlatformSpopOperationResult::Canceled- 로그인 시도를 중단합니다.
- 여기서 플레이 -
-
해결 - XUser는 결과에 따라 진행합니다. “여기서 플레이”가 선택되면 원격 세션이 종료되고(다른 장치는 로그아웃 이벤트를 받음) 사용자가 로컬로 활성화됩니다. “계정 전환”이 선택되면
XUserAddAsync가 실패하고 게임이 다른 계정을 요청할 수 있습니다.
구현
SPoP를 사용하려면 콜백 함수를 구현하고 등록하세요.OnSpopPrompt 핸들러에서 게임은 사용자 식별자와 최신 게이머태그를 받습니다. 핸들러는 로그인이 보류 중이므로 게임 흐름을 일시 중지하고 옵션이 포함된 UI 프롬프트를 표시해야 합니다. 핸들러는 작업 핸들을 저장하고 즉시 완료하지 않습니다.
사용자가 선택하면 다음과 같이 처리합니다.
- 충돌이 제대로 처리되도록 하려면
XUserAddAsync를 호출하기 전에XUserPlatformSpopPromptSetEventHandlers를 호출하세요. - 수신된 각 SPoP 이벤트에 대해 정확히 한 번
XUserPlatformSpopPromptComplete를 호출해야 합니다. 그렇지 않으면 로그인이 무기한 정지됩니다. - 핸들러가 설정되지 않았고 충돌이 발생하면
XUserAddAsync가 오류 코드로 실패하여 사용자에게 충돌을 원활하게 해결할 기회를 주지 않습니다.
사용자 경험 고려 사항
좋은 사용자 경험을 제공하려면 다음을 수행하세요.- 명확한 메시지 - 사용자의 게이머태그를 표시하고 계속하면 다른 장치에서 로그아웃된다는 것을 명확하게 설명하세요.
- 가시적인 옵션 - “여기서 플레이”와 “계정 전환” 옵션 모두 명확하게 표시되고 이해하기 쉽게 만드세요.
- 저장 충돌 방지 - 이것이 저장된 게임 충돌과 동시 게임 플레이 문제를 방지한다는 것을 강조하세요.
- 플랫폼별 동작 - XBOX와 Windows에서 OS는 이를 자동으로 처리하며 SPoP 핸들러는 절대 호출되지 않습니다. 다른 플랫폼에서는 게임이 이 선택을 제시할 책임이 있습니다.