사용자 정보 인터페이스

표시되는 이름 또는 국가와 같은 사용자 정보를 얻고 계정 식별자에 표시되는 이름을 매핑하는 인터페이스입니다.

2022년 10월 이전에 에픽 계정 서비스가 통합된 콘솔용 게임을 출시할 계획이라면 eas-on-console-beta@epicgames.com으로 연락하여 출시 계획을 조율하세요.

모든 에픽 온라인 서비스(EOS) 사용자 계정에는 내부적으로 계정을 참조할 때 사용하는 고유의 식별 정보가 있습니다. 사용자 정보 인터페이스(User Info Interface) 는 사용자의 계정 식별 정보와 사용자 정보(표시되는 이름, 국가, 선호 언어 등)의 차이를 메워줍니다. 이 정보는 원격 사용자와 로그인한 로컬 사용자에 관계없이 얻을 수 있습니다.

사용자의 개인 정보를 보호하기 위해 원격 사용자일 경우에는 표시되는 이름과 고유 계정 식별 정보만 제공됩니다.

사용자 정보 인터페이스를 사용하려면 제품에서 에픽 계정 서비스 (EAS)가 활성 상태여야 하며, 사용자 데이터에 액세스하려면 사용자의 동의가 필요합니다. 개발자 포털(Developer Portal)에서 EAS를 활성화하거나 에픽 문서에서 자세한 내용을 확인할 수 있습니다. EAS와 사용자 동의가 없어도 EOS SDK와 친구 인터페이스를 초기화할 수는 있지만, 백엔드 서비스에 보내는 모든 사용자 정보 인터페이스 함수 호출이 실패합니다.

사용자 정보 얻기 및 캐싱

사용자 정보 인터페이스에 액세스하려면 EOS_HUserInfo 핸들이 필요합니다. 이 핸들은 EOS_Platform_GetUserInfoInterface 를 통해 플랫폼 인터페이스 에서 얻을 수 있습니다. 이 핸들이 있어야 사용자 정보 인터페이스 함수가 사용자 정보에 액세스할 수 있습니다. 에픽 온라인 서비스의 서버는 사용자 정보를 저장하며 이 정보는 사용자가 자신의 계정을 업데이트하면 알림 없이 변경될 수 있습니다. 사용자 정보 인터페이스는 최신 정보가 필요하면 서버를 쿼리하여 업데이트할 수 있는 로컬 캐시를 자동으로 생성합니다.

계정 식별 정보로 사용자 정보 얻기

사용자 정보를 다루는 첫 단계는 EOS_UserInfo_QueryUserInfoOptions 데이터 구조로 EOS_UserInfo_QueryUserInfo 를 호출하는 것입니다. 이렇게 하면 최신 사용자 정보가 로컬 캐시로 다운로드됩니다. 다음 필드값으로 EOS_UserInfo_QueryUserInfoOptions 를 생성하고 초기화하면 EOS_UserInfo_QueryUserInfo 를 호출할 수 있습니다.

프로퍼티

ApiVersion

EOS_USERINFO_QUERYUSERINFO_API_LATEST

LocalUserId

로그인한 사용자의 EOS_EpicAccountId 입니다.

TargetUserId

정보를 얻고자 하는 사용자의 EOS_EpicAccountId 입니다.

사용자 정보 인터페이스 핸들, EOS_UserInfo_QueryUserInfoOptions 구조, 콜백 정보를 함수에 전달합니다. EOS_HPlatform 핸들이 틱 중이라면 EOS_UserInfo_QueryUserInfo 에 한 콜백은 작업이 끝난 후 실행됩니다. 콜백이 실행되면 EOS_UserInfo_QueryUserInfoCallbackInfo 구조의 ResultCode 필드에서 작업 성공 여부를 확인할 수 있습니다. 성공 코드는 SDK가 서버의 최신 데이터를 캐시했음을 나타내며, 이 데이터는 언제든지 확인 가능합니다.

표시되는 이름으로 사용자 정보 얻기

EOS SDK의 거의 모든 함수는 고유 계정 식별 정보로 사용자를 구분하지만, 플레이어는 친구의 계정 이름만 알면 됩니다. EOS_UserInfo_QueryUserInfoByDisplayName 로 표시되는 이름과 계정 식별 정보를 매핑할 수 있습니다. EOS_UserInfo_QueryUserInfoByDisplayNameOptions 데이터 구조로 EOS_UserInfo_QueryUserInfoByDisplayName 를 호출해 사용자 정보의 최신 버전을 얻고 캐시할 수 있습니다. 이 함수를 호출할 때는 다음과 같이 EOS_UserInfo_QueryUserInfoByDisplayNameOptions 구조를 초기화합니다.

프로퍼티

ApiVersion

EOS_USERINFO_QUERYUSERINFOBYDISPLAYNAME_API_LATEST

LocalUserId

로그인한 사용자의 EOS_EpicAccountId 입니다.

DisplayName

