- Conocimiento del descriptor de red
- Posesión de un token de entidad
title_player_accountde PlayFab válido - Conocimiento de un identificador de invitación
- Presencia del identificador de entidad de PlayFab del token en la invitación especificada, o que la invitación especificada sea una invitación abierta
Invitaciones
Una invitación (PartyInvitation) es un objeto dentro de una red que concede a un usuario acceso a la red. Las invitaciones se pueden crear y revocar a lo largo de la vida de una red. Una invitación tiene un creador, un identificador único, una configuración de revocabilidad y un conjunto opcional de usuarios especificados como identificadores de entidad. Una red puede tener cualquier número de invitaciones activas, incluida ninguna. Una red siempre se crea con una invitación inicial.
Duración de una invitación
Una invitación está activa desde el momento en que se crea hasta que se revoca.Creación
Hay dos maneras de crear una invitación. La primera es llamando aPartyManager::CreateNewNetwork(). Dado que se requiere una invitación para unirse a una red, debe existir una cuando se crea la red. Esta invitación se conoce como la invitación inicial y tiene algunas propiedades especiales descritas a continuación. La segunda manera es llamando a PartyNetwork::CreateInvitation().
El creador de una invitación es el usuario especificado al llamar a PartyNetwork::CreateInvitation(). La invitación inicial no tiene creador.
Cuando se crea una invitación (o al unirse a una red con una invitación inicial activa), se genera un PartyInvitationCreatedStateChange.
La invitación inicial no permite implícitamente que el creador de una red se una. A menos que se use una invitación abierta, asegúrese de incluir el identificador de entidad del creador en la lista de usuarios.
Enumeración
La enumeración de las invitaciones activas se realiza mediantePartyNetwork::GetInvitations(). Solo se pueden enumerar las invitaciones creadas en el dispositivo local, junto con la invitación inicial si sigue activa.
Revocación
Una invitación se revoca llamando aPartyNetwork::RevokeInvitation(). Solo el creador de una invitación puede revocarla, excepto la invitación inicial, que puede ser revocada por cualquier usuario. Además, una invitación se revoca automáticamente cuando el usuario que la creó se quita de la red.
Cuando se revoca una invitación, se genera un PartyInvitationRevokedStateChange en todos los dispositivos que podían ver la invitación.
Una vez revocada la invitación inicial, no se puede volver a crear. Su identificador se puede reutilizar para una nueva invitación, pero esa nueva invitación no tendrá las propiedades especiales de la invitación inicial.
Revocar una invitación no tiene ningún efecto en los dispositivos y usuarios que ya se han unido a la red. Para quitar un usuario o dispositivo de la red, use
PartyNetwork::KickUser() o PartyNetwork::KickDevice(). Tenga en cuenta que estos métodos aún no están implementados.Configuración de la invitación
La configuración de una invitación se especifica durante la creación mediante la estructuraPartyInvitationConfiguration.
Identificadores
Cada invitación tiene un identificador que la identifica de forma única dentro de la red. Si no se especifica un identificador al crear una invitación, Party asigna uno. Para las llamadas aPartyManager::CreateNewNetwork(), el identificador asignado se devuelve en un parámetro de salida y también se notifica en PartyCreateNewNetworkCompletedStateChange cuando se completa la creación de la red. Para las llamadas a PartyManager::CreateInvitation(), el identificador asignado se puede recuperar del parámetro de salida invitation o del campo invitation en PartyCreateInvitationCompletedStateChange cuando se completa la creación de la invitación.
Aunque el identificador de una invitación debe ser único, después de que se revoque una invitación, su identificador se puede reutilizar al crear una nueva invitación.
Invitación inicial y otras invitaciones
Aunque solo hay un tipo de invitación, la invitación inicial creada por la llamada aPartyManager::CreateNewNetwork() es un poco diferente de las invitaciones creadas más adelante a través de PartyNetwork::CreateInvitation(). Las diferencias se resumen en la tabla siguiente.
Las invitaciones (distintas de la invitación inicial) están ocultas para los demás dispositivos por motivos de privacidad. Consulte el patrón de uso de lista de amigos para ver un ejemplo de por qué esto es importante.
Usuarios e invitaciones abiertas
Una invitación contiene 0 o más usuarios especificados como identificadores de entidadtitle_player_account. Si una invitación contiene usuarios, esa invitación solo concede acceso para unirse a la red a esos usuarios. Sin embargo, si una invitación no contiene usuarios, es una invitación abierta. Cualquier usuario puede unirse a la red con el identificador de una invitación abierta.
En un dispositivo multiusuario, como una consola de juegos, asegúrese de usar la invitación correcta con el usuario correcto. Dependiendo de qué usuarios se especifiquen en cada invitación, es posible que distintos usuarios del dispositivo tengan que usar invitaciones diferentes al autenticar un usuario en la red a través de PartyNetwork::AuthenticateLocalUser().
Inmutabilidad
Una vez creada una invitación, su configuración no se puede cambiar. Sin embargo, después de que una invitación se haya revocado, se puede crear otra con el mismo identificador pero una configuración diferente. Consulte el patrón de uso de invitación única dinámica.Patrones de uso
Las invitaciones de PlayFab Party son sencillas pero flexibles. Hay muchas formas eficaces de usarlas para lograr distintos modelos de acceso a una red.Red abierta
Una red abierta es la más sencilla de entender e implementar. Permite unirse a cualquiera que tenga el descriptor de red y el identificador de invitación. Cree una red abierta pasando null en el parámetroinitialInvitationConfiguration al llamar a PartyManager::CreateNewNetwork(). El identificador de la invitación abierta se devuelve como parámetro de salida. Una vez completada la creación de la red, comparta el descriptor de red y el identificador de invitación para permitir que los usuarios se unan.
Opcionalmente, puede cerrar la red en cualquier momento en el futuro revocando la invitación inicial.
Lista de usuarios estática
Para los juegos que conocen a todos los jugadores de antemano, como un juego creado por emparejamiento sin reposición, una lista de usuarios estática es un patrón sencillo y eficaz. Esto permite unirse a la red solo a los usuarios identificados antes de que comience el juego. Cree una estructuraPartyInvitationConfiguration y agregue los usuarios conocidos a su campo entityIds. Pase esta estructura a PartyManager::CreateNewNetwork(). Una vez completada la creación de la red, comparta el descriptor de red y el identificador de invitación para permitir que los usuarios se unan.
Invitaciones uno a uno
En un juego donde los usuarios existentes invitan individualmente a otros usuarios, un patrón de invitación uno a uno es eficaz y sencillo. Cree una estructuraPartyInvitationConfiguration y agregue solo al creador a su campo entityIds. Pase esta estructura a PartyManager::CreateNewNetwork(). Una vez que el creador se conecte a la red, la invitación inicial se puede revocar opcionalmente. Alternativamente, el creador de la red puede crear una red abierta y luego revocar la invitación inicial tan pronto como se conecte.
Cree otra estructura PartyInvitationConfiguration para cada usuario que deba unirse a la red. Cree invitaciones pasando estas estructuras a PartyNetwork::CreateInvitation(). Comparta el descriptor de red con cada usuario junto con el identificador de invitación de su invitación específica. A medida que los usuarios se unen, pueden repetir este patrón para invitar a más usuarios.
Una vez que un usuario se une, su invitación específica se puede revocar opcionalmente.
Lista de amigos
Para los juegos que quieren permitir que los amigos de cada usuario se unan fácilmente sin crear invitaciones uno a uno, se pueden crear invitaciones que contengan las listas de amigos completas de los usuarios. Después de conectarse a la red, cada usuario creará una estructuraPartyInvitationConfiguration y agregará a cada uno de sus amigos de la plataforma social a su campo entityIds. Pase esta estructura a PartyNetwork::CreateInvitation() y comparta el descriptor de red y el identificador de invitación con los amigos. Cuando la lista de amigos de un usuario cambie, la invitación debe revocarse y debe crearse una nueva invitación con la nueva lista de amigos.
Invitación única dinámica
Muchos juegos tienen una sala u otro servicio externo que controla quién debe unirse a una red determinada. Para mantener una red sincronizada con el servicio externo, se puede usar un patrón de invitación única dinámica. Este patrón usa una única invitación con un identificador conocido. Hay dos variantes de este patrón. El servicio externo puede seleccionar un único usuario para administrar las invitaciones de la red, o puede pedir a todos los usuarios que intenten administrar las invitaciones. En ambos casos, cada vez que cambia el conjunto de usuarios que deben estar en la red, el servicio externo notifica a los usuarios, y los usuarios intentan revocar la invitación actual y crear una nueva invitación con el mismo identificador conocido que contenga el nuevo conjunto completo de usuarios.Administración por un único usuario
Que un único usuario sea responsable de revocar la invitación actual y crear la nueva invitación conduce a una propiedad predecible de la invitación. Sin embargo, el servicio externo debe hacer lo siguiente.- Seleccionar el usuario que administrará las invitaciones.
- Seleccionar un nuevo usuario cuando el usuario anterior abandone la red.
Administración por todos los usuarios
Que todos los usuarios intenten administrar las invitaciones conduce a una propiedad impredecible de la invitación, pero evita que el servicio externo tenga que seleccionar un único usuario. En su lugar, un usuario en cada dispositivo hace lo siguiente.- Intentar revocar la invitación actual. Para la invitación inicial, todos los usuarios lo intentan, pero solo uno lo conseguirá. Para las demás invitaciones, solo el usuario que creó la última invitación puede intentar revocarla, ya que la invitación no es visible para los demás usuarios.
- Intentar crear una nueva invitación. Dado que las invitaciones deben tener identificadores únicos, solo uno de los usuarios lo conseguirá. Ese usuario debe notificar a los demás que es el nuevo propietario de la invitación, ya que la invitación no es visible en los demás dispositivos.
- Cuando el creador de la invitación actual abandone el dispositivo creador, todos los usuarios deben volver a intentar crear una nueva invitación.
Al revocar una invitación y crear una nueva con el mismo identificador, hay una pequeña ventana de tiempo en la que el identificador de invitación no es válido. Si usa este enfoque, es necesario reintentar la llamada a
PartyNetwork::AuthenticateLocalUser() si falla después de un período de espera razonable.Invitación abierta rotativa
Para los juegos en los que una sala u otro servicio externo controla quién debe unirse a una red determinada, una alternativa al patrón de invitación única dinámica es el patrón de invitación abierta rotativa. En este patrón, siempre hay una única invitación abierta. La invitación se revoca y se vuelve a crear con un nuevo identificador cada vez que un usuario que anteriormente tenía permiso para unirse se quita de la lista de usuarios del servicio externo. El identificador de invitación actúa como una contraseña y debe protegerse de forma similar. El patrón se puede implementar en estos pasos:- El servicio externo selecciona un dispositivo para crear la red y especifica el identificador de invitación que se va a usar.
- El servicio externo envía el identificador de invitación a todos los demás usuarios que deben unirse a la red.
- Cuando un nuevo usuario deba unirse a la red, el servicio externo comparte el identificador de invitación actual con ese usuario.
- Cuando un usuario que tiene la invitación actual ya no deba tener permiso para unirse, el servicio externo debe “cambiar la contraseña” haciendo lo siguiente.
- Seleccionar un nuevo identificador de invitación.
- Solicitar que uno o todos los usuarios revoquen la invitación actual y creen una nueva con el identificador de invitación seleccionado. Consulte invitación única dinámica para ver una discusión sobre la administración por un único usuario frente a la administración por todos los usuarios.
- Compartir el nuevo identificador de invitación con todos los usuarios que ahora deban tener permiso para unirse a la red.