> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-Gateway SDK for Game Engine API 레퍼런스

게임 엔진용 GS2-Gateway SDK의 모델 사양과 API 레퍼런스



## 모델

### EzWebSocketSession

WebSocketSession<br>

WebSocket 세션은 GS2 서버와 클라이언트 간의 지속적인 연결로, 실시간 양방향 통신을 수행합니다.<br>
서버에 대해 클라이언트 측에서 식별자로 사용자 ID를 등록합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| connectionId | string |  | ✓ |  |  ~ 128자 | 커넥션 ID<br>이 WebSocket 접속에 할당된 고유 식별자입니다. 알림 송신 시 특정 클라이언트 접속을 식별하는 데 사용됩니다. |
| namespaceName | string |  | ✓ |  |  ~ 128자 | 네임스페이스 이름 |
| userId | string |  | ✓ |  |  ~ 128자 | 사용자ID |

**관련 메서드:**
setUserId - 서버로부터의 푸시 알림을 수신하기 위해 플레이어의 접속을 등록한다


---

## 메서드

### setUserId

서버로부터의 푸시 알림을 수신하기 위해 플레이어의 접속을 등록한다<br>

현재 WebSocket 접속을 플레이어의 사용자 ID에 연결하여, 서버가 이 클라이언트에 실시간 푸시 알림을 전송할 수 있도록 합니다.<br>
일반적으로 플레이어가 로그인하여 서버에 접속한 직후에 호출합니다. 이 단계를 거치지 않으면 서버는 어느 접속이 어느 플레이어의 것인지 판별할 수 없습니다.<br>
allowConcurrentAccess 플래그로 동일한 플레이어가 여러 디바이스에서 동시에 접속할 수 있는지를 제어합니다:<br>
- true: 여러 동시 접속을 허용(스마트폰과 태블릿 양쪽에서 플레이하는 경우 등)<br>
- false: 플레이어당 1개의 접속만 허용(중복 로그인 방지. 기존 접속은 연결 해제됩니다)<br>
게임의 로그인·초기화 흐름의 일부로 사용합니다. 실시간 채팅 알림, 친구 요청 알림, 매치메이킹 성사 알림 등의 기능을 활성화하는 데 필요합니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름 |
| gameSession | GameSession | | ✓|  |  | GameSession |
| allowConcurrentAccess | bool |  | | true |  | 동시에 다른 클라이언트로부터의 접속을 허용할지 여부 |
| sessionId | string | {allowConcurrentAccess} == false | |  |  ~ 128자 | allowConcurrentAccess를 false로 설정한 경우에도, 기존 접속과 동일한 sessionId라면 접속을 허용하기 위해 지정합니다. |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzWebSocketSession](#ezwebsocketsession) | 갱신한 WebSocket 세션|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Gateway.Namespace(
        namespaceName: "$hash"
    ).Me(
        gameSession: GameSession
    ).WebSocketSession(
    );
    var result = await domain.SetUserIdAsync(
        allowConcurrentAccess: true,
        sessionId: null
    );
    var item = await result.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Gateway.Namespace(
        namespaceName: "$hash"
    ).Me(
        gameSession: GameSession
    ).WebSocketSession(
    );
    var future = domain.SetUserIdFuture(
        allowConcurrentAccess: true,
        sessionId: null
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Gateway->Namespace(
        "$hash" // namespaceName
    )->Me(
        GameSession
    )->WebSocketSession(
    );
    const auto Future = Domain->SetUserId(
        true // allowConcurrentAccess
        // sessionId
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // 변경된 값 / 결과 값을 취득
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

```

**Godot**
```gdscript

var domain = ez.gateway.namespace_(
        "$hash"
    ).me(game_session).web_socket_session(
    )

var async_result = await domain.set_user_id(
    true, # allow_concurrent_access
    null # session_id
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

```


---