Skip to main content

XBOX Live Helper 라이브러리 개요

PlayFab Party용 XBOX Live Helper 라이브러리는 PlayFab Party를 사용하는 게임이 통신과 관련된 XBOX Live 정책(XR-015 및 XR-045)을 충족하도록 돕도록 설계되었습니다. XBOX Live Helper 라이브러리는 Nuget.org에서 사용할 수 있습니다.

PlayFab Party 라이브러리와의 호환성

API에서 호환성이 손상되는 변경을 최소화하기 위해 노력하지만, PlayFab Party API에 대한 일부 변경 사항으로 인해 XBOX Live Helper 라이브러리가 잘못된 값을 반환할 수 있습니다. 라이브러리 버전이 호환되는지 확인하려면 아래 표를 참조하세요.

XBOX Live 사용자 추적

PlayFab Party XBOX Live Helper 라이브러리는 현재 Party 세션에 참여하는 XBOX Live 사용자에 대해 명시적으로 알림을 받아야 합니다. 타이틀은 multiplayer session document에 대한 변경 사항을 수신하고 PartyXblManager::CreateLocalChatUserPartyXblManager::CreateRemoteChatUser를 통해 XBOX Live Helper 라이브러리에 해당 명단을 반영하여 라이브러리에 알리는 것이 권장됩니다. 로컬 사용자의 경우:
이 시점에서 해당 로컬 XBOX 사용자에 대해 PartyLocalChatControl이 이미 존재하는 경우, SetCustomContext 메서드를 통해 이 PartyXblLocalChatUser와 연결할 수 있습니다.
그렇지 않은 경우 이 새 PartyXblLocalChatUser를 사용하여 채팅 컨트롤을 생성하고 그때 연결할 수 있습니다. 자세한 내용은 PartyXblLocalChatUsers에서 PartyLocalChatControls 만들기를 참조하세요. 원격 사용자의 경우:
이 시점에서 해당 원격 XBOX 사용자에 대해 PartyChatControl이 이미 존재하는 경우, SetCustomContext 메서드를 통해 이 PartyXblChatUser와 연결할 수 있습니다.
세션 문서에 대한 업데이트와 원격 채팅 컨트롤 목록에 대한 업데이트는 순서가 지정되지 않을 수 있으며, 원격 채팅 컨트롤에 대한 PartyChatControlCreatedStateChange 업데이트를 처리할 때 유사한 연결 로직이 필요할 수 있습니다. 로컬 및 원격 채팅 사용자 모두에 대해 핵심 Party 라이브러리는 PlayFab Entity ID를 통해 사용자와 채팅 컨트롤을 식별하는 반면 XBOX Live Helper 라이브러리는 XBOX User ID로 채팅 사용자를 식별한다는 점을 명심하는 것이 중요합니다. 따라서 이 둘 사이의 변환이 종종 필요합니다. 자세한 내용은 XBOX Live User ID와 PlayFab Entity ID 간 매핑을 참조하세요.

PartyXblLocalChatUsers에서 PartyLocalChatControls 만들기

PartyXblLocalChatUser 객체는 Party 라이브러리의 PartyLocalUserPartyLocalChatControl 객체와 연결될 때만 유용한 경우가 많습니다. PartyLocalUserPartyLocalChatControl 객체를 생성하려면 타이틀이 PlayFab에 사용자를 로그인시키고 사용자의 entityIdtitlePlayerEntityToken을 검색해야 합니다. 로그인은 PlayFab CPP SDK를 통해 수행할 수 있지만, 타이틀이 XBOX Live 자격 증명을 사용하여 PlayFab에 로그인하려는 경우 추가 종속성을 가져오는 것을 피하기 위해 PartyXblManager::LoginToPlayFab을 사용할 수 있습니다. 다음 샘플은 XBOX Live Helper 라이브러리가 PartyXblLocalChatUser 객체에서 PartyLocalUserPartyLocalChatControl 객체를 만드는 데 어떻게 도움이 되는지 보여줍니다. PartyXblLocalChatUser 객체 만들기에 대한 자세한 내용은 XBOX Live 사용자 추적을 참조하세요.
PartyXblManager::LoginToPlayFab 호출 직후 로그인 작업 결과를 포함하는 PartyXblLoginToPlayFabCompletedStateChange를 받습니다.

XBOX Live 사용자의 접근성 기본 설정 준수

PartyXblLocalChatUser 객체는 Party 채팅 세션과 관련된 XBOX Live 사용자의 접근성 기본 설정 일부를 노출합니다. 타이틀은 이 정보를 사용하여 Party의 접근성 기능 일부를 바로 활성화함으로써 플레이어에게 더 나은 경험을 제공할 수 있습니다.

XBOX Live 사용자의 개인 정보 보호 설정 및 권한 준수

