Réception d'invitations

Utilisez cette rubrique pour ajouter des invitations de jeu à votre titre des services XBOX. Pour recevoir des invitations multijoueurs, votre jeu s’inscrit au protocole multijoueur et aux rappels d’invitation de jeu. Votre jeu reçoit les invitations destinées à l’utilisateur local, puis intègre cet utilisateur à la session multijoueur.

Prérequis

Pour recevoir des notifications d’invitation de jeu sur un PC Windows, installez la XBOX Game Bar. L’application XBOX Game Bar est installée par défaut sur Windows 10, version 1903 ou ultérieure du système d’exploitation. Appuyez sur Touche Windows+G pour lancer l’application XBOX Game Bar et vérifier qu’elle est correctement installée.

Si la XBOX Game Bar n’est pas installée sur votre PC Windows, vous pouvez l’installer depuis le Microsoft Store.

Inscription au protocole multijoueur

L’inscription au protocole multijoueur indique au système comment lancer votre jeu lorsque l’utilisateur accepte une invitation de jeu multijoueur. Pour inscrire le protocole multijoueur, vous devez ajouter un élément MultiplayerProtocol à votre fichier MicrosoftGame.config, comme indiqué dans le code suivant.

    <MultiplayerProtocol>true</MultiplayerProtocol>

Si votre package contient plusieurs exécutables, vous pouvez spécifier l’exécutable qui gère le protocole multijoueur à l’aide de l’attribut Executable, comme indiqué dans le code suivant.

    <MultiplayerProtocol Executable="MyExecutableForMultiplayer.exe">true</MultiplayerProtocol>

Inscription aux rappels d’invitation de jeu multijoueur

Les API XGameInviteRegisterForEvent et XGameInviteUnregisterForEvent sont désormais dépréciées. Utilisez plutôt XGameActivationRegisterForEvent et XGameActivationUnregisterForEvent. Pour obtenir des conseils de migration, consultez XGameActivation.

Pour recevoir les rappels d’invitation de jeu multijoueur, vous devez vous inscrire aux rappels d’activation à l’aide de l’API XGameActivationRegisterForEvent, comme indiqué dans le code suivant. Pour plus d’informations sur l’inscription et la désinscription des rappels d’activation, consultez XGameActivationRegisterForEvent et XGameActivationUnregisterForEvent.

C plat

#include <XTaskQueue.h>
#include <XGameActivation.h>  
  
XTaskQueueHandle g_taskQueue;  
XTaskQueueRegistrationToken g_activationToken;  
  
void CALLBACK OnActivation(void* context, const XGameActivationInfo* activationInfo)  
{  
    if (activationInfo->type == XGameActivationType::AcceptedGameInvite)
    {
        if (activationInfo->inviteUri != nullptr)
        {
            std::string inviteString(activationInfo->inviteUri);
            auto pos = inviteString.find("handle=");
            auto handleId = inviteString.substr(pos + 7, 36);
            // Now call XblMultiplayerManagerJoinLobby
        }
    }
}  
  
void InitializeGame()  
{  
    XGameActivationRegisterForEvent(g_taskQueue, nullptr, OnActivation, &g_activationToken);  
}  
  
void ShutdownGame()  
{  
    XGameActivationUnregisterForEvent(g_activationToken, true);  
}  

Pour gérer correctement le scénario « invitation acceptée depuis un état suspendu », le titre doit stocker l’inviteUri transmis à la méthode de gestionnaire OnActivation() de l’exemple de code ci-dessus depuis le rappel XGameActivationRegisterForEvent. Le titre doit ensuite attendre la notification RegisterAppStateChangeNotification, qui signale que le jeu a entièrement repris, avant d’agir sur la session à l’aide des détails fournis dans l’inviteUri. Pour plus d’informations sur RegisterAppStateChangeNotification, consultez Cycle de vie des jeux XBOX (rubrique sous NDA).

Analyse de l’inviteUri à partir de XGameActivationCallback

Lorsque votre jeu reçoit l’événement XGameActivationCallback avec le type d’activation AcceptedGameInvite, vous pouvez accéder à la chaîne inviteUri à partir de la structure XGameActivationInfo. L’inviteUri présente l’un des formats suivants.

Pour l’acceptation d’une invitation de jeu

Lorsque l’utilisateur accepte une invitation de jeu, le jeu reçoit le rappel d’invitation de jeu avec un inviteUri, comme indiqué dans le code suivant.

    "ms-xbl-multiplayer://inviteHandleAccept?handle=%s&invitedXuid=%s&senderXuid=%s&context=%s"
    
    // for example:
    // "ms-xbl-multiplayer://inviteHandleAccept?handle=00000000-0000-1234-5678-1234567890ab&invitedXuid=1234567890123456&senderXuid=6543210987654321&context="

