친구와 게임을 즐기고 온라인에서 새로운 사람을 만나는 것은 많은 온라인 서비스에서 중요한 부분입니다. 에픽 온라인 서비스(Epic Online Services, EOS) SDK는 친구 인터페이스(Friends Interface) 를 사용하여 로그인한 사용자의 친구 목록을 가져옵니다.
친구 목록은 온라인 서비스의 서버를 통해 저장되며, 친구가 계속해서 추가/제거되거나 친구가 게임에서 자신의 정보 사용에 동의/철회하기 때문에 세션 중에도 친구 목록은 계속 변경될 수 있습니다.
친구 목록 쿼리가 완료되면 친구 인터페이스는 다른 모든 친구 인터페이스 함수가 사용할 로컬 캐시를 생성합니다. 추가로, SDK는 친구 제거, 초대 수락, 게임에서 사용하는 친구의 정보 이용 동의 철회와 같이 친구 목록에 변화를 주는 이벤트에 대한 알림을 백엔드로부터 받게 됩니다.
친구 인터페이스를 사용하려면 제품에서 에픽 계정 서비스(Epic Account Services, EAS) 가 활성 상태여야 하며, 친구 목록 데이터에 액세스하려면 사용자의 동의가 필요합니다. 데브 포털에서 EAS를 활성화하거나 에픽 문서에서 자세한 내용을 확인할 수 있습니다.
친구 목록 가져오기 및 캐시하기
플레이어의 친구 목록을 가져오려면 EOS_HFriends 핸들이 필요합니다. 플랫폼 인터페이스 함수인 EOS_Platform_GetFriendsInterface 를 통해 이 핸들을 얻을 수 있습니다. 로그인한 사용자의 친구 목록에 액세스하려면 친구 인터페이스 함수에 이 핸들이 필요합니다. EOS_Friends_QueryFriends 함수는 이 게임을 최소 1회 이상 플레이했고 동의를 제출한 친구에게만 반환되는 점에 유의하세요. 게임을 구매하거나, 플레이어가 에픽 계정 서비스를 사용하여 애플리케이션에 로그인하고 에픽 계정 서비스가 계정에 액세스하도록 허용하면 동의가 제출됩니다.
플레이어의 친구 목록을 처리하는 첫 단계는 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_AS_FriendsManagement 의 범위는 로그인한 플레이어가 소셜 그래프(예: 친구 상태)를 변경하거나 보류 중인 변경사항을 볼 수 있는지 여부를 제어합니다. 기본적으로 이 범위는 활성화되지 않습니다. EOS SDK는 게임에 친구(EOS_FS_Friends) 와 친구가 아닌 상태(EOS_FS_NotFriends) 만 반환합니다. 소셜 오버레이에서는 남아 있는 보낸 초대(EOS_FS_Invite Sent) 및 받은 초대(EOS_FS_Invite Received) 상태를 포함하여 보류 중인 초대를 처리합니다.
이러한 상태는 헤더에서 사용할 수 있지만 게임에서 이러한 상태를 처리할 필요는 없습니다.
친구 목록은 언제든지 변할 수 있습니다. 새 친구를 만나는 것과 같은 게임 내 이벤트뿐만 아니라 플레이어가 별도 시스템에서 계정을 수정하는 등의 게임 외 이벤트를 통해서도 변합니다. 게임은 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_AddNotifyFriendsUpdate 는 EOS_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_AcceptInvite 및 EOS_Friends_RejectInvite SDK API를 사용하면 됩니다.
이러한 API는 아직 이용할 수 없는 플랫폼에서는 EOS_NotImplemented 를 반환합니다.