Información general sobre el administrador social

En este tema se describe cómo la API del administrador social de los servicios XBOX simplifica el seguimiento de los amigos en línea y su actividad de juego. Los servicios XBOX proporcionan un grafo social enriquecido que los títulos pueden usar para diversos escenarios. Usar las API sociales de la API de servicios XBOX (XSAPI) para obtener y mantener información sobre un grafo social es complejo. Mantener esta información actualizada puede ser complicado. No hacerlo correctamente puede provocar problemas de rendimiento, datos obsoletos o limitaciones de velocidad debido a que se llama a los servicios sociales de los servicios XBOX con más frecuencia de la necesaria. El administrador social resuelve este problema haciendo lo siguiente:

Crea una API sencilla a la que llamar.
Crea información actualizada mediante el servicio de actividad en tiempo real (RTA) en segundo plano.
Los desarrolladores pueden llamar a la API del administrador social de forma sincrónica sin ninguna sobrecarga adicional en el servicio.

El administrador social oculta la complejidad de tratar con varias suscripciones RTA y de actualizar los datos de los usuarios, y permitir que los desarrolladores obtengan fácilmente el grafo actualizado que desean crea escenarios interesantes. Para obtener más información, consulte Memoria y rendimiento del administrador social.

Características

El administrador social proporciona las siguientes características.

API social simplificada
Grafo social actualizado
Control sobre el nivel de detalle de la información mostrada
Número reducido de llamadas a los servicios XBOX
- Esto se correlaciona directamente con la reducción general de la latencia en la adquisición de datos
Seguridad para subprocesos
Mantiene los datos actualizados de forma eficiente

Conceptos básicos

Grafo social: se crea un grafo social para un usuario local en el dispositivo. Esto crea una estructura que mantiene actualizada la información sobre todos los amigos de un usuario.

En Windows, solo puede haber un usuario local.

Usuario social de XBOX: un usuario social de XBOX es un conjunto completo de datos sociales asociados a un usuario de un grupo. Grupo de usuarios sociales de XBOX: un grupo es una colección de usuarios que se usa para cosas como rellenar la interfaz de usuario. Hay dos tipos de grupos:

Grupos de filtro: un grupo de filtro toma el grafo social de un usuario local (que realiza la llamada) y devuelve un conjunto de usuarios siempre actualizado según los parámetros de filtro especificados.
Grupos de lista: un grupo de lista toma una lista de usuarios y devuelve una vista siempre actualizada de esos usuarios. Estos usuarios pueden estar fuera de la lista de amigos de un usuario.

Para mantener actualizado un grupo de usuarios sociales, se debe llamar a la función XblSocialManagerDoWork en cada fotograma.

Información general sobre la API

Las siguientes son las API clave que usará con más frecuencia.

Función de la API plana de C: XblSocialManagerAddLocalUser

Agregar un usuario local al administrador social hace que se cree un grafo social para el usuario. Después de agregar un usuario local, se pueden crear grupos de usuarios sociales para ese usuario. El administrador social mantendrá actualizados los grupos de usuarios sociales de XBOX y puede filtrar los grupos de usuarios por presencia o por relación con el usuario. Por ejemplo, se podría crear un grupo de usuarios sociales de XBOX que contenga todos los amigos del usuario que están en línea y jugando al título actual. Este se mantendría actualizado a medida que los amigos empiecen o dejen de jugar al título.

Grupo de usuarios sociales de XBOX

Función de la API plana de C: XblSocialManagerAddLocalUser

Un grupo de usuarios sociales de XBOX es un grupo de usuarios que cumplen determinados criterios, como se ha descrito anteriormente. Los grupos de usuarios sociales de XBOX exponen qué tipo de grupo son, qué usuarios se están rastreando o cuál es su conjunto de filtros, y el usuario local al que pertenece el grupo. Puede encontrar una descripción completa de las API del administrador social en la referencia de la API de XBOX Live. También puede encontrar las API en la documentación del prefijo XblSocialManager.

Uso

Creación de un grupo de usuarios sociales a partir de filtros