XBOX Live 정책에 따라 타이틀은 사용자의 개인 정보 보호 또는 권한이 허용하지 않는 경우 XBOX Live를 통한 통신을 허용해서는 안 됩니다. XBOX Live Helper 라이브러리는 XBOX Live 정책이 허용하는 두 사용자 간의 가장 제한적인 PartyChatPermissionOptions를 쿼리할 수 있게 하여 이를 달성하는 데 도움이 됩니다. 이 값이 변경될 때마다 라이브러리에서 PartyXblRequiredChatPermissionInfoChangedStateChange가 생성됩니다. 업데이트된 PartyChatPermissionOptionsPartyXblLocalChatUser::GetRequiredChatPermissionInfo() 호출을 통해 얻을 수 있습니다.
XBOX Live Helper 라이브러리는 XBOX Live 개인 정보 보호 서비스와 통신하여 각 로컬 채팅 사용자와 관련된 각 원격 채팅 사용자의 개인 정보 보호 및 권한 설정을 추적합니다. 또한 라이브러리는 Real-Time Activity 업데이트를 구독하여 이러한 설정에 대한 변경 사항을 수신합니다. 새 원격 채팅 사용자가 추가되거나 로컬 채팅 사용자와 기존 원격 채팅 사용자 간의 개인 정보 보호 및 권한 관계가 변경되면 업데이트된 PartyChatPermissionOptions 값을 이제 사용할 수 있음을 알리기 위해 PartyXblRequiredChatPermissionInfoChangedStateChange가 생성됩니다.
PartyXblChatPermissionInfo 구조체에는 두 가지 정보가 포함되어 있습니다.
  • PartyChatPermissionOptions 마스크로, PartyLocalChatControl::SetPermission()에 그대로 전달하거나 사용하려는 PartyChatPermissionOptions 값이 이미 있지만 XBOX Live 정책을 준수하고 있는지 확인하려는 경우 이진 마스크로 사용할 수 있습니다.
  • PartyXblChatPermissionInfo::chatPermissionMask의 값에 대한 추가 정보를 제공하는 PartyXblChatPermissionMaskReason

크로스 네트워크 통신 권한 준수

XBOX Live와 XBOX Live가 아닌 플레이어 간의 크로스 네트워크 플레이 및 통신을 지원하는 타이틀은 해당 플레이어 간 통신을 허용하기 전에 통신 권한을 확인해야 합니다. XBOX Live Helper 라이브러리는 PartyXblLocalChatUser::GetCrossNetworkCommunicationPrivacySetting()을 통해 이 정보를 제공합니다. 이 메서드는 세 가지 가능한 값을 가진 PartyXblCrossNetworkCommunicationPrivacySetting 열거형을 반환합니다.
XR-015 및 크로스 네트워크 플레이 및 통신과 관련된 방식에 대한 자세한 정보는 여기에서 확인할 수 있습니다.

XBOX Live User ID와 PlayFab Entity ID 간 매핑

PlayFab Party를 사용하는 많은 XBOX Live 타이틀은 (XBOX Live 생태계 전반에서 사용되는) XBOX Live User ID와 (PlayFab Party에서 사용되는) PlayFab Entity ID 간에 변환해야 합니다. PartyXblManager::GetEntityIdsFromXboxLiveUserIds를 사용하여 타이틀은 주어진 XBOX Live User ID 목록에 해당하는 PlayFab Entity ID 목록을 검색할 수 있습니다. 타이틀은 Multiplayer Session Directory 같은 외부 명단 서비스 사용을 통해 이미 XBOX Live User ID 목록을 가지고 있어야 합니다. 명단의 XBOX Live User ID를 그들의 PlayFab Entity ID와 연결하여, 게임 세션의 명단에 해당하는 모든 PlayFab Entity ID의 매핑을 구성할 수 있습니다. 그런 다음 이 매핑을 사용하여 PartyEndpointPartyChatControl 객체를 해당 XBOX Live 사용자와 연결할 수 있습니다.
각 XBOX Live User ID는 이 XBOX Live 사용자가 이미 PlayFab 계정에 연결된 경우에만 PlayFab Entity ID에 매핑됩니다. PlayFab 계정은 주어진 XBOX 사용자에 대해 PartyXblManager::LoginToPlayFab가 처음 호출될 때 자동으로 생성되고 연결됩니다. 또는 PlayFab SDK 소비자는 LoginWithXbox API를 사용하여 동일한 결과를 얻을 수 있습니다.
로컬 PartyXblLocalChatUser는 PlayFab로 인증하는 데 사용됩니다. 사용자가 이전에 PartyXblManager::LoginToPlayFab 호출을 통해 PlayFab에 로그인하지 않은 경우 XBOX Live Helper 라이브러리는 백그라운드에서 사용자를 인증해야 합니다.
PartyXblManager::GetEntityIdsFromXboxLiveUserIds 호출 직후 작업 결과를 포함하는 PartyXblGetEntityIdsFromXboxLiveUserIdsCompletedStateChange를 받게 됩니다. 이 결과는 매핑을 구성하거나 업데이트하는 데 사용할 수 있습니다.
이러한 매핑을 통해 타이틀은 Party 객체가 XBOX Live 사용자를 나타내는 시기를 인식할 수 있습니다.

Windows에 대한 특수 고려 사항

Windows에서는 XBOX Live Helper 라이브러리가 XBOX Live 토큰을 얻는 데 타이틀의 도움이 필요합니다. 라이브러리는 PartyXblTokenAndSignatureRequestedStateChange를 생성하여 토큰을 요청합니다. 타이틀은 XBOX Authentication Library(XAL)를 사용하여 이러한 요청을 이행할 수 있습니다. 이 작업을 타이틀로 오프로드하면 사용자 인증과 일반적으로 연관된 모든 UI 처리와 동의 프롬프트를 완전히 제어할 수 있습니다.
XAL을 사용하여 토큰과 서명을 검색하는 방법에 대한 자세한 지침은 XBOX Authentication Library 문서를 참조하세요. 토큰과 서명이 있으면 상태 변경을 통해 타이틀에 제공된 동일한 correlationId와 함께 PartyXblManager::CompleteGetTokenAndSignatureRequest()를 호출하여 XBOX Live Helper 라이브러리에 제공할 수 있습니다.
마지막 수정일 2026년 9월 1일