> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Social Manager overview

> How the XBOX services Social Manager API simplifies the social graph, using Real-Time Activity to keep friends and presence data fresh with synchronous calls.

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](/services/xbox-services/community/social-manager/concepts/live-socmgr-mem-perf).

## 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.

<Note>On Windows, there can be only one local user.</Note>

**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](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdowork) function must be called every frame.

## API overview

You will most frequently use the following key APIs.

### Adding local users to Social Manager

* Flat C API function: [XblSocialManagerAddLocalUser](/reference/live/xsapi-c/social_manager_c/functions/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.

### XBOX social user group

* Flat C API function: [XblSocialManagerAddLocalUser](/reference/live/xsapi-c/social_manager_c/functions/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](https://aka.ms/xboxliveuwpdocs).
You can also find the APIs in the `XblSocialManager` prefix documentation.

## Usage

### Creating a social user group from filters

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**

```cpp theme={null}
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:

* [XblPresenceFilter](/reference/live/xsapi-c/social_manager_c/enums/xblpresencefilter)
* [XblRelationshipFilter](/reference/live/xsapi-c/social_manager_c/enums/xblrelationshipfilter)
* [XblSocialManagerAddLocalUser](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanageraddlocaluser)
* [XblSocialManagerCreateSocialUserGroupFromFilters](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagercreatesocialusergroupfromfilters)
* [XblSocialManagerDoWork](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdowork)
* [XblSocialManagerEvent](/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanagerevent)

#### 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](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::LocalUserAdded`

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

* Flat C API: [XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::SocialUserGroupLoaded`

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

* Flat C API: [XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::UsersAddedToSocialGraph`

For more information, see the following:

* [XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/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](/reference/live/xsapi-c/social_manager_c/enums/xblpresencefilter) and [XblRelationshipFilter](/reference/live/xsapi-c/social_manager_c/enums/xblrelationshipfilter) enums.

In the game loop, the [XblSocialManagerDoWork](/reference/live/xsapi-c/social_manager_c/functions/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](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerusergroupgetusers) function. It returns an `XblSocialManagerUserPtrArray`, an array of [XblSocialManagerUser](/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanageruser) objects owned by XSAPI.
[XblSocialManagerUser](/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanageruser) contains the social information such as gamertag, gamerpic, and URI.

### Create and update a social user group from list

In this scenario, you want the social information of a list of users such as users in a multiplayer session.

**Flat C API**

```cpp theme={null}
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:

* [XblSocialManagerAddLocalUser](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanageraddlocaluser)
* [XblSocialManagerCreateSocialUserGroupFromList](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagercreatesocialusergroupfromlist)
* [XblSocialManagerDoWork](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdowork)
* [XblSocialManagerEvent](/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanagerevent)

#### Events returned

[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::LocalUserAdded`. Triggers when loading of user's social graph is complete. Indicates if any errors occurred during initialization.

[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::SocialUserGroupLoaded`. Triggers when a social user group has been created, and the tracked users have been added to the social graph.

[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::UsersAddedToSocialGraph`. Triggers when users are loaded in.

### Updating social user group from list

You can also change the list of tracked users in the social user group by calling [XblSocialManagerUpdateSocialUserGroup](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerupdatesocialusergroup).

**Flat C API**

```cpp theme={null}
// 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:

* [XblSocialManagerDoWork](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdowork)
* [XblSocialManagerEvent](/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanagerevent)
* [XblSocialManagerUpdateSocialUserGroup](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerupdatesocialusergroup)

#### Events returned

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

* C++: `social_user_group_updated`
* C: [XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/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](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)::UsersAddedToSocialGraph

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

* C: [XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)::UsersRemovedFromSocialGraph

### Using Social Manager events

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**

```cpp theme={null}
// 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:

* [XblSocialManagerDoWork](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdowork)
* [XblSocialManagerEvent](/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanagerevent)

#### Events returned

[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::LocalUserAdded`. Triggers when the loading of a user's social graph is complete. Indicates if any errors occurred during initialization.

[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::SocialUserGroupLoaded`. Triggers when a social user group has been created.

[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::UsersAddedToSocialGraph`. Triggers when users are loaded in.

[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::UsersRemovedFromSocialGraph`. Triggers when a user is removed from the social graph.

[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::PresenceChanged`. Triggers when the presence of a user in the social graph changes.

[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::ProfilesChanged`. Triggers when the profile of a user in the social graph changes.

[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::SocialRelationshipsChanged`. Triggers when the relationship between the local user and another user in the social graph changes.

[XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/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](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerdowork) function.

*Events* is a list of [XblSocialManagerEvent](/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanagerevent). Each [XblSocialManagerEvent](/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanagerevent) contains a change to the social graph that occurred during the last frame.
For example, [XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::ProfilesChanged` and [XblSocialManagerEventType](/reference/live/xsapi-c/social_manager_c/enums/xblsocialmanagereventtype)`::UsersAddedToSocialGraph`.

For more information, see the [XblSocialManagerEvent](/reference/live/xsapi-c/social_manager_c/structs/xblsocialmanagerevent) API documentation.

### Cleanup

#### Cleaning up social user groups

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**

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

For more information, see the following:

* [XblSocialManagerDestroySocialUserGroup](/reference/live/xsapi-c/social_manager_c/functions/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**

```cpp theme={null}
HRESULT hr = XblSocialManagerRemoveLocalUser(user);
```

For more information, see the following:

* [XblSocialManagerRemoveLocalUser](/reference/live/xsapi-c/social_manager_c/functions/xblsocialmanagerremovelocaluser)


## Related topics

- [Social Manager](/services/xbox-services/community/social-manager/live-social-manager-nav.md)
- [Overview of Social features](/services/xbox-services/community/live-social-overview.md)
- [Getting a social relationship](/services/xbox-services/community/people-system/how-to/live-getting-a-social-relationship.md)
- [Community](/services/xbox-services/community/index.md)
- [Social manager](/services/xbox-services/community/social-manager/index.md)