Visão geral do Social Manager - XBOX Game Development Documentation

Este tópico descreve como a API do Social Manager dos serviços do XBOX simplifica o acompanhamento dos amigos online e de sua atividade de jogo. Os serviços do XBOX fornecem um grafo social avançado que os títulos podem usar em vários cenários. Usar as APIs sociais da XBOX Services API (XSAPI) para obter e manter informações sobre um grafo social é complexo. Manter essas informações atualizadas pode ser complicado. Não fazer isso corretamente pode resultar em problemas de desempenho, dados desatualizados ou limitação de taxa, porque os serviços sociais do XBOX são chamados com mais frequência do que o necessário. O Social Manager resolve esse problema fazendo o seguinte:

Criando uma API simples de chamar.
Criando informações atualizadas por meio do serviço Real-Time Activity (RTA) em segundo plano.
Os desenvolvedores podem chamar a API do Social Manager de forma síncrona, sem nenhuma sobrecarga extra no serviço.

O Social Manager oculta a complexidade de lidar com várias assinaturas do RTA e de atualizar os dados dos usuários, e permitir que os desenvolvedores obtenham facilmente o grafo atualizado que desejam cria cenários interessantes. Para obter mais informações, consulte Memória e desempenho do Social Manager.

Recursos

O Social Manager oferece os recursos a seguir.

API social simplificada
Grafo social atualizado
Controle sobre o nível de detalhes das informações exibidas
Número reduzido de chamadas aos serviços do XBOX
- Isso se correlaciona diretamente com a redução geral da latência na aquisição de dados
Seguro para threads
Mantém os dados atualizados de forma eficiente

Conceitos principais

Grafo social: um grafo social é criado para um usuário local no dispositivo. Isso cria uma estrutura que mantém atualizadas as informações sobre todos os amigos de um usuário.

No Windows, pode haver apenas um usuário local.

Usuário social do XBOX: um usuário social do XBOX é um conjunto completo de dados sociais associado a um usuário de um grupo. Grupo de usuários sociais do XBOX: um grupo é um conjunto de usuários usado para coisas como preencher a interface. Há dois tipos de grupos:

Grupos de filtro: um grupo de filtro usa o grafo social de um usuário local (chamador) e retorna um conjunto de usuários sempre atualizado com base nos parâmetros de filtro especificados.
Grupos de lista: um grupo de lista recebe uma lista de usuários e retorna uma visão sempre atualizada desses usuários. Esses usuários podem estar fora da lista de amigos de um usuário.

Para manter um grupo de usuários sociais atualizado, a função XblSocialManagerDoWork precisa ser chamada a cada quadro.

Visão geral da API

Você usará com mais frequência as principais APIs a seguir.

Função da API C simples: XblSocialManagerAddLocalUser

Adicionar um usuário local ao Social Manager faz com que um grafo social seja criado para o usuário. Depois que um usuário local é adicionado, grupos de usuários sociais podem ser criados para esse usuário. O Social Manager manterá os grupos de usuários sociais do XBOX atualizados e pode filtrar os grupos de usuários por presença ou por relacionamento com o usuário. Por exemplo, é possível criar um grupo de usuários sociais do XBOX que contenha todos os amigos do usuário que estão online e jogando o título atual. Esse grupo seria mantido atualizado à medida que os amigos começam ou param de jogar o título.

Grupo de usuários sociais do XBOX

Função da API C simples: XblSocialManagerAddLocalUser

Um grupo de usuários sociais do XBOX é um grupo de usuários que atendem a determinados critérios, conforme descrito anteriormente. Os grupos de usuários sociais do XBOX expõem que tipo de grupo eles são, quais usuários estão sendo acompanhados ou qual é o conjunto de filtros aplicado a eles e o usuário local ao qual o grupo pertence. Você pode encontrar uma descrição completa das APIs do Social Manager na referência da API do XBOX Live. Você também pode encontrar as APIs na documentação com o prefixo XblSocialManager.

Uso

Criando um grupo de usuários sociais a partir de filtros

Neste cenário, você deseja uma lista de usuários a partir de um filtro, como uma lista dos amigos de um usuário ou o subconjunto de amigos que um usuário marcou como favoritos. API C simples

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 obter mais informações, consulte:

Eventos retornados

Usuário local adicionado: é disparado quando o carregamento do grafo social de um usuário é concluído. Indica se ocorreu algum erro durante a inicialização.

API C simples: XblSocialManagerEventType::LocalUserAdded

Grupo de usuários sociais carregado: é disparado quando um grupo de usuários sociais é criado.

API C simples: XblSocialManagerEventType::SocialUserGroupLoaded

Usuários adicionados ao grafo social: é disparado quando os usuários são carregados.

API C simples: XblSocialManagerEventType::UsersAddedToSocialGraph

Para obter mais informações, consulte:

XblSocialManagerEventType (API C simples)

Detalhes adicionais

API C simples O exemplo anterior mostra como inicializar o Social Manager para um usuário, criar um grupo de usuários sociais para esse usuário e mantê-lo atualizado. As opções de filtragem são os enums XblPresenceFilter e XblRelationshipFilter. No loop do jogo, a função XblSocialManagerDoWork atualiza todas as visões criadas com o instantâneo mais recente dos usuários daquele grupo. Os usuários da visão podem ser obtidos chamando a função XblSocialManagerUserGroupGetUsers. Ela retorna um XblSocialManagerUserPtrArray, uma matriz de objetos XblSocialManagerUser de propriedade da XSAPI. XblSocialManagerUser contém as informações sociais, como gamertag, gamerpic e URI.

