소셜 관리자 개요

아티클
05/09/2023

이 항목에서는 Xbox 서비스 소셜 관리자 API가 온라인 친구 및 게임 활동 추적을 단순화하는 방법을 설명합니다.

Xbox 서비스는 타이틀이 다양한 시나리오에 사용할 수 있는 풍부한 소셜 그래프를 제공합니다. Xbox 서비스 API(XSAPI)에서 소셜 API를 사용하여 소셜 그래프에 대한 정보를 얻고 유지 관리하는 것은 복잡합니다. 이 정보를 최신 상태로 유지하는 것은 복잡할 수 있습니다. 이 작업을 올바르게 수행하지 않으면 Xbox 서비스 소셜 서비스가 필요 이상으로 자주 호출되기 때문에 성능 문제, 오래된 데이터 또는 제한이 발생할 수 있습니다.

소셜 관리자는 다음을 수행하여 이 문제를 해결합니다.

간단한 API를 만들어서 호출합니다.
백그라운드에서 실시간 활동(RTA) 서비스를 사용하여 최신 정보 생성.
개발자는 서비스에 추가적인 부담을 주지 않고 소셜 관리자 API를 동기식으로 호출할 수 있습니다.

소셜 관리자는 여러 RTA 구독을 처리하는 복잡성을 숨기고 사용자를 위해 데이터를 새로 고치고 개발자가 원하는 최신 그래프를 쉽게 얻을 수 있도록 하여 흥미로운 시나리오를 만듭니다.

자세한 내용은 소셜 관리자 메모리 및 성능을 참조하세요.

기능

소셜 관리자는 다음과 같은 기능을 제공합니다.

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

핵심 개념

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

참고 항목

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

Xbox 소셜 사용자: Xbox 소셜 사용자는 그룹의 사용자와 연결된 소셜 데이터의 전체 집합입니다.

Xbox 소셜 사용자 그룹: 그룹은 UI 채우기와 같은 작업에 사용되는 사용자 모음입니다. 두 가지 유형의 그룹이 있습니다.

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

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

API 개요

다음의 핵심 API를 사용하는 경우가 가장 많습니다.

플랫 C API 함수: XblSocialManagerAddLocalUser

소셜 관리자에 로컬 사용자를 추가하면 사용자에 대한 소셜 그래프가 만들어집니다. 로컬 사용자가 추가되면 해당 사용자에 대한 소셜 사용자 그룹을 만들 수 있습니다.

소셜 관리자는 Xbox 소셜 사용자 그룹을 최신 상태로 유지하고 현재 상태 또는 사용자와의 관계를 기준으로 사용자 그룹을 필터링할 수 있습니다. 예를 들어, 온라인 상태이고 현재 타이틀을 플레이하는 모든 사용자 친구를 포함하는 Xbox 소셜 사용자 그룹을 만들 수 있습니다. 이 그룹은 친구가 타이틀 플레이를 시작하거나 중지하면 최신 상태로 유지됩니다.

플랫 C API 함수: XblSocialManagerAddLocalUser

Xbox 소셜 사용자 그룹은 앞에서 설명한 대로 특정 기준을 충족하는 사용자 그룹입니다. Xbox 소셜 사용자 그룹은 그룹 유형, 추적 중인 사용자 또는 필터 세트가 무엇인지, 그룹이 속한 로컬 사용자를 표시합니다.

Xbox Live API 참조에서 소셜 관리자 API에 대한 자세한 설명을 확인할 수 있습니다. 또한 XblSocialManager 접두사 문서에서도 API를 확인할 수 있습니다.

사용

이 시나리오에서는 사용자의 친구 목록 또는 사용자가 즐겨찾기로 태그를 지정한 친구 하위 집합과 같은 필터의 사용자 목록을 원합니다.

플랫 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(플랫 C API)

추가 정보

Flat C API 이전 예는 사용자에 대한 소셜 관리자를 초기화하고 해당 사용자에 대한 소셜 사용자 그룹을 생성하고 최신 상태로 유지하는 방법을 보여줍니다.

필터링 옵션은 XblPresenceFilter 및 XblRelationshipFilter 열거형입니다.

게임 루프에서 XblSocialManagerDoWork 함수는 해당 그룹 사용자의 최신 스냅샷으로 만든 모든 보기를 업데이트합니다.

보기의 사용자는 XblSocialManagerUserGroupGetUsers 함수를 호출하여 가져올 수 있습니다. XSAPI가 소유한 XblSocialManagerUser 개체의 배열인 XblSocialManagerUserPtrArray을(를) 반환합니다. XblSocialManagerUser는 게이머태그, 게이머 사진 및 URI와 같은 소셜 정보를 포함합니다.

이 시나리오에서는 멀티 플레이어 세션의 사용자 같은 사용자 목록의 소셜 정보가 필요합니다.

플랫 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을 호출하여 소셜 사용자 그룹에서 추적된 사용자 목록을 변경할 수도 있습니다.

플랫 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

소셜 관리자는 발생한 상황을 이벤트 형식으로 알려줍니다. 이벤트를 사용하여 UI를 업데이트하거나 다른 논리를 수행할 수 있습니다.

플랫 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. 소셜 사용자 그룹에 대한 업데이트가 완료되면 트리거됩니다.

추가 정보

이 예는 소셜 관리자에서 제공하는 몇 가지 추가 제어를 보여줍니다.

소셜 사용자 그룹 필터로 게임 루프 도중 새로운 사용자 목록을 제공하는 대신 소셜 그래프가 게임 루프 외부에서 초기화됩니다. 그런 다음 타이틀은 XblSocialManagerDoWork 함수에서 반환된 이벤트를 사용합니다.

이벤트는 XblSocialManagerEvent의 목록입니다. 각 XblSocialManagerEvent에는 마지막 프레임 동안 발생한 소셜 그래프의 변경 내용이 포함됩니다. 예: XblSocialManagerEventType::ProfilesChanged 및 XblSocialManagerEventType::UsersAddedToSocialGraph.

자세한 내용은 XblSocialManagerEvent API 설명서를 참조하세요.

정리

다음 예에서는 생성된 소셜 사용자 그룹을 정리합니다. 또한 호출자는 생성된 소셜 사용자 그룹이 이제 유효하지 않기 때문에 모든 참조를 제거해야 합니다.

플랫 C API

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

자세한 내용은 다음을 참조하십시오.

XblSocialManagerDestroySocialUserGroup

로컬 사용자 정리

다음 예와 같이 로컬 사용자를 제거하면 로드된 사용자의 소셜 그래프와 해당 사용자를 사용하여 생성된 모든 소셜 사용자 그룹이 제거됩니다.

플랫 C API를 사용하면 제거된 사용자에 대해 더 이상 이벤트를 수신하지 않습니다.

플랫 C API

HRESULT hr = XblSocialManagerRemoveLocalUser(user);

자세한 내용은 다음을 참조하십시오.

XblSocialManagerRemoveLocalUser

다음을 통해 공유

기능

핵심 개념

API 개요

사용

반환된 이벤트

추가 정보

반환된 이벤트

반환된 이벤트

반환된 이벤트

추가 정보

정리

로컬 사용자 정리

추가 리소스

다음을 통해 공유

기능

핵심 개념

API 개요

소셜 관리자에 로컬 사용자 추가

Xbox 소셜 사용자 그룹

사용

필터에서 소셜 사용자 그룹 생성

반환된 이벤트

추가 정보

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

반환된 이벤트

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

반환된 이벤트

소셜 관리자 이벤트 사용

반환된 이벤트

추가 정보

정리

소셜 사용자 그룹 정리

로컬 사용자 정리

추가 리소스