L’URI commence toujours par “ms-xbl-multiplayer//”, suivi des handles suivants.

inviteHandleAccept indique que le rappel a été déclenché parce que l’utilisateur a accepté une invitation de jeu.
handle est le handle d’invitation que vous utilisez pour rejoindre la session multijoueur.
invitedXuid est l’ID de l’utilisateur des services XBOX invité à la session multijoueur.
senderXuid est l’ID de l’utilisateur des services XBOX qui a envoyé l’invitation de jeu.
context est le contexte supplémentaire (facultatif) que l’expéditeur a pu inclure.

Pour rejoindre une session de jeu en cours

Lorsque l’utilisateur tente de rejoindre une session multijoueur, le jeu reçoit un rappel d’invitation avec un inviteUri, comme indiqué dans le code suivant.

    "ms-xbl-multiplayer://activityHandleJoin?&handle=%s&joinerXuid=%s&joineeXuid=%s"

L’URI commence toujours par “ms-xbl-multiplayer//”, suivi des handles suivants.

activityHandleJoin indique que le rappel a été déclenché parce que l’utilisateur a accepté une invitation de jeu.
handle est le handle d’activité que vous utilisez pour rejoindre la session multijoueur.
joinerXuid est l’ID de l’utilisateur des services XBOX qui tente de rejoindre la session multijoueur.
joineeXuid est l’ID de l’utilisateur des services XBOX qui se trouve actuellement dans la session multijoueur.

Rejoindre une session de jeu multijoueur avec handleId

Utilisation de Multiplayer Manager

Si vous utilisez Multiplayer Manager, vous pouvez intégrer l’utilisateur à la session multijoueur à l’aide de l’API XblMultiplayerManagerJoinLobby en lui transmettant le handleId extrait de l’inviteUri. Vous pouvez également utiliser le xblUserHandle correspondant à l’invitedXuid, comme indiqué dans le code suivant.

C plat

HRESULT hr = XblMultiplayerManagerJoinLobby(handleId, xblUserHandle);

Utilisation directe de l’API Multijoueur

Si vous utilisez l’API Multijoueur, procédez comme suit pour configurer les sessions multijoueurs et les invitations de votre titre.

Récupérez le document de session multijoueur à l’aide de l’API XblMultiplayerGetSessionByHandleAsync en lui transmettant le handleId.
Ajoutez l’utilisateur local au document de session multijoueur à l’aide de l’API XblMultiplayerSessionJoin.
Écrivez le document de session multijoueur dans le service pour valider cette modification à l’aide de l’API XblMultiplayerWriteSessionByHandleAsync.

Documentation de référence de l’API

Voir aussi

API XGameActivation Gestion de l’activation de protocole pour démarrer une partie à l’aide de Multiplayer Manager

XBOX Services

PlayFab

Prérequis

Inscription au protocole multijoueur

Inscription aux rappels d’invitation de jeu multijoueur

C plat

Analyse de l’inviteUri à partir de XGameActivationCallback

Pour l’acceptation d’une invitation de jeu

Pour rejoindre une session de jeu en cours

Rejoindre une session de jeu multijoueur avec handleId

Utilisation de Multiplayer Manager

C plat

Utilisation directe de l’API Multijoueur

Documentation de référence de l’API

Voir aussi

​Prérequis

​Inscription au protocole multijoueur

​Inscription aux rappels d’invitation de jeu multijoueur

​C plat

​Analyse de l’inviteUri à partir de XGameActivationCallback

​Pour l’acceptation d’une invitation de jeu

​Pour rejoindre une session de jeu en cours

​Rejoindre une session de jeu multijoueur avec handleId

​Utilisation de Multiplayer Manager

​C plat

​Utilisation directe de l’API Multijoueur

​Documentation de référence de l’API

​Voir aussi

Prérequis

Inscription au protocole multijoueur

Inscription aux rappels d’invitation de jeu multijoueur

C plat

Analyse de l’inviteUri à partir de XGameActivationCallback

Pour l’acceptation d’une invitation de jeu

Pour rejoindre une session de jeu en cours

Rejoindre une session de jeu multijoueur avec handleId

Utilisation de Multiplayer Manager

C plat

Utilisation directe de l’API Multijoueur

Documentation de référence de l’API

Voir aussi