Social Manager 개요 - XBOX Game Development Documentation

이 항목에서는 XBOX services Social Manager API가 온라인 친구와 그들의 게임 활동을 추적하는 작업을 어떻게 단순화하는지 설명합니다. XBOX services는 타이틀이 다양한 시나리오에서 사용할 수 있는 풍부한 소셜 그래프를 제공합니다. XBOX Services API(XSAPI)의 소셜 API를 사용하여 소셜 그래프에 대한 정보를 가져오고 유지 관리하는 것은 복잡합니다. 이 정보를 최신 상태로 유지하는 것은 복잡할 수 있습니다. 이를 올바르게 수행하지 않으면 성능 문제, 오래된 데이터가 발생하거나 XBOX services 소셜 서비스가 필요 이상으로 자주 호출되어 throttling이 발생할 수 있습니다. Social Manager는 다음을 통해 이 문제를 해결합니다.

호출할 간단한 API 생성.
백그라운드에서 Real-Time Activity(RTA) 서비스를 사용하여 최신 정보 생성.
개발자는 서비스에 추가 부담을 주지 않고 Social Manager API를 동기적으로 호출할 수 있습니다.

Social Manager는 여러 RTA 구독을 처리하고 사용자의 데이터를 새로 고치는 복잡성을 숨기며, 개발자가 원하는 최신 그래프를 쉽게 얻을 수 있도록 하여 흥미로운 시나리오를 만들어냅니다. 자세한 내용은 Social Manager 메모리 및 성능을 참조하세요.

기능

Social Manager는 다음과 같은 기능을 제공합니다.

단순화된 소셜 API
최신 소셜 그래프
표시되는 정보의 상세도 제어
XBOX services에 대한 호출 수 감소
- 이는 데이터 획득의 전체적인 지연 시간 감소와 직접적으로 연관됩니다
스레드 안전
데이터를 효율적으로 최신 상태로 유지

핵심 개념

소셜 그래프: 장치의 로컬 사용자에 대해 소셜 그래프가 생성됩니다. 이는 사용자의 모든 친구에 대한 정보를 최신 상태로 유지하는 구조를 만듭니다.

Windows에서는 로컬 사용자가 하나만 있을 수 있습니다.

XBOX 소셜 사용자: XBOX 소셜 사용자는 그룹의 사용자와 연관된 전체 소셜 데이터 집합입니다. XBOX 소셜 사용자 그룹: 그룹은 UI 채우기와 같은 용도로 사용되는 사용자 컬렉션입니다. 두 가지 유형의 그룹이 있습니다.

필터 그룹: 필터 그룹은 로컬(호출) 사용자의 소셜 그래프를 가져와 지정된 필터 매개 변수를 기반으로 일관되게 새로 고쳐지는 사용자 집합을 반환합니다.
목록 그룹: 목록 그룹은 사용자 목록을 가져와 해당 사용자들의 일관되게 새로 고쳐진 뷰를 반환합니다. 이러한 사용자는 사용자의 친구 목록 외부에 있을 수 있습니다.

소셜 사용자 그룹을 최신 상태로 유지하려면 매 프레임마다 XblSocialManagerDoWork 함수를 호출해야 합니다.

API 개요

가장 자주 사용하는 주요 API는 다음과 같습니다.

Flat C API 함수: XblSocialManagerAddLocalUser

Social Manager에 로컬 사용자를 추가하면 해당 사용자에 대한 소셜 그래프가 생성됩니다. 로컬 사용자가 추가된 후에는 해당 사용자에 대한 소셜 사용자 그룹을 만들 수 있습니다. Social Manager는 XBOX 소셜 사용자 그룹을 최신 상태로 유지하며, 상태 또는 사용자와의 관계별로 사용자 그룹을 필터링할 수 있습니다. 예를 들어, 온라인 상태이며 현재 타이틀을 플레이 중인 사용자의 모든 친구를 포함하는 XBOX 소셜 사용자 그룹을 만들 수 있습니다. 친구가 타이틀 플레이를 시작하거나 중지할 때 이 그룹이 최신 상태로 유지됩니다.

XBOX 소셜 사용자 그룹

Flat C API 함수: XblSocialManagerAddLocalUser

