친구 인터페이스

친구 목록을 검색하거나 다른 사용자를 추가 또는 제거하는 데 사용되는 인터페이스입니다.

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

친구와 게임을 즐기고 온라인에서 새로운 사람을 만나는 것은 많은 온라인 서비스에서 중요한 부분입니다. 에픽 온라인 서비스 (EOS) SDK는 친구 인터페이스(Friends Interface) 를 사용하여 로그인한 사용자의 친구 목록을 가져옵니다.

친구 목록은 온라인 서비스의 서버를 통해 저장되며, 친구가 계속해서 추가/제거되거나 친구가 게임에서 자신의 정보 사용에 동의/철회하기 때문에 세션 중에도 친구 목록은 계속 변경될 수 있습니다.

친구 목록 쿼리가 완료되면 친구 인터페이스는 다른 모든 친구 인터페이스 함수가 사용할 로컬 캐시를 생성합니다. 추가로, SDK는 친구 제거, 초대 수락, 게임에서 사용하는 친구의 정보 이용 동의 철회와 같이 친구 목록에 변화를 주는 이벤트에 대한 알림을 백엔드로부터 받게 됩니다.

친구 인터페이스를 사용하려면 제품에서 에픽 계정 서비스 (EAS)가 활성 상태여야 하며, 친구 목록 데이터에 액세스하려면 사용자의 동의가 필요합니다. 개발자 포털에서 EAS를 활성화하거나 에픽 문서에서 자세한 내용을 확인할 수 있습니다.

친구 목록 가져오기 및 캐시하기

사용자의 친구 목록을 가져오려면 EOS_HFriends 핸들이 필요합니다. 이 핸들은 플랫폼 인터페이스 함수인 EOS_Platform_GetFriendsInterface 를 통해 얻을 수 있습니다. 로그인한 사용자의 친구 목록에 액세스하려면 친구 인터페이스 함수에 이 핸들이 필요합니다.

친구 목록을 처리하는 첫 단계는 EOS_Friends_QueryFriendsOptions 데이터 구조로 EOS_Friends_QueryFriends 를 호출하는 것입니다. 이 작업은 사용자 친구 목록의 가장 최신 버전을 로컬 캐시에 다운로드한 다음, 완료되면 EOS_Friends_QueryFriends 콜백 함수를 호출합니다.

EOS_Friends_QueryFriends 호출을 수행하려면 EOS_Friends_QueryFriendsOptions 구조를 생성하고 다음과 같이 초기화합니다.

프로퍼티

ApiVersion

EOS_FRIENDS_QUERYFRIENDS_API_LATEST

LocalUserId

친구 목록을 가져올 로그인 사용자의 EOS_EpicAccountId 입니다.

친구 인터페이스 핸들, EOS_Friends_QueryFriendsOptions 구조, 콜백 정보를 함수에 전달합니다. EOS_HPlatform 핸들의 틱이 실행 중이라면 전달한 콜백은 작업이 끝난 후에 실행됩니다.

콜백이 실행되면 EOS_Friends_QueryFriendsCallbackInfo 구조의 ResultCode 필드를 확인함으로써 작업 성공 여부를 알 수 있습니다. 성공 코드는 SDK가 서버의 최신 데이터를 캐시했음을 나타내며, 이 데이터는 언제든지 확인 가능합니다.

친구 목록 조사하기

EOS_Friends_QueryFriends 호출에 성공한 후, 개발자는 로컬 캐시로 다음과 같은 유용한 함수를 사용할 수 있습니다.

  • EOS_Friends_GetFriendsCount 를 호출하여 목록에 있는 친구 수를 확인합니다.

  • EOS_Friends_GetFriendAtIndex 를 호출하여 각 친구의 EOS_EpicAccountId 를 가져옵니다.

    이 함수로 반환된 EOS_EpicAccountId사용자 정보 인터페이스 에 전달하면 사용자에 대한 추가 정보를 가져올 수 있습니다.

  • EOS_Friends_GetStatus 를 호출하여 소셜 관계의 현재 상태를 확인합니다. 이 함수는 다음 네 가지 값 중 하나를 반환합니다.

    설명

    EOS_FS_NotFriends

    사용자끼리 친구가 아닙니다.

    EOS_FS_InviteSent

    로컬 사용자가 다른 사용자에게 친구 초대를 보냈습니다.

    EOS_FS_InviteReceived

    다른 사용자가 로컬 사용자에게 친구 초대를 보냈습니다.

    EOS_FS_Friends

    사용자끼리 친구입니다.

친구 목록은 언제든지 변할 수 있습니다. 새 친구를 만나는 것과 같은 게임 내 이벤트뿐만 아니라 사용자가 별도 시스템에서 계정을 수정하는 등의 게임 외 이벤트를 통해서도 변합니다. 게임은 EOS_Friends_QueryFriends 를 플레이어의 로그인당 한 번만 호출해야 하며 여러 번 호출하면 안 됩니다. 하지만 플레이어가 로그아웃한 후 다시 로그인하는 경우에는 플레이어의 친구 목록을 다시 쿼리해야 합니다. 게임의 친구 목록 로컬 사본을 최신 상태로 유지하려면 친구 상태 업데이트 알림을 구독합니다.

친구 상태 업데이트 구독하기

친구 상태가 변했을 때 알림을 받으려면 다음 파라미터가 있는 EOS_Friends_AddNotifyFriendsUpdate 를 호출합니다.

파라미터

설명

Options

유일하게 ApiVersion`만을 파라미터로 사용하는 EOS_Friends_AddNotifyFriendsUpdateOptions` 구조입니다.

Callback

EOS_Friends_OnFriendsUpdateCallback 과 일치하는 유효한 콜백 함수입니다.

친구가 업데이트되면 콜백 함수가 호출됩니다. 콜백은 다음 파라미터가 있는 EOS_Friends_OnFriendsUpdateInfo 구조를 받습니다.

파라미터

설명

LocalUserId

친구에 대한 업데이트를 받는 로컬 사용자의 EOS_EpicAccountId 입니다.

TargetUserId

상태가 업데이트된 사용자의 EOS_EpicAccountId 입니다.

PreviousStatus

타깃 사용자 상태의 이전 값입니다.

CurrentStatus

타깃 사용자 상태의 업데이트된 값입니다.

EOS_Friends_AddNotifyFriendsUpdateEOS_NotificationId 를 반환하는데, 이는 필요 없을 때 알림 구독 해지에 사용하는 특수 핸들입니다. 실패한 경우 EOS_INVALID_NOTIFICATIONID 결과 코드를 반환합니다.

친구 상태 업데이트 구독을 해지하려면, 구독 중에 받은 알림 ID를 수락하는 EOS_Friends_RemoveNotifyFriendsUpdate 함수를 사용합니다.

친구 목록 관리하기

이 섹션에서 설명하는 친구 목록 관리 API는 현재 Windows PC의 게임에서만 사용할 수 있습니다.

Nintendo Switch, PlayStation®, Xbox 콘솔 플랫폼에 대한 지원이 예정되어 있습니다. macOS, Linux, Android, iOS에 대한 지원이 예정되어 있습니다.

로컬 사용자가 게임 내 다른 사용자에게 친구 요청을 보낼 수 있게 하려면 EOS_Friends_SendInvite SDK API를 호출합니다. 수신한 친구 요청을 수락하거나 거부하는 게임 UI 기능을 구현하려면 각각 EOS_Friends_AcceptInviteEOS_Friends_RejectInvite SDK API를 사용합니다.

이러한 API를 아직 사용할 수 없는 플랫폼에서는 EOS_NotImplemented 가 반환됩니다.