En este escenario, quiere una lista de usuarios a partir de un filtro, como una lista de los amigos de un usuario o el subconjunto de amigos que un usuario ha etiquetado como favoritos. API plana de C

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

Para obtener más información, consulte lo siguiente:

Eventos devueltos

Usuario local agregado: se desencadena cuando se completa la carga del grafo social de un usuario. Indica si se produjo algún error durante la inicialización.

API plana de C: XblSocialManagerEventType::LocalUserAdded

Grupo de usuarios sociales cargado: se desencadena cuando se ha creado un grupo de usuarios sociales.

API plana de C: XblSocialManagerEventType::SocialUserGroupLoaded

Usuarios agregados al grafo social: se desencadena cuando se cargan los usuarios.

API plana de C: XblSocialManagerEventType::UsersAddedToSocialGraph

Para obtener más información, consulte lo siguiente:

XblSocialManagerEventType (API plana de C)

Detalles adicionales

API plana de C El ejemplo anterior muestra cómo inicializar el administrador social para un usuario, crear un grupo de usuarios sociales para ese usuario y mantenerlo actualizado. Las opciones de filtrado son las enumeraciones XblPresenceFilter y XblRelationshipFilter. En el bucle del juego, la función XblSocialManagerDoWork actualiza todas las vistas creadas con la instantánea más reciente de los usuarios de ese grupo. Los usuarios de la vista pueden obtenerse llamando a la función XblSocialManagerUserGroupGetUsers. Esta devuelve un XblSocialManagerUserPtrArray, una matriz de objetos XblSocialManagerUser que pertenecen a XSAPI. XblSocialManagerUser contiene la información social, como el gamertag, la imagen de jugador y el URI.

Creación y actualización de un grupo de usuarios sociales a partir de una lista

En este escenario, quiere la información social de una lista de usuarios, como los usuarios de una sesión multijugador. API plana de C

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

Para obtener más información, consulte lo siguiente:

Eventos devueltos

XblSocialManagerEventType::LocalUserAdded. Se desencadena cuando se completa la carga del grafo social del usuario. Indica si se produjo algún error durante la inicialización. XblSocialManagerEventType::SocialUserGroupLoaded. Se desencadena cuando se ha creado un grupo de usuarios sociales y los usuarios rastreados se han agregado al grafo social. XblSocialManagerEventType::UsersAddedToSocialGraph. Se desencadena cuando se cargan los usuarios.

Actualización de un grupo de usuarios sociales a partir de una lista

También puede cambiar la lista de usuarios rastreados en el grupo de usuarios sociales llamando a XblSocialManagerUpdateSocialUserGroup. API plana de C

// 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.
        }
    }
}

Para obtener más información, consulte lo siguiente:

Eventos devueltos

Grupo de usuarios sociales actualizado: se desencadena cuando se completa la actualización del grupo de usuarios sociales.

C++: social_user_group_updated
C: XblSocialManagerEventType::SocialUserGroupUpdated

Usuarios agregados al grafo social: se desencadena cuando se cargan los usuarios. Si los usuarios agregados mediante la lista ya están en el grafo, este evento no se desencadena.

C++: users_added_to_social_graph
C: XblSocialManagerEventType::UsersAddedToSocialGraph

Usuarios eliminados del grafo social: se desencadena cuando los usuarios anteriores se eliminan del grafo social.

C: XblSocialManagerEventType::UsersRemovedFromSocialGraph

El administrador social le indica lo que ha ocurrido, en forma de eventos. Puede usar esos eventos para actualizar la interfaz de usuario o realizar otra lógica. API plana de C

// 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());
        }
    }
}

Para obtener más información, consulte lo siguiente:

Eventos devueltos