XBOX 소셜 사용자 그룹은 앞서 설명한 대로 특정 기준을 충족하는 사용자 그룹입니다. XBOX 소셜 사용자 그룹은 그룹 유형, 추적 중인 사용자 또는 필터 집합, 그리고 그룹이 속한 로컬 사용자를 노출합니다. Social Manager API의 전체 설명은 XBOX Live API 참조에서 확인할 수 있습니다. XblSocialManager 접두사 문서에서도 해당 API를 찾을 수 있습니다.

사용법

필터에서 소셜 사용자 그룹 만들기

이 시나리오에서는 사용자의 친구 목록 또는 사용자가 즐겨찾기로 태그한 친구의 하위 집합과 같이 필터에서 사용자 목록을 얻고자 합니다. Flat C API

HRESULT hr = XblSocialManagerAddLocalUser(user, extraLevelDetail, nullptr);

XblPresenceFilter presenceFilter{ XblPresenceFilter::All };
XblRelationshipFilter relationshipFilter{ XblRelationshipFilter::Friends };

XblSocialManagerUserGroupHandle groupHandle{ nullptr };
HRESULT hr = XblSocialManagerCreateSocialUserGroupFromFilters(user, presenceFilter, relationshipFilter, &groupHandle);

if (SUCCEEDED(hr))
{
    state.groups.insert(groupHandle);
}

// Some update loop in the game.
while (true)
{
    const XblSocialManagerEvent* events{ nullptr };
    size_t eventCount{ 0 };
    HRESULT hr = XblSocialManagerDoWork(&events, &eventCount);
    if (SUCCEEDED(hr))
    {
        for (size_t i = 0; i < eventCount; i++)
        {
            // Act on the event.
        }
    }
}

자세한 내용은 다음을 참조하세요.

반환되는 이벤트

로컬 사용자 추가됨: 사용자의 소셜 그래프 로딩이 완료되면 트리거됩니다. 초기화 중 오류가 발생한 경우 이를 나타냅니다.

Flat C API: XblSocialManagerEventType::LocalUserAdded

소셜 사용자 그룹 로드됨: 소셜 사용자 그룹이 생성되면 트리거됩니다.

Flat C API: XblSocialManagerEventType::SocialUserGroupLoaded

소셜 그래프에 사용자 추가됨: 사용자가 로드되면 트리거됩니다.

Flat C API: XblSocialManagerEventType::UsersAddedToSocialGraph

자세한 내용은 다음을 참조하세요.

XblSocialManagerEventType (flat C API)

추가 세부 정보

Flat C API 이전 예제는 사용자에 대해 Social Manager를 초기화하고, 해당 사용자에 대한 소셜 사용자 그룹을 만들고, 최신 상태로 유지하는 방법을 보여줍니다. 필터링 옵션은 XblPresenceFilter 및 XblRelationshipFilter 열거형입니다. 게임 루프에서 XblSocialManagerDoWork 함수는 만들어진 모든 뷰를 해당 그룹에 있는 사용자의 최신 스냅샷으로 업데이트합니다. 뷰의 사용자는 XblSocialManagerUserGroupGetUsers 함수를 호출하여 얻을 수 있습니다. 이 함수는 XSAPI가 소유하는 XblSocialManagerUser 개체의 배열인 XblSocialManagerUserPtrArray를 반환합니다. XblSocialManagerUser는 gamertag, gamerpic, URI와 같은 소셜 정보를 포함합니다.

목록에서 소셜 사용자 그룹 만들기 및 업데이트

이 시나리오에서는 멀티플레이어 세션의 사용자와 같은 사용자 목록의 소셜 정보를 얻고자 합니다. Flat C API

HRESULT hr = XblSocialManagerAddLocalUser(user, extraLevelDetail, nullptr);

// List of xuids to track.
std::vector<uint64_t> xuids
{
    listXuids.begin() + static_cast<int>(offset),
    listXuids.begin() + static_cast<int>(offset + count) 
}; 

XblSocialManagerUserGroupHandle groupHandle{ nullptr };
HRESULT hr = XblSocialManagerCreateSocialUserGroupFromList(user, xuids.data(), xuids.size(), &groupHandle);