정보를 얻고자 하는 사용자에게서 표시되는 이름입니다.

사용자 정보 인터페이스 핸들, EOS_UserInfo_QueryUserInfoByDisplayNameOptions 구조, 콜백 정보를 함수에 전달합니다. EOS_HPlatform 핸들의 틱이 실행 중이라면 전달한 콜백은 작업이 끝난 후에 실행됩니다. 콜백 함수에서 EOS_UserInfo_QueryUserInfoByDisplayNameCallbackInfo 구조의 ResultCode 필드에서 작업 성공 여부를 확인할 수 있습니다. 성공하면 SDK가 서버에서 최신 데이터를 캐시하며, 언제든지 데이터를 검토할 수 있습니다.

사용자 정보 검사

에픽 온라인 서비스에서 특정 사용자의 정보를 얻은 후에는 EOS_UserInfo_CopyUserInfo 함수로 데이터 복사본을 요청할 수 있습니다. 이 함수에는 다음 정보가 담긴 EOS_UserInfo_CopyUserInfoOptions 구조가 필요합니다.

프로퍼티

ApiVersion

EOS_USERINFO_COPYUSERINFO_API_LATEST

LocalUserId

로그인한 사용자의 EOS_EpicAccountId 입니다.

TargetUserId

정보를 얻고자 하는 사용자의 EOS_EpicAccountId 입니다. LocalUserId 와 같을 수 있습니다.

사용자 정보 인터페이스 핸들, EOS_UserInfo_CopyUserInfoOptions 구조, EOS_UserInfo 데이터 구조 포인터의 주소를 전달합니다. 캐시에 타깃 사용자의 정보가 포함되어 있다면 EOS_UserInfo 데이터 구조가 채워지고 함수가 EOS_Success 를 반환합니다.

이 함수는 데이터 복사본을 만들어 사용자 정보 인터페이스가 게임 코드가 액세스하고 있는 사용자 정보를 삭제하지 않도록 합니다. 이는 게임 코드가 메모리를 소유하며 해제도 코드가 담당한다는 것을 의미합니다. 그렇지 않으면 메모리 누수가 발생합니다. EOS_UserInfo 오브젝트를 EOS_UserInfo_Release 함수에 패스하면 해당 오브젝트를 해제할 수 있습니다.

로컬 사용자가 아니라면 EOS_UserInfo 구조의 대부분 정보는 비어 있습니다. 이는 EOS가 개인 식별 정보(PII)를 다른 사용자에게 제공하지 않도록 하기 위한 것입니다. EOS SDK가 채울 수 있는 건 DisplayNameUserId 필드뿐입니다.

표시명 및 닉네임

사용자는 다른 사용자의 닉네임을 설정할 수 있습니다. 사용자가 다른 사용자에게 닉네임을 할당하면 해당 닉네임이 Nickname 필드에 기재됩니다. 닉네임은 그 닉네임을 만든 사용자에게만 노출됩니다. 닉네임을 할당하지 않은 경우 Nickname 필드는 비어 있습니다.

로컬 사용자는 할당된 닉네임이 개인 정보라고 생각할 수 있으므로 닉네임을 할당할 때는 해당 사용자를 존중하고 중복된 닉네임을 사용하지 않는 것이 좋습니다.

외부 사용자 정보

1.6 버전부터 SDK에서 외부 사용자 정보로 알려진 사용자의 연결 계정에 대한 데이터를 얻을 수 있습니다. 인터페이스에서는 이러한 데이터를 쉽게 얻을 수 있도록 여러 API 함수가 노출됩니다. 사용자의 EOS_UserInfo_ExternalUserInfo 는 사용자의 EOS_UserInfo 와 마찬가지로 이전에 EOS_UserInfo_QueryUserInfo 를 호출한 적이 없는 한 캐싱되지 않으며 검색에 사용할 수 있습니다.

EOS_UserInfo_GetExternalUserInfoCount 는 타깃 사용자를 검색하는 데 사용할 수 있는 외부 사용자 정보 항목의 개수를 반환합니다.

EOS_UserInfo_CopyExternalUserInfoByIndex 는 인덱스가 할당된 타깃 사용자의 외부 사용자 정보를 출력합니다.

EOS_UserInfo_CopyExternalUserInfoByAccountType 은 정보를 얻으려는 외부 계정의 구체적인 타입이 할당된 타깃 사용자의 외부 사용자 정보를 출력합니다. 1.6 버전에서 지원되는 외부 사용자 정보의 계정 타입은 EOS_EAT_PSN, EOS_EAT_XBL, EOS_EAT_NINTENDO, EOS_EAT_STEAM 입니다.

EOS_UserInfo_CopyExternalUserInfoByAccountId 는 외부 계정의 계정 ID가 할당된 타깃 사용자의 외부 사용자 정보를 출력합니다.

외부 사용자 정보 항목을 열람한 후에는 EOS_UserInfo_ExternalUserInfo_Release 를 호출하여 유출을 방지해야 합니다.