- La connaissance du descripteur de réseau
- La possession d’un jeton d’entité PlayFab
title_player_accountvalide - La connaissance d’un identificateur d’invitation
- La présence de l’ID d’entité PlayFab correspondant au jeton dans l’invitation spécifiée, ou le fait que l’invitation spécifiée soit une invitation ouverte
Invitations
Une invitation (PartyInvitation) est un objet au sein d’un réseau qui accorde à un utilisateur l’accès au réseau. Des invitations peuvent être créées et révoquées tout au long de la durée de vie d’un réseau. Une invitation possède un créateur, un identificateur unique, un paramètre de révocabilité et un ensemble d’utilisateurs facultatif spécifiés sous forme d’ID d’entité. Un réseau peut avoir un nombre quelconque d’invitations actives, y compris aucune. Un réseau est toujours créé avec une invitation initiale.
Durée de vie d’une invitation
Une invitation est active à partir de sa création jusqu’à sa révocation.Création
Il existe deux façons de créer une invitation. La première consiste à appelerPartyManager::CreateNewNetwork(). Comme une invitation est nécessaire pour rejoindre un réseau, il doit en exister une lors de la création d’un réseau. Cette invitation est appelée invitation initiale et possède certaines propriétés particulières décrites ci-dessous. La seconde consiste à appeler PartyNetwork::CreateInvitation().
Le créateur d’une invitation est l’utilisateur spécifié lors de l’appel de PartyNetwork::CreateInvitation(). L’invitation initiale n’a pas de créateur.
Lorsqu’une invitation est créée (ou lorsque vous rejoignez un réseau ayant une invitation initiale active), un PartyInvitationCreatedStateChange est généré.
L’invitation initiale n’autorise pas implicitement le créateur d’un réseau à le rejoindre. Sauf si une invitation ouverte est utilisée, assurez-vous d’inclure l’ID d’entité du créateur dans la liste des utilisateurs.
Énumération
L’énumération des invitations actives s’effectue à l’aide dePartyNetwork::GetInvitations(). Seules les invitations créées sur l’appareil local, ainsi que l’invitation initiale si elle est toujours active, peuvent être énumérées.
Révocation
Une invitation est révoquée en appelantPartyNetwork::RevokeInvitation(). Seul le créateur d’une invitation peut la révoquer, à l’exception de l’invitation initiale, qui peut être révoquée par n’importe quel utilisateur. En outre, une invitation est automatiquement révoquée lorsque l’utilisateur qui l’a créée est retiré du réseau.
Lorsqu’une invitation est révoquée, un PartyInvitationRevokedStateChange est généré sur tous les appareils qui pouvaient voir l’invitation.
Une fois l’invitation initiale révoquée, elle ne peut pas être recréée. Son identificateur peut être réutilisé pour une nouvelle invitation, mais cette nouvelle invitation n’aura pas les propriétés particulières de l’invitation initiale.
La révocation d’une invitation n’a aucun effet sur les appareils et les utilisateurs qui ont déjà rejoint le réseau. Pour retirer un utilisateur ou un appareil du réseau, utilisez
PartyNetwork::KickUser() ou PartyNetwork::KickDevice(). Notez que ces méthodes ne sont pas encore implémentées.Configuration d’une invitation
La configuration d’une invitation est spécifiée lors de sa création à l’aide de la structurePartyInvitationConfiguration.
Identificateurs
Chaque invitation possède un identificateur qui l’identifie de façon unique au sein du réseau. Si aucun identificateur n’est spécifié lors de la création d’une invitation, Party en attribue un. Pour les appels àPartyManager::CreateNewNetwork(), l’identificateur attribué est retourné dans un paramètre de sortie et également signalé dans PartyCreateNewNetworkCompletedStateChange à la fin de la création du réseau. Pour les appels à PartyManager::CreateInvitation(), l’identificateur attribué peut être récupéré à partir du paramètre de sortie invitation ou du champ invitation de PartyCreateInvitationCompletedStateChange à la fin de la création de l’invitation.
Bien qu’un identificateur d’invitation doive être unique, une fois une invitation révoquée, son identificateur peut être réutilisé lors de la création d’une nouvelle invitation.
Invitation initiale et autres invitations
Bien qu’il n’existe qu’un seul type d’invitation, l’invitation initiale créée par l’appel àPartyManager::CreateNewNetwork() diffère légèrement des invitations créées ultérieurement au moyen de PartyNetwork::CreateInvitation(). Les différences sont résumées dans le tableau ci-dessous.
Les invitations (autres que l’invitation initiale) sont masquées aux autres appareils pour des raisons de confidentialité. Consultez le modèle d’utilisation de la liste d’amis pour un exemple illustrant l’importance de ce point.
Utilisateurs et invitations ouvertes
Une invitation contient 0 ou plusieurs utilisateurs spécifiés sous forme d’ID d’entitétitle_player_account. Si une invitation contient des utilisateurs, elle n’accorde l’accès au réseau qu’à ces utilisateurs. En revanche, si une invitation ne contient aucun utilisateur, il s’agit d’une invitation ouverte. N’importe quel utilisateur peut rejoindre le réseau avec l’identificateur d’une invitation ouverte.
Sur un appareil multi-utilisateur, comme une console de jeu, assurez-vous d’utiliser la bonne invitation avec le bon utilisateur. Selon les utilisateurs spécifiés dans chaque invitation, il est possible que différents utilisateurs de l’appareil doivent utiliser des invitations différentes lors de l’authentification d’un utilisateur dans le réseau au moyen de PartyNetwork::AuthenticateLocalUser().
Immuabilité
Une fois une invitation créée, sa configuration ne peut pas être modifiée. Cependant, une fois une invitation révoquée, une autre peut être créée avec le même identificateur mais une configuration différente. Consultez le modèle d’utilisation d’invitation unique dynamique.Modèles d’utilisation
Les invitations PlayFab Party sont simples mais flexibles. Il existe de nombreuses façons efficaces de les utiliser pour obtenir différents modèles d’accès à un réseau.Réseau ouvert
Un réseau ouvert est le plus simple à comprendre et à mettre en œuvre. Il permet à toute personne disposant du descripteur de réseau et de l’identificateur d’invitation de le rejoindre. Créez un réseau ouvert en transmettant null pour le paramètreinitialInvitationConfiguration lors de l’appel de PartyManager::CreateNewNetwork(). L’identificateur de l’invitation ouverte est retourné en tant que paramètre de sortie. Une fois la création du réseau terminée, partagez le descripteur de réseau et l’identificateur d’invitation pour permettre aux utilisateurs de rejoindre le réseau.
Vous pouvez éventuellement fermer le réseau à tout moment ultérieur en révoquant l’invitation initiale.
Liste d’utilisateurs statique
Pour les jeux qui connaissent tous les joueurs à l’avance, comme une partie créée par matchmaking sans backfill, une liste d’utilisateurs statique est un modèle simple et efficace. Elle permet uniquement aux utilisateurs identifiés avant le début de la partie de rejoindre le réseau. Créez une structurePartyInvitationConfiguration et ajoutez les utilisateurs connus à son champ entityIds. Transmettez cette structure à PartyManager::CreateNewNetwork(). Une fois la création du réseau terminée, partagez le descripteur de réseau et l’identificateur d’invitation pour permettre aux utilisateurs de rejoindre le réseau.
Invitations individuelles
Dans un jeu où les utilisateurs existants invitent individuellement d’autres utilisateurs, un modèle d’invitations individuelles est efficace et simple. Créez une structurePartyInvitationConfiguration et ajoutez uniquement le créateur à son champ entityIds. Transmettez cette structure à PartyManager::CreateNewNetwork(). Une fois que le créateur s’est connecté au réseau, l’invitation initiale peut éventuellement être révoquée. Le créateur du réseau peut également créer un réseau ouvert, puis révoquer l’invitation initiale dès qu’il s’est connecté.
Créez une autre structure PartyInvitationConfiguration pour chaque utilisateur qui doit rejoindre le réseau. Créez des invitations en transmettant ces structures à PartyNetwork::CreateInvitation(). Partagez le descripteur de réseau avec chaque utilisateur, ainsi que l’identificateur de son invitation spécifique. À mesure que des utilisateurs rejoignent le réseau, ils peuvent répéter ce modèle pour inviter d’autres utilisateurs.
Une fois qu’un utilisateur a rejoint le réseau, son invitation spécifique peut éventuellement être révoquée.
Liste d’amis
Pour les jeux qui souhaitent permettre aux amis de chaque utilisateur de rejoindre facilement le réseau sans créer d’invitations individuelles, il est possible de créer des invitations contenant l’intégralité des listes d’amis des utilisateurs. Après s’être connecté au réseau, chaque utilisateur crée une structurePartyInvitationConfiguration et ajoute chacun de ses amis de la plateforme sociale à son champ entityIds. Transmettez cette structure à PartyNetwork::CreateInvitation(), puis partagez le descripteur de réseau et l’identificateur d’invitation avec les amis. Lorsque la liste d’amis d’un utilisateur change, l’invitation doit être révoquée et une nouvelle invitation doit être créée avec la nouvelle liste d’amis.
Invitation unique dynamique
De nombreux jeux disposent d’un lobby ou d’un autre service externe qui contrôle qui doit rejoindre un réseau donné. Pour maintenir un réseau synchronisé avec le service externe, un modèle d’invitation unique dynamique peut être utilisé. Ce modèle utilise une seule invitation avec un identificateur bien connu. Ce modèle comporte deux variantes. Le service externe peut soit sélectionner un seul utilisateur pour gérer les invitations du réseau, soit demander à tous les utilisateurs de tenter de gérer les invitations. Dans les deux cas, chaque fois que l’ensemble des utilisateurs qui doivent faire partie du réseau change, le service externe en informe les utilisateurs, qui tentent alors de révoquer l’invitation actuelle et de créer une nouvelle invitation avec le même identificateur bien connu, contenant le nouvel ensemble complet d’utilisateurs.Gestion par un seul utilisateur
Confier à un seul utilisateur la responsabilité de révoquer l’invitation actuelle et de créer la nouvelle invitation permet une propriété prévisible de l’invitation. Cependant, le service externe doit effectuer les opérations suivantes.- Sélectionner l’utilisateur qui gérera les invitations.
- Sélectionner un nouvel utilisateur lorsque l’utilisateur précédent quitte le réseau.
Gestion par tous les utilisateurs
Faire en sorte que tous les utilisateurs tentent de gérer les invitations rend la propriété des invitations imprévisible, mais évite au service externe de devoir sélectionner un seul utilisateur. À la place, un utilisateur sur chaque appareil effectue les opérations suivantes.- Tenter de révoquer l’invitation actuelle. Pour l’invitation initiale, tous les utilisateurs tentent cette opération, mais un seul y parvient. Pour les autres invitations, seul l’utilisateur qui a créé la dernière invitation peut tenter de la révoquer, car l’invitation n’est pas visible pour les autres utilisateurs.
- Tenter de créer une nouvelle invitation. Comme les invitations doivent avoir des identificateurs uniques, un seul des utilisateurs y parvient. Cet utilisateur doit informer les autres qu’il est le nouveau propriétaire de l’invitation, car l’invitation n’est pas visible sur les autres appareils.
- Lorsque le créateur de l’invitation actuelle quitte l’appareil créateur, tous les utilisateurs doivent de nouveau tenter de créer une nouvelle invitation.
Lorsque vous révoquez une invitation et en créez une nouvelle avec le même identificateur, il existe un court intervalle de temps pendant lequel l’identificateur d’invitation n’est pas valide. Si vous utilisez cette approche, vous devez réessayer l’appel à
PartyNetwork::AuthenticateLocalUser() en cas d’échec, après une période d’attente raisonnable.Invitation ouverte tournante
Pour les jeux dans lesquels un lobby ou un autre service externe contrôle qui doit rejoindre un réseau donné, le modèle d’invitation ouverte tournante constitue une alternative au modèle d’invitation unique dynamique. Dans ce modèle, il existe toujours une seule invitation ouverte. L’invitation est révoquée et recréée avec un nouvel identificateur chaque fois qu’un utilisateur précédemment autorisé à rejoindre le réseau est retiré de la liste des utilisateurs du service externe. L’identificateur d’invitation fait office de mot de passe et doit être protégé de la même façon. Le modèle peut être mis en œuvre selon les étapes suivantes :- Le service externe sélectionne un appareil pour créer le réseau et spécifie l’identificateur d’invitation à utiliser.
- Le service externe envoie l’identificateur d’invitation à tous les autres utilisateurs qui doivent rejoindre le réseau.
- Lorsqu’un nouvel utilisateur doit rejoindre le réseau, le service externe partage avec lui l’identificateur d’invitation actuel.
- Lorsqu’un utilisateur disposant de l’invitation actuelle ne doit plus être autorisé à rejoindre le réseau, le service externe doit « changer le mot de passe » en procédant comme suit.
- Sélectionner un nouvel identificateur d’invitation.
- Demander à l’un des utilisateurs ou à tous les utilisateurs de révoquer l’invitation actuelle et d’en créer une nouvelle avec l’identificateur d’invitation sélectionné. Consultez Invitation unique dynamique pour une discussion sur la gestion par un seul utilisateur et la gestion par tous les utilisateurs.
- Partager le nouvel identificateur d’invitation avec tous les utilisateurs qui doivent maintenant être autorisés à rejoindre le réseau.