Passer au contenu principal

Démarrage rapide de l’API REST Matchmaking

Nous vous recommandons vivement d’envisager l’utilisation des SDK Multiplayer, car ils incluent la prise en charge des messages en temps réel, ce qui réduit le besoin d’interrogation. Cela améliore l’expérience de matchmaking et réduit les délais. Démarrage rapide - SDK client
Ce guide de démarrage rapide vous guide tout au long du processus d’intégration de la fonctionnalité de matchmaking. Tous les exemples de code de ce démarrage rapide sont destinés à Unity ; toutefois, les concepts et le flux s’appliquent (en général) également aux autres plateformes. Selon la conception de votre jeu, consultez la section sur le matchmaking à utilisateur unique et à plusieurs utilisateurs. Ce tutoriel montre comment soumettre un ticket à une file d’attente spécifique afin de trouver une partie. Une file d’attente correspond généralement à un mode de jeu ou à plusieurs modes de jeu (par exemple, un mode capture du drapeau et un mode roi de la colline dans la même file d’attente). Le service de matchmaking se charge de trouver une correspondance parmi les tickets d’une file d’attente. Lorsqu’une correspondance est trouvée, votre titre doit se charger de connecter les joueurs entre eux pour jouer.

Configurer une file d’attente de matchmaking dans Game Manager

Ce démarrage rapide suppose que vous avez configuré vos files d’attente dans Game Manager. Pour plus de détails sur la configuration d’une file d’attente, consultez Configuration des files d’attente de matchmaking.

Matchmaking avec un ticket à utilisateur unique

Si votre jeu dispose d’un mode de jeu 1 contre 1 ou permet à un utilisateur d’entrer seul dans le matchmaking, envisagez le matchmaking à utilisateur unique. Le matchmaking à utilisateur unique suit le modèle illustré ci-dessous. Flux de matchmaking

Créer un ticket de matchmaking

Un utilisateur crée un ticket de matchmaking à l’aide de CreateMatchmakingTicket. Lorsque la création du ticket réussit, le service renvoie un TicketId. La création du ticket nécessite de spécifier le Creator (l’identité et les attributs de l’utilisateur), GiveUpAfterSeconds (le délai en secondes avant que le service abandonne la mise en correspondance du ticket) et le QueueName dans lequel rechercher une correspondance. Le champ Creator doit contenir les attributs utilisateur requis par la configuration de la file d’attente correspondant au QueueName. Une bonne valeur pour GiveUpAfterSeconds est de 120 secondes, afin d’éviter que les utilisateurs n’abandonnent d’eux-mêmes.

Vérifier l’état du ticket de matchmaking

Vous devez interroger le service à l’aide du TicketId pour accéder au Status du ticket dans le matchmaking. Pour ce faire, faites appeler GetMatchmakingTicket par votre titre. Vous pouvez effectuer jusqu’à 10 interrogations par minute. Par exemple, interrogez l’état du ticket toutes les 6 secondes. L’interrogation peut augmenter les délais lors de la récupération de l’état de votre ticket. C’est pourquoi nous vous recommandons vivement d’envisager la méthode du SDK Multiplayer décrite dans Démarrage rapide - SDK client. Celle-ci évite d’avoir à interroger le service grâce à la fonctionnalité de messages en temps réel. Lorsque l’état du ticket passe à Matched, votre client peut arrêter d’interroger le ticket. À partir de ce moment, le ticket inclut le MatchId.

Obtenir la correspondance

Depuis votre client, appelez GetMatch avec le MatchId fourni dans la réponse de GetMatchmakingTicket. Cette correspondance contient la liste des utilisateurs qui ont été mis en correspondance.

Annulation d’un ticket de matchmaking

Si, pour une raison quelconque, votre client souhaite annuler le processus de matchmaking avant que GiveUpAfterSeconds ne soit atteint, appelez CancelMatchmakingTicket avec le TicketId. Si aucune correspondance n’a encore été trouvée, le ticket est retiré du processus de matchmaking et son état passe à Canceled.

Matchmaking avec un ticket à plusieurs utilisateurs

Si votre jeu permet à des groupes de joueurs d’entrer ensemble dans une file d’attente de matchmaking, quelques étapes supplémentaires sont nécessaires pour entrer dans le matchmaking. Nous conseillons à votre titre de désigner un chef de groupe (le créateur), afin d’éviter des appels inutiles. Le chef crée le ticket, mais tous les membres du groupe doivent accepter de le rejoindre.

Créer un ticket de matchmaking (plusieurs utilisateurs)

Le groupe doit élire un créateur de ticket dans votre titre. Le créateur crée un ticket de matchmaking à l’aide de CreateMatchmakingTicket, qui renvoie un TicketId en cas de réussite. La création du ticket nécessite de spécifier le Creator (l’identité et les attributs de l’utilisateur), GiveUpAfterSeconds (le délai en secondes avant que le service abandonne la mise en correspondance du ticket), MembersToMatchWith (les identités des autres membres du groupe) et le QueueName dans lequel rechercher une correspondance. Le champ Creator doit contenir les attributs utilisateur requis par la configuration de la file d’attente correspondant au QueueName. Une bonne valeur pour GiveUpAfterSeconds est de 120 secondes, afin d’éviter que les utilisateurs n’abandonnent d’eux-mêmes.

Les membres du groupe rejoignent le ticket de correspondance

Une fois le ticket de correspondance créé, les autres membres du groupe doivent le rejoindre pour faire avancer le processus de matchmaking. À ce stade, le ticket est à l’état WaitingForPlayers. Il ne commence à être mis en correspondance avec d’autres tickets qu’une fois que tous les MembersToMatchWith ont rejoint le ticket. Pour que les membres le rejoignent, le Creator doit partager le TicketId avec les autres membres via votre titre. Chaque membre appelle ensuite JoinMatchmakingTicket, en fournissant ses propres attributs requis. Une fois que tous les membres ont rejoint le ticket, l’état du ticket devient WaitingForMatch.
Le reste du processus est identique à celui du matchmaking avec un ticket à utilisateur unique

Connecter vos joueurs entre eux

Une fois vos joueurs mis en correspondance, vous souhaiterez qu’ils se rejoignent, soit via un serveur, soit par des connexions pair à pair. Si vous utilisez un serveur dédié, vous pouvez vous appuyer sur l’ID de correspondance pour identifier de manière unique le groupe de joueurs dans lequel ils doivent se trouver. Si vous utilisez les serveurs multijoueurs de PlayFab, GetMatch fournit un serveur et un port auxquels vos joueurs peuvent se connecter. Pour plus d’informations, consultez Intégration avec PlayFab Multiplayer Servers. Dans cette version, la connexion pair à pair n’est actuellement pas officiellement prise en charge par le matchmaking. Si le pair à pair est nécessaire, envisagez d’utiliser PlayFab Party ou une solution de contournement provisoire. Contactez-nous pour obtenir davantage d’assistance à ce sujet.

Conclusion

Grâce à ce démarrage rapide, vous devriez maintenant disposer d’un flux de matchmaking fonctionnel dans votre jeu. Vous devez également tenir compte des points suivants :
  • La façon dont votre titre gère la formation des groupes.
  • Ce que votre titre affiche pendant que les utilisateurs attendent une correspondance.
  • La façon de gérer les échecs et les nouvelles tentatives.
Dernière modification le 8 octobre 2026