> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 초대 받기
> 멀티플레이어 프로토콜과 XGameActivation 초대 이벤트 콜백을 등록하여 XBOX 서비스 타이틀에 멀티플레이어 게임 초대 처리를 추가합니다.
이 항목을 사용하여 XBOX 서비스 타이틀에 게임 초대를 추가합니다. 멀티플레이어 초대를 받으려면 게임에서 멀티플레이어 프로토콜 및 게임 초대 콜백에 대해 등록해야 합니다. 게임은 로컬 사용자에 대한 초대를 받은 다음 해당 사용자를 멀티플레이어 세션에 참가시킵니다.
## 사전 요구 사항
Windows PC에서 게임 초대 알림을 받으려면 XBOX Game Bar를 설치하세요. XBOX Game Bar 앱은 Windows 10, OS 버전 1903 이상에 기본적으로 설치되어 있습니다. **Windows 키**+**G**를 눌러 XBOX Game Bar 앱을 실행하여 올바르게 설치되었는지 확인합니다.
Windows PC에 XBOX Game Bar가 설치되어 있지 않은 경우, [Microsoft Store](https://www.microsoft.com/store/productId/9NZKPSTSNW4P)에서 설치할 수 있습니다.
## 멀티플레이어 프로토콜 등록
멀티플레이어 프로토콜을 등록하면 사용자가 멀티플레이어 게임 초대를 수락할 때 시스템이 게임을 시작하는 방법을 알 수 있습니다. 멀티플레이어 프로토콜을 등록하려면 다음 코드와 같이 [MicrosoftGame.config](/build/core-features/common/game-config/MicrosoftGameConfig-toc) 파일에 `MultiplayerProtocol` 요소를 추가해야 합니다.
```xml theme={null}
true
```
패키지에 여러 실행 파일이 있는 경우, 다음 코드와 같이 `Executable` 특성을 사용하여 어떤 실행 파일이 멀티플레이어 프로토콜을 처리할지 지정할 수 있습니다.
```xml theme={null}
true
```
## 멀티플레이어 게임 초대 콜백 등록
`XGameInviteRegisterForEvent` 및 `XGameInviteUnregisterForEvent` API는 이제 더 이상 사용되지 않습니다. 대신 [XGameActivationRegisterForEvent](/reference/system/xgameactivation/functions/xgameactivationregisterforevent) 및 [XGameActivationUnregisterForEvent](/reference/system/xgameactivation/functions/xgameactivationunregisterforevent)를 사용하세요. 마이그레이션 지침은 [XGameActivation](/reference/system/xgameactivation/xgameactivation_members#remarks)을 참조하세요.
멀티플레이어 게임 초대 콜백을 받으려면 다음 코드와 같이 [XGameActivationRegisterForEvent](/reference/system/xgameactivation/functions/xgameactivationregisterforevent) API를 사용하여 활성화 콜백에 등록해야 합니다.
활성화 콜백 등록 및 등록 취소에 대한 자세한 내용은 [XGameActivationRegisterForEvent](/reference/system/xgameactivation/functions/xgameactivationregisterforevent) 및 [XGameActivationUnregisterForEvent](/reference/system/xgameactivation/functions/xgameactivationunregisterforevent)를 참조하세요.
### Flat C
```cpp theme={null}
#include
#include
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);
}
```
"일시 중단 상태에서 수락된 초대" 시나리오를 적절히 처리하려면, 타이틀은 위 샘플 코드의 [XGameActivationRegisterForEvent](/reference/system/xgameactivation/functions/xgameactivationregisterforevent) 콜백에서 `OnActivation()` 핸들러 메서드로 전달된 `inviteUri`를 저장해야 합니다. 그런 다음 타이틀은 게임이 완전히 재개되었음을 알리는 `RegisterAppStateChangeNotification`을 기다려야 하며, 그 후에 `inviteUri`에 제공된 세부 정보를 사용하여 세션에서 작업을 계속 진행해야 합니다.
`RegisterAppStateChangeNotification`에 대한 자세한 내용은 [XBOX Game Life Cycle (NDA topic)](/build/console-features/console-workflows/xbox-game-life-cycle)을 참조하세요.
## XGameActivationCallback에서 inviteUri 구문 분석
게임이 `AcceptedGameInvite`의 활성화 유형으로 [XGameActivationCallback](/reference/system/xgameactivation/functions/xgameactivationcallback) 이벤트를 받으면, [XGameActivationInfo](/reference/system/xgameactivation/structs/xgameactivationinfo) 구조체에서 `inviteUri` 문자열에 액세스할 수 있습니다. `inviteUri`는 다음 형식 중 하나입니다.
### 게임 초대 수락의 경우
사용자가 게임 초대를 수락하면 다음 코드와 같이 `inviteUri`가 포함된 게임 초대 콜백을 받습니다.
```cpp theme={null}
"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="
```
URI는 항상 "ms-xbl-multiplayer//"로 시작하며, 그 뒤에 다음 핸들이 있습니다.
* `inviteHandleAccept`는 사용자가 게임 초대를 수락했기 때문에 콜백이 시작되었음을 나타냅니다.
* `handle`은 멀티플레이어 세션에 참가하는 데 사용하는 초대 핸들입니다.
* `invitedXuid`는 멀티플레이어 세션에 초대받은 XBOX 서비스 사용자의 ID입니다.
* `senderXuid`는 게임 초대를 보낸 XBOX 서비스 사용자의 ID입니다.
* `context`는 발신자가 포함했을 수 있는 추가(선택 사항) 컨텍스트입니다.
### 진행 중인 게임 세션에 참가하는 경우
사용자가 멀티플레이어 세션에 참가하려고 시도할 때, 게임은 다음 코드와 같은 `inviteUri`가 포함된 초대 콜백을 받습니다.
```cpp theme={null}
"ms-xbl-multiplayer://activityHandleJoin?&handle=%s&joinerXuid=%s&joineeXuid=%s"
```
URI는 항상 "ms-xbl-multiplayer//"로 시작하며, 그 뒤에 다음 핸들이 있습니다.
* `activityHandleJoin`은 사용자가 게임 초대를 수락했기 때문에 콜백이 시작되었음을 나타냅니다.
* `handle`은 멀티플레이어 세션에 참가하는 데 사용하는 활동 핸들입니다.
* `joinerXuid`는 멀티플레이어 세션에 참가하려고 시도하는 XBOX 서비스 사용자의 ID입니다.
* `joineeXuid`는 현재 멀티플레이어 세션에 있는 XBOX 서비스 사용자의 ID입니다.
## handleId로 멀티플레이어 게임 세션에 참가
### Multiplayer Manager 사용
Multiplayer Manager를 사용하는 경우, [XblMultiplayerManagerJoinLobby](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoinlobby) API를 사용하고 `inviteUri`에서 추출한 `handleId`를 전달하여 사용자를 멀티플레이어 세션에 참가시킬 수 있습니다. 다음 코드와 같이 `invitedXuid`에 대해 `xblUserHandle`을 사용할 수도 있습니다.
#### Flat C
```cpp theme={null}
HRESULT hr = XblMultiplayerManagerJoinLobby(handleId, xblUserHandle);
```
### Multiplayer API 직접 사용
Multiplayer API를 사용하는 경우, 다음 단계에 따라 타이틀에 대한 멀티플레이어 세션 및 초대를 구성합니다.
1. [XblMultiplayerGetSessionByHandleAsync](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayergetsessionbyhandleasync) API를 사용하고 `handleId`를 전달하여 멀티플레이어 세션 문서를 가져옵니다.
2. [XblMultiplayerSessionJoin](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionjoin) API를 사용하여 로컬 사용자를 멀티플레이어 세션 문서에 참가시킵니다.
3. [XblMultiplayerWriteSessionByHandleAsync](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionbyhandleasync) API를 사용하여 이 변경 사항을 커밋하기 위해 멀티플레이어 세션 문서를 서비스에 씁니다.
## 참조 API 문서
* [Xgameactivation (API contents)](/reference/system/xgameactivation/xgameactivation_members)
* Functions
* [XGameActivationRegisterForEvent](/reference/system/xgameactivation/functions/xgameactivationregisterforevent)
* [XGameActivationUnregisterForEvent](/reference/system/xgameactivation/functions/xgameactivationunregisterforevent)
* [XGameActivationCallback](/reference/system/xgameactivation/functions/xgameactivationcallback)
* Structures
* [XGameActivationInfo](/reference/system/xgameactivation/structs/xgameactivationinfo)
* [multiplayer\_manager\_c (API contents)](/reference/live/xsapi-c/multiplayer_manager_c/multiplayer_manager_c_members)
* Functions
* [XblMultiplayerManagerJoinLobby](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoinlobby)
* [XblMultiplayerGetSessionByHandleAsync](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayergetsessionbyhandleasync)
* [XblMultiplayerSessionJoin](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionjoin)
* [XblMultiplayerWriteSessionByHandleAsync](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionbyhandleasync)
## 참고 항목
[XGameActivation API](/reference/system/xgameactivation/xgameactivation_members) [Multiplayer Manager를 사용하여 게임을 시작하기 위한 프로토콜 활성화 처리](/services/xbox-services/multiplayer/mpm/how-to/live-handle-protocol-activation)
## Related topics
- [Multiplayer Activity에 대한 예제 코드](/ko/services/xbox-services/multiplayer/mpa/how-to/live-mpa-client-how-to.md)
- [초대 예제 코드](/ko/services/xbox-services/multiplayer/invites/how-to/live-invites-howto-nav.md)
- [XGameActivation](/ko/reference/system/xgameactivation/xgameactivation_members.md)
- [XblMultiplayerGetSessionByHandleAsync](/ko/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayergetsessionbyhandleasync.md)
- [XGameActivationInfo](/ko/reference/system/xgameactivation/structs/xgameactivationinfo.md)