if (SUCCEEDED(hr))
{
    state.groups.insert(groupHandle);
}

// Some update loop in the game.
while (true)
{
    const XblSocialManagerEvent* events{ nullptr };
    size_t eventCount{ 0 };
    HRESULT hr = XblSocialManagerDoWork(&events, &eventCount);
    if (SUCCEEDED(hr))
    {
        for (size_t i = 0; i < eventCount; i++)
        {
            // Act on the event
        }
    }
}

자세한 내용은 다음을 참조하세요.

반환되는 이벤트

XblSocialManagerEventType::LocalUserAdded. 사용자의 소셜 그래프 로딩이 완료되면 트리거됩니다. 초기화 중 오류가 발생한 경우 이를 나타냅니다. XblSocialManagerEventType::SocialUserGroupLoaded. 소셜 사용자 그룹이 생성되고 추적된 사용자가 소셜 그래프에 추가되면 트리거됩니다. XblSocialManagerEventType::UsersAddedToSocialGraph. 사용자가 로드되면 트리거됩니다.

목록에서 소셜 사용자 그룹 업데이트

XblSocialManagerUpdateSocialUserGroup을 호출하여 소셜 사용자 그룹에서 추적되는 사용자 목록을 변경할 수도 있습니다. Flat C API

// New list of xuids to track.
std::vector<uint64_t> xuids
{ 
    listXuids.begin() + static_cast<int>(offset),
    listXuids.begin() + static_cast<int>(offset + count)
};

HRESULT hr = XblSocialManagerUpdateSocialUserGroup(group, xuids.data(), xuids.size());

// Some update loop in the game.
while (true)
{
    const XblSocialManagerEvent* events{ nullptr };
    size_t eventCount{ 0 };
    HRESULT hr = XblSocialManagerDoWork(&events, &eventCount);
    if (SUCCEEDED(hr))
    {
        for (size_t i = 0; i < eventCount; i++)
        {
            // Act on the event.
        }
    }
}

자세한 내용은 다음을 참조하세요.

반환되는 이벤트

소셜 사용자 그룹 업데이트됨: 소셜 사용자 그룹 업데이트가 완료되면 트리거됩니다.

C++: social_user_group_updated
C: XblSocialManagerEventType::SocialUserGroupUpdated

소셜 그래프에 사용자 추가됨: 사용자가 로드되면 트리거됩니다. 목록을 통해 추가된 사용자가 이미 그래프에 있는 경우 이 이벤트는 트리거되지 않습니다.

C++: users_added_to_social_graph
C: XblSocialManagerEventType::UsersAddedToSocialGraph

소셜 그래프에서 사용자 제거됨: 이전 사용자가 소셜 그래프에서 제거되면 트리거됩니다.

C: XblSocialManagerEventType::UsersRemovedFromSocialGraph

Social Manager는 발생한 상황을 이벤트 형태로 알려줍니다. 이러한 이벤트를 사용하여 UI를 업데이트하거나 다른 로직을 수행할 수 있습니다. Flat C API

// Some update loop in the game.
while (true)
{
    const XblSocialManagerEvent* events{ nullptr };
    size_t eventCount{ 0 };
    HRESULT hr = XblSocialManagerDoWork(&events, &eventCount);
    if (SUCCEEDED(hr))
    {
        for (size_t i = 0; i < eventCount; i++)
        {
            // Act on the event.
            auto& socialEvent = events[i];
            std::stringstream ss;
            ss << "XblSocialManagerDoWork: Event of type " << eventTypesMap[socialEvent.eventType] << std::endl;
            for (uint32_t i = 0; i < XBL_SOCIAL_MANAGER_MAX_AFFECTED_USERS_PER_EVENT; i++)
            {
                if (socialEvent.usersAffected[i] != nullptr)
                {
                    if (i == 0)
                    {
                        ss << "Users affected: " << std::endl;
                    }
                    ss << "\t" << socialEvent.usersAffected[i]->gamertag << std::endl;
                }
            }
            LogToFile(ss.str().c_str());
        }
    }
}

자세한 내용은 다음을 참조하세요.

반환되는 이벤트

