Social Manager overview - XBOX Game Development Documentation

This topic describes how the XBOX services Social Manager API simplifies keeping track of online friends and their gaming activity. XBOX services provides a rich social graph that titles can use for various scenarios. Using the social APIs in the XBOX Services API (XSAPI) to get and maintain information about a social graph is complex. Keeping this information up to date can be complicated. Not doing this correctly can result in performance issues, stale data, or being throttled because the XBOX services social services are called more frequently than necessary. Social Manager solves this problem by doing the following:

Creating a simple API to call.
Creating up-to-date information by using the Real-Time Activity (RTA) service in the background.
Developers can call the Social Manager API synchronously without any extra strain on the service.

Social Manager masks the complexity of dealing with multiple RTA subscriptions, and refreshing data for users and allowing developers to easily get the up-to-date graph they want creates interesting scenarios. For more information, see Social Manager memory and performance.

Features

Social Manager provides the following features.

Simplified social API
Up-to-date social graph
Control over the verbosity of information displayed
Reduced number of calls to XBOX services
- This directly correlates to overall latency reduction in data acquisition
Thread-safe
Efficiently keeps data up to date

Core concepts

Social graph: A social graph is created for a local user on the device. This creates a structure that keeps information about all of a user’s friends up to date.

On Windows, there can be only one local user.

XBOX social user: An XBOX social user is a full set of social data associated with a user from a group. XBOX social user group: A group is a collection of users that is used for things like populating UI. There are two types of groups:

Filter groups: A filter group takes a local (calling) user’s social graph and returns a consistently fresh set of users based on specified filter parameters.
List groups: A list group takes a list of users and returns a consistently fresh view of those users. These users can be outside a user’s friends list.

To keep a social user group up to date, the XblSocialManagerDoWork function must be called every frame.

API overview

You will most frequently use the following key APIs.

Flat C API function: XblSocialManagerAddLocalUser

Adding a local user to Social Manager causes a social graph to be created for the user. After a local user is added, social user groups can be created for that user. The Social Manager will keep XBOX social user groups up to date and can filter user groups by presence or relationship to the user. For example, an XBOX social user group containing all the user’s friends who are online and playing the current title could be created. This would be kept up to date as friends start or stop playing the title.

Flat C API function: XblSocialManagerAddLocalUser

An XBOX social user group is a group of users that meet certain criteria, as described previously described. XBOX social user groups expose what type of a group they are, which users are being tracked or what the filter set is on them, and the local user that the group belongs to. You can find a complete description of the Social Manager APIs in the XBOX Live API reference. You can also find the APIs in the XblSocialManager prefix documentation.

Usage

In this scenario, you want a list of users from a filter, such as a list of a user’s Friends or the subset of friends that a user has tagged as favorite. 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.
        }
    }
}

For more information, see the following:

Events returned

Local user added: Triggers when loading of a user’s social graph is complete. Indicates if any errors occurred during initialization.

Flat C API: XblSocialManagerEventType::LocalUserAdded

Social user group loaded: Triggers when a social user group has been created.

Flat C API: XblSocialManagerEventType::SocialUserGroupLoaded

Users added to social graph: Triggers when users are loaded in.

Flat C API: XblSocialManagerEventType::UsersAddedToSocialGraph

For more information, see the following:

XblSocialManagerEventType (flat C API)

Additional details

Flat C API The previous example shows how to initialize Social Manager for a user, create a social user group for that user, and keep it up to date. The filtering options are the XblPresenceFilter and XblRelationshipFilter enums. In the game loop, the XblSocialManagerDoWork function updates all created views with the latest snapshot of the users in that group. The users in the view can be obtained by calling the XblSocialManagerUserGroupGetUsers function. It returns an XblSocialManagerUserPtrArray, an array of XblSocialManagerUser objects owned by XSAPI. XblSocialManagerUser contains the social information such as gamertag, gamerpic, and URI. In this scenario, you want the social information of a list of users such as users in a multiplayer session. 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
        }
    }
}