Criar e atualizar um grupo de usuários sociais a partir de uma lista

Neste cenário, você deseja as informações sociais de uma lista de usuários, como os usuários de uma sessão multiplayer. API C simples

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 obter mais informações, consulte:

Eventos retornados

XblSocialManagerEventType::LocalUserAdded. É disparado quando o carregamento do grafo social do usuário é concluído. Indica se ocorreu algum erro durante a inicialização. XblSocialManagerEventType::SocialUserGroupLoaded. É disparado quando um grupo de usuários sociais é criado e os usuários acompanhados são adicionados ao grafo social. XblSocialManagerEventType::UsersAddedToSocialGraph. É disparado quando os usuários são carregados.

Atualizando um grupo de usuários sociais a partir de uma lista

Você também pode alterar a lista de usuários acompanhados no grupo de usuários sociais chamando XblSocialManagerUpdateSocialUserGroup. API C simples

// 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 obter mais informações, consulte:

Eventos retornados

Grupo de usuários sociais atualizado: é disparado quando a atualização do grupo de usuários sociais é concluída.

C++: social_user_group_updated
C: XblSocialManagerEventType::SocialUserGroupUpdated

Usuários adicionados ao grafo social: é disparado quando os usuários são carregados. Se os usuários adicionados pela lista já estiverem no grafo, esse evento não será disparado.

C++: users_added_to_social_graph
C: XblSocialManagerEventType::UsersAddedToSocialGraph

Usuários removidos do grafo social: é disparado quando os usuários anteriores são removidos do grafo social.

C: XblSocialManagerEventType::UsersRemovedFromSocialGraph

O Social Manager informa o que aconteceu na forma de eventos. Você pode usar esses eventos para atualizar sua interface ou executar outra lógica. API C simples

// 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 obter mais informações, consulte:

Eventos retornados

XblSocialManagerEventType::LocalUserAdded. É disparado quando o carregamento do grafo social de um usuário é concluído. Indica se ocorreu algum erro durante a inicialização. XblSocialManagerEventType::SocialUserGroupLoaded. É disparado quando um grupo de usuários sociais é criado. XblSocialManagerEventType::UsersAddedToSocialGraph. É disparado quando os usuários são carregados. XblSocialManagerEventType::UsersRemovedFromSocialGraph. É disparado quando um usuário é removido do grafo social. XblSocialManagerEventType::PresenceChanged. É disparado quando a presença de um usuário no grafo social muda. XblSocialManagerEventType::ProfilesChanged. É disparado quando o perfil de um usuário no grafo social muda. XblSocialManagerEventType::SocialRelationshipsChanged. É disparado quando o relacionamento entre o usuário local e outro usuário no grafo social muda. XblSocialManagerEventType::SocialUserGroupUpdated. É disparado quando uma atualização de um grupo de usuários sociais é concluída.

Detalhes adicionais

Este exemplo mostra parte do controle adicional oferecido pelo Social Manager. Em vez de depender dos filtros do grupo de usuários sociais para fornecer uma lista de usuários atualizada durante o loop do jogo, o grafo social é inicializado fora do loop do jogo. Em seguida, o título depende dos eventos retornados pela função XblSocialManagerDoWork. Eventos é uma lista de XblSocialManagerEvent. Cada XblSocialManagerEvent contém uma alteração no grafo social que ocorreu durante o último quadro. Por exemplo, XblSocialManagerEventType::ProfilesChanged e XblSocialManagerEventType::UsersAddedToSocialGraph. Para obter mais informações, consulte a documentação da API XblSocialManagerEvent.

Limpeza

Limpando grupos de usuários sociais

O exemplo a seguir limpa o grupo de usuários sociais que foi criado. O chamador também deve remover quaisquer referências que tenha a qualquer grupo de usuários sociais criado, pois ele agora é inválido. API C simples

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

Para obter mais informações, consulte:

XblSocialManagerDestroySocialUserGroup

Limpando usuários locais

Conforme mostrado no exemplo a seguir, remover um usuário local remove o grafo social carregado do usuário e quaisquer grupos de usuários sociais criados usando esse usuário. Com a API C simples, nenhum outro evento é recebido para o usuário removido. API C simples

HRESULT hr = XblSocialManagerRemoveLocalUser(user);

Para obter mais informações, consulte:

XblSocialManagerRemoveLocalUser

​Recursos

​Conceitos principais

​Visão geral da API

​Adicionando usuários locais ao Social Manager

​Grupo de usuários sociais do XBOX

​Uso

​Criando um grupo de usuários sociais a partir de filtros

​Eventos retornados

​Detalhes adicionais

​Criar e atualizar um grupo de usuários sociais a partir de uma lista

​Eventos retornados

​Atualizando um grupo de usuários sociais a partir de uma lista

​Eventos retornados

​Usando os eventos do Social Manager

​Eventos retornados

​Detalhes adicionais

​Limpeza

​Limpando grupos de usuários sociais

​Limpando usuários locais

Recursos

Conceitos principais

Visão geral da API

Adicionando usuários locais ao Social Manager

Grupo de usuários sociais do XBOX

Uso

Criando um grupo de usuários sociais a partir de filtros

Eventos retornados

Detalhes adicionais

Criar e atualizar um grupo de usuários sociais a partir de uma lista

Eventos retornados

Atualizando um grupo de usuários sociais a partir de uma lista

Eventos retornados

Usando os eventos do Social Manager

Eventos retornados

Detalhes adicionais

Limpeza

Limpando grupos de usuários sociais

Limpando usuários locais