XblSocialManagerEventType::LocalUserAdded. 사용자의 소셜 그래프 로딩이 완료되면 트리거됩니다. 초기화 중 오류가 발생한 경우 이를 나타냅니다. XblSocialManagerEventType::SocialUserGroupLoaded. 소셜 사용자 그룹이 생성되면 트리거됩니다. XblSocialManagerEventType::UsersAddedToSocialGraph. 사용자가 로드되면 트리거됩니다. XblSocialManagerEventType::UsersRemovedFromSocialGraph. 사용자가 소셜 그래프에서 제거되면 트리거됩니다. XblSocialManagerEventType::PresenceChanged. 소셜 그래프의 사용자 상태가 변경되면 트리거됩니다. XblSocialManagerEventType::ProfilesChanged. 소셜 그래프의 사용자 프로필이 변경되면 트리거됩니다. XblSocialManagerEventType::SocialRelationshipsChanged. 로컬 사용자와 소셜 그래프의 다른 사용자 간의 관계가 변경되면 트리거됩니다. XblSocialManagerEventType::SocialUserGroupUpdated. 소셜 사용자 그룹 업데이트가 완료되면 트리거됩니다.

추가 세부 정보

이 예제는 Social Manager가 제공하는 몇 가지 추가 제어를 보여줍니다. 게임 루프 중에 새로 고쳐진 사용자 목록을 제공하기 위해 소셜 사용자 그룹 필터에 의존하는 대신, 소셜 그래프는 게임 루프 외부에서 초기화됩니다. 그런 다음 타이틀은 XblSocialManagerDoWork 함수가 반환하는 이벤트에 의존합니다. 이벤트는 XblSocialManagerEvent 목록입니다. 각 XblSocialManagerEvent는 마지막 프레임 동안 발생한 소셜 그래프의 변경 사항을 포함합니다. 예를 들면 XblSocialManagerEventType::ProfilesChanged 및 XblSocialManagerEventType::UsersAddedToSocialGraph가 있습니다. 자세한 내용은 XblSocialManagerEvent API 문서를 참조하세요.

정리

소셜 사용자 그룹 정리

다음 예제는 만들어진 소셜 사용자 그룹을 정리합니다. 호출자는 만들어진 소셜 사용자 그룹에 대한 참조가 이제 유효하지 않으므로 이러한 참조도 제거해야 합니다. Flat C API

HRESULT hr = XblSocialManagerDestroySocialUserGroup(groupHandle);
if (SUCCEEDED(hr))
{
    state.groups.erase(groupHandle);
}

자세한 내용은 다음을 참조하세요.

XblSocialManagerDestroySocialUserGroup

로컬 사용자 정리

다음 예제와 같이 로컬 사용자를 제거하면 로드된 사용자의 소셜 그래프와 해당 사용자를 사용하여 만든 소셜 사용자 그룹이 제거됩니다. Flat C API에서는 제거된 사용자에 대해 더 이상 이벤트를 받지 않습니다. Flat C API

HRESULT hr = XblSocialManagerRemoveLocalUser(user);

자세한 내용은 다음을 참조하세요.

XblSocialManagerRemoveLocalUser

​기능

​핵심 개념

​API 개요

​Social Manager에 로컬 사용자 추가

​XBOX 소셜 사용자 그룹

​사용법

​필터에서 소셜 사용자 그룹 만들기

​반환되는 이벤트

​추가 세부 정보

​목록에서 소셜 사용자 그룹 만들기 및 업데이트

​반환되는 이벤트

​목록에서 소셜 사용자 그룹 업데이트

​반환되는 이벤트

​Social Manager 이벤트 사용

​반환되는 이벤트

​추가 세부 정보

​정리

​소셜 사용자 그룹 정리

​로컬 사용자 정리

기능

핵심 개념

API 개요

Social Manager에 로컬 사용자 추가

XBOX 소셜 사용자 그룹

사용법

필터에서 소셜 사용자 그룹 만들기

반환되는 이벤트

추가 세부 정보

목록에서 소셜 사용자 그룹 만들기 및 업데이트

반환되는 이벤트

목록에서 소셜 사용자 그룹 업데이트

반환되는 이벤트

Social Manager 이벤트 사용

반환되는 이벤트

추가 세부 정보

정리

소셜 사용자 그룹 정리

로컬 사용자 정리