For more information, see the following:

Events returned

XblSocialManagerEventType::LocalUserAdded. Triggers when loading of user’s social graph is complete. Indicates if any errors occurred during initialization. XblSocialManagerEventType::SocialUserGroupLoaded. Triggers when a social user group has been created, and the tracked users have been added to the social graph. XblSocialManagerEventType::UsersAddedToSocialGraph. Triggers when users are loaded in. You can also change the list of tracked users in the social user group by calling 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.
        }
    }
}

For more information, see the following:

Events returned

Social user group updated: Triggers when the social user group update is complete.

C++: social_user_group_updated
C: XblSocialManagerEventType::SocialUserGroupUpdated

Users added to social graph: Triggers when users are loaded in. If users added via list are already in graph, this event doesn’t trigger.

C++: users_added_to_social_graph
C: XblSocialManagerEventType::UsersAddedToSocialGraph

Users removed from social graph: Triggers when the previous users are removed from the social graph.

C: XblSocialManagerEventType::UsersRemovedFromSocialGraph

Social Manager tells you what happened, in the form of events. You can use those events to update your UI or perform other logic. 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());
        }
    }
}

For more information, see the following:

Events returned

XblSocialManagerEventType::LocalUserAdded. Triggers when the loading of a user’s social graph is complete. Indicates if any errors occurred during initialization. XblSocialManagerEventType::SocialUserGroupLoaded. Triggers when a social user group has been created. XblSocialManagerEventType::UsersAddedToSocialGraph. Triggers when users are loaded in. XblSocialManagerEventType::UsersRemovedFromSocialGraph. Triggers when a user is removed from the social graph. XblSocialManagerEventType::PresenceChanged. Triggers when the presence of a user in the social graph changes. XblSocialManagerEventType::ProfilesChanged. Triggers when the profile of a user in the social graph changes. XblSocialManagerEventType::SocialRelationshipsChanged. Triggers when the relationship between the local user and another user in the social graph changes. XblSocialManagerEventType::SocialUserGroupUpdated. Triggers when an update to a social user group is complete.

Additional details

This example shows some of the additional control that’s offered by Social Manager. Rather than relying on the social user group filters to provide a fresh user list during the game loop, the social graph is initialized outside the game loop. The title then relies on the events that are returned by the XblSocialManagerDoWork function. Events is a list of XblSocialManagerEvent. Each XblSocialManagerEvent contains a change to the social graph that occurred during the last frame. For example, XblSocialManagerEventType::ProfilesChanged and XblSocialManagerEventType::UsersAddedToSocialGraph. For more information, see the XblSocialManagerEvent API documentation.

Cleanup

The following example cleans up the social user group that was created. The caller should also remove any references they have to any created social user group because it’s now invalid. Flat C API

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

For more information, see the following:

XblSocialManagerDestroySocialUserGroup

Cleaning up local users

As shown in the following example, removing a local user removes the loaded user’s social graph and any social user groups that were created using that user. With the flat C API, receive no further events for the removed user. Flat C API

HRESULT hr = XblSocialManagerRemoveLocalUser(user);

For more information, see the following:

XblSocialManagerRemoveLocalUser

​Features

​Core concepts

​API overview

​Adding local users to Social Manager

​XBOX social user group

​Usage

​Creating a social user group from filters

​Events returned

​Additional details

​Create and update a social user group from list

​Events returned

​Updating social user group from list

​Events returned

​Using Social Manager events

​Events returned

​Additional details

​Cleanup

​Cleaning up social user groups

​Cleaning up local users

Features

Core concepts

API overview

Adding local users to Social Manager

XBOX social user group

Usage

Creating a social user group from filters

Events returned

Additional details

Create and update a social user group from list

Events returned

Updating social user group from list

Events returned

Using Social Manager events

Events returned

Additional details

Cleanup

Cleaning up social user groups

Cleaning up local users