- Conhecimento do descritor de rede
- Posse de um token de entidade
title_player_accountválido do PlayFab - Conhecimento de um identificador de convite
- Presença da ID de entidade do PlayFab correspondente ao token no convite especificado, ou o convite especificado ser um convite aberto
Convites
Um convite (PartyInvitation) é um objeto dentro de uma rede que concede ao usuário acesso à rede. Os convites podem ser criados e revogados durante todo o tempo de vida de uma rede. Um convite tem um criador, um identificador exclusivo, uma configuração de revogabilidade e um conjunto de usuários opcional especificado como IDs de entidade. Uma rede pode ter qualquer número de convites ativos, inclusive nenhum. Uma rede é sempre criada com um convite inicial.
Tempo de vida do convite
Um convite fica ativo desde o momento em que é criado até ser revogado.Criação
Há duas maneiras de criar um convite. A primeira é chamandoPartyManager::CreateNewNetwork(). Como um convite é necessário para ingressar em uma rede, um convite deve existir quando uma rede é criada. Esse convite é conhecido como convite inicial e tem algumas propriedades especiais descritas abaixo. A segunda maneira é chamando PartyNetwork::CreateInvitation().
O criador de um convite é o usuário especificado ao chamar PartyNetwork::CreateInvitation(). O convite inicial não tem criador.
Quando um convite é criado (ou ao ingressar em uma rede com um convite inicial ativo), um PartyInvitationCreatedStateChange é gerado.
O convite inicial não permite implicitamente que o criador de uma rede ingresse nela. A menos que um convite aberto esteja sendo usado, certifique-se de incluir a ID de entidade do criador na lista de usuários.
Enumeração
A enumeração dos convites ativos é feita usandoPartyNetwork::GetInvitations(). Somente os convites criados no dispositivo local, junto com o convite inicial, se ele ainda estiver ativo, podem ser enumerados.
Revogação
Um convite é revogado chamandoPartyNetwork::RevokeInvitation(). Somente o criador de um convite pode revogá-lo, exceto no caso do convite inicial, que pode ser revogado por qualquer usuário. Além disso, um convite é revogado automaticamente quando o usuário que o criou é removido da rede.
Quando um convite é revogado, um PartyInvitationRevokedStateChange é gerado em todos os dispositivos que podiam ver o convite.
Depois que o convite inicial é revogado, ele não pode ser criado novamente. Seu identificador pode ser reutilizado para um novo convite, mas esse novo convite não terá as propriedades especiais do convite inicial.
Revogar um convite não tem efeito sobre os dispositivos e usuários que já ingressaram na rede. Para remover um usuário ou dispositivo da rede, use
PartyNetwork::KickUser() ou PartyNetwork::KickDevice(). Observe que esses métodos ainda não foram implementados.Configuração do convite
A configuração de um convite é especificada durante a criação usando a structPartyInvitationConfiguration.
Identificadores
Cada convite tem um identificador que o identifica de forma exclusiva dentro da rede. Se um identificador não for especificado ao criar um convite, o Party atribuirá um. Para chamadas aPartyManager::CreateNewNetwork(), o identificador atribuído é retornado em um parâmetro de saída e também relatado em PartyCreateNewNetworkCompletedStateChange quando a criação da rede é concluída. Para chamadas a PartyManager::CreateInvitation(), o identificador atribuído pode ser recuperado do parâmetro de saída invitation ou do campo invitation em PartyCreateInvitationCompletedStateChange quando a criação do convite é concluída.
Embora o identificador de um convite deva ser exclusivo, depois que um convite é revogado, seu identificador pode ser reutilizado ao criar um novo convite.
Convite inicial e outros convites
Embora haja apenas um tipo de convite, o convite inicial criado pela chamada aPartyManager::CreateNewNetwork() é um pouco diferente dos convites criados posteriormente por meio de PartyNetwork::CreateInvitation(). As diferenças estão resumidas na tabela abaixo.
Os convites (exceto o convite inicial) ficam ocultos para os outros dispositivos por motivos de privacidade. Confira o padrão de uso de lista de amigos para ver um exemplo de por que isso é importante.
Usuários e convites abertos
Um convite contém 0 ou mais usuários especificados como IDs de entidadetitle_player_account. Se um convite contiver usuários, ele concederá acesso para ingressar na rede apenas a esses usuários. No entanto, se um convite não contiver usuários, ele será um convite aberto. Qualquer usuário pode ingressar na rede com o identificador de um convite aberto.
Em um dispositivo multiusuário, como um console de jogos, certifique-se de usar o convite correto com o usuário correto. Dependendo de quais usuários estão especificados em cada convite, é possível que usuários diferentes no dispositivo precisem usar convites diferentes ao autenticar um usuário na rede por meio de PartyNetwork::AuthenticateLocalUser().
Imutabilidade
Depois que um convite é criado, sua configuração não pode ser alterada. No entanto, depois que um convite é revogado, outro pode ser criado com o mesmo identificador, mas com uma configuração diferente. Confira o padrão de uso de convite único dinâmico.Padrões de uso
Os convites do PlayFab Party são simples, mas flexíveis. Há muitas maneiras eficazes de usá-los para obter diferentes modelos de acesso a uma rede.Rede aberta
Uma rede aberta é a mais simples de entender e implementar. Ela permite que qualquer pessoa com o descritor de rede e o identificador do convite ingresse. Crie uma rede aberta passando nulo para o parâmetroinitialInvitationConfiguration ao chamar PartyManager::CreateNewNetwork(). O identificador do convite aberto é retornado como um parâmetro de saída. Depois que a criação da rede for concluída, compartilhe o descritor de rede e o identificador do convite para permitir que os usuários ingressem.
Opcionalmente, você pode fechar a rede a qualquer momento no futuro revogando o convite inicial.
Lista de usuários estática
Para jogos que conhecem todos os jogadores com antecedência, como um jogo criado por matchmaking sem preenchimento, uma lista de usuários estática é um padrão fácil e eficaz. Isso permite que apenas os usuários identificados antes do início do jogo ingressem na rede. Crie uma structPartyInvitationConfiguration e adicione os usuários conhecidos ao campo entityIds dela. Passe essa struct para PartyManager::CreateNewNetwork(). Depois que a criação da rede for concluída, compartilhe o descritor de rede e o identificador do convite para permitir que os usuários ingressem.
Convites individuais
Em um jogo em que os usuários existentes convidam outros usuários individualmente, um padrão de convites individuais é eficaz e simples. Crie uma structPartyInvitationConfiguration e adicione apenas o criador ao campo entityIds dela. Passe essa struct para PartyManager::CreateNewNetwork(). Depois que o criador se conectar à rede, o convite inicial poderá ser revogado, opcionalmente. Como alternativa, o criador da rede pode criar uma rede aberta e, em seguida, revogar o convite inicial assim que se conectar.
Crie outra struct PartyInvitationConfiguration para cada usuário que deve ingressar na rede. Crie convites passando essas structs para PartyNetwork::CreateInvitation(). Compartilhe o descritor de rede com cada usuário, junto com o identificador do convite específico dele. À medida que os usuários ingressam, eles podem repetir esse padrão para convidar mais usuários.
Depois que um usuário ingressar, o convite específico dele poderá ser revogado, opcionalmente.
Lista de amigos
Para jogos que desejam permitir que os amigos de cada usuário ingressem facilmente sem criar convites individuais, é possível criar convites que contenham as listas de amigos completas dos usuários. Depois de se conectar à rede, cada usuário criará uma structPartyInvitationConfiguration e adicionará cada um dos seus amigos da plataforma social ao campo entityIds dela. Passe essa struct para PartyNetwork::CreateInvitation() e compartilhe o descritor de rede e o identificador do convite com os amigos. Quando a lista de amigos de um usuário mudar, o convite deverá ser revogado e um novo convite deverá ser criado com a nova lista de amigos.
Convite único dinâmico
Muitos jogos têm um lobby ou outro serviço externo que controla quem deve ingressar em uma determinada rede. Para manter uma rede sincronizada com o serviço externo, um padrão de convite único dinâmico pode ser usado. Esse padrão usa um único convite com um identificador conhecido. Há duas variantes desse padrão. O serviço externo pode selecionar um único usuário para gerenciar os convites da rede ou pode pedir que todos os usuários tentem gerenciar os convites. Em ambos os casos, sempre que o conjunto de usuários que deve estar na rede muda, o serviço externo notifica os usuários, e os usuários tentam revogar o convite atual e criar um novo convite com o mesmo identificador conhecido contendo o novo conjunto completo de usuários.Gerenciamento por um único usuário
Ter um único usuário responsável por revogar o convite atual e criar o novo convite leva a uma propriedade previsível do convite. No entanto, o serviço externo precisa fazer o seguinte.- Selecionar o usuário que gerenciará os convites.
- Selecionar um novo usuário quando o usuário anterior sair da rede.
Gerenciamento por todos os usuários
Fazer com que todos os usuários tentem gerenciar os convites leva a uma propriedade imprevisível do convite, mas evita que o serviço externo precise selecionar um único usuário. Em vez disso, um usuário em cada dispositivo faz o seguinte.- Tenta revogar o convite atual. No caso do convite inicial, todos os usuários tentam fazer isso, mas apenas um terá êxito. No caso de outros convites, somente o usuário que criou o último convite pode tentar revogá-lo, pois o convite não fica visível para os outros usuários.
- Tenta criar um novo convite. Como os convites devem ter identificadores exclusivos, apenas um dos usuários terá êxito. Esse usuário deve notificar os outros de que é o novo proprietário do convite, pois o convite não fica visível em outros dispositivos.
- Quando o criador do convite atual sai do dispositivo criador, todos os usuários devem tentar novamente criar um novo convite.
Ao revogar um convite e criar um novo com o mesmo identificador, há uma pequena janela de tempo em que o identificador do convite é inválido. Se você estiver usando essa abordagem, será necessário repetir a chamada a
PartyNetwork::AuthenticateLocalUser() caso ela falhe, após um período de espera razoável.Convite aberto rotativo
Para jogos em que um lobby ou outro serviço externo controla quem deve ingressar em uma determinada rede, uma alternativa ao padrão de convite único dinâmico é o padrão de convite aberto rotativo. Nesse padrão, há sempre um único convite aberto. O convite é revogado e recriado com um novo identificador sempre que um usuário que antes tinha permissão para ingressar é removido da lista de usuários do serviço externo. O identificador do convite funciona como uma senha e deve ser protegido da mesma forma. O padrão pode ser implementado nestas etapas:- O serviço externo seleciona um dispositivo para criar a rede e especifica o identificador de convite a ser usado.
- O serviço externo envia o identificador do convite para todos os outros usuários que devem ingressar na rede.
- Quando um novo usuário deve ingressar na rede, o serviço externo compartilha o identificador do convite atual com esse usuário.
- Quando um usuário que tem o convite atual não deve mais ter permissão para ingressar, o serviço externo precisa “alterar a senha” fazendo o seguinte.
- Selecionar um novo identificador de convite.
- Solicitar que um ou todos os usuários revoguem o convite atual e criem um novo com o identificador de convite selecionado. Confira convite único dinâmico para ver uma discussão sobre o gerenciamento por um único usuário em comparação com o gerenciamento por todos os usuários.
- Compartilhar o novo identificador de convite com todos os usuários que agora devem ter permissão para ingressar na rede.