XblSocialManagerEventType::LocalUserAdded. Se desencadena cuando se completa la carga del grafo social de un usuario. Indica si se produjo algún error durante la inicialización. XblSocialManagerEventType::SocialUserGroupLoaded. Se desencadena cuando se ha creado un grupo de usuarios sociales. XblSocialManagerEventType::UsersAddedToSocialGraph. Se desencadena cuando se cargan los usuarios. XblSocialManagerEventType::UsersRemovedFromSocialGraph. Se desencadena cuando un usuario se elimina del grafo social. XblSocialManagerEventType::PresenceChanged. Se desencadena cuando cambia la presencia de un usuario en el grafo social. XblSocialManagerEventType::ProfilesChanged. Se desencadena cuando cambia el perfil de un usuario en el grafo social. XblSocialManagerEventType::SocialRelationshipsChanged. Se desencadena cuando cambia la relación entre el usuario local y otro usuario en el grafo social. XblSocialManagerEventType::SocialUserGroupUpdated. Se desencadena cuando se completa una actualización de un grupo de usuarios sociales.

Detalles adicionales

Este ejemplo muestra parte del control adicional que ofrece el administrador social. En lugar de depender de los filtros del grupo de usuarios sociales para proporcionar una lista de usuarios actualizada durante el bucle del juego, el grafo social se inicializa fuera del bucle del juego. El título depende entonces de los eventos que devuelve la función XblSocialManagerDoWork. Events es una lista de XblSocialManagerEvent. Cada XblSocialManagerEvent contiene un cambio en el grafo social que se produjo durante el último fotograma. Por ejemplo, XblSocialManagerEventType::ProfilesChanged y XblSocialManagerEventType::UsersAddedToSocialGraph. Para obtener más información, consulte la documentación de la API XblSocialManagerEvent.

Limpieza

Limpieza de grupos de usuarios sociales

El ejemplo siguiente limpia el grupo de usuarios sociales que se creó. El autor de la llamada también debe eliminar cualquier referencia que tenga a cualquier grupo de usuarios sociales creado, ya que ahora no es válido. API plana de C

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

Para obtener más información, consulte lo siguiente:

XblSocialManagerDestroySocialUserGroup

Limpieza de usuarios locales

Como se muestra en el ejemplo siguiente, eliminar un usuario local elimina el grafo social del usuario cargado y todos los grupos de usuarios sociales que se crearon con ese usuario. Con la API plana de C, no se reciben más eventos para el usuario eliminado. API plana de C

HRESULT hr = XblSocialManagerRemoveLocalUser(user);

Para obtener más información, consulte lo siguiente:

XblSocialManagerRemoveLocalUser

XBOX Services

PlayFab

Características

Conceptos básicos

Información general sobre la API

Grupo de usuarios sociales de XBOX

Uso

Creación de un grupo de usuarios sociales a partir de filtros

Eventos devueltos

Detalles adicionales

Creación y actualización de un grupo de usuarios sociales a partir de una lista

Eventos devueltos

Actualización de un grupo de usuarios sociales a partir de una lista

Eventos devueltos

Eventos devueltos

Detalles adicionales

Limpieza

Limpieza de grupos de usuarios sociales

Limpieza de usuarios locales

​Características

​Conceptos básicos

​Información general sobre la API

​Agregar usuarios locales al administrador social

​Grupo de usuarios sociales de XBOX

​Uso

​Creación de un grupo de usuarios sociales a partir de filtros

​Eventos devueltos

​Detalles adicionales

​Creación y actualización de un grupo de usuarios sociales a partir de una lista

​Eventos devueltos

​Actualización de un grupo de usuarios sociales a partir de una lista

​Eventos devueltos

​Uso de los eventos del administrador social

​Eventos devueltos

​Detalles adicionales

​Limpieza

​Limpieza de grupos de usuarios sociales

​Limpieza de usuarios locales

Características

Conceptos básicos

Información general sobre la API

Agregar usuarios locales al administrador social

Grupo de usuarios sociales de XBOX

Uso

Creación de un grupo de usuarios sociales a partir de filtros

Eventos devueltos

Detalles adicionales

Creación y actualización de un grupo de usuarios sociales a partir de una lista

Eventos devueltos

Actualización de un grupo de usuarios sociales a partir de una lista

Eventos devueltos

Uso de los eventos del administrador social

Eventos devueltos

Detalles adicionales

Limpieza

Limpieza de grupos de usuarios sociales

Limpieza de usuarios locales