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

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

모델

EzWebSocketSession

WebSocketSession

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

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

메서드

setUserId

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

현재 WebSocket 접속을 플레이어의 사용자 ID에 연결하여, 서버가 이 클라이언트에 실시간 푸시 알림을 전송할 수 있도록 합니다.
일반적으로 플레이어가 로그인하여 서버에 접속한 직후에 호출합니다. 이 단계를 거치지 않으면 서버는 어느 접속이 어느 플레이어의 것인지 판별할 수 없습니다.
allowConcurrentAccess 플래그로 동일한 플레이어가 여러 디바이스에서 동시에 접속할 수 있는지를 제어합니다:

true: 여러 동시 접속을 허용(스마트폰과 태블릿 양쪽에서 플레이하는 경우 등)
false: 플레이어당 1개의 접속만 허용(중복 로그인 방지. 기존 접속은 연결 해제됩니다)
게임의 로그인·초기화 흐름의 일부로 사용합니다. 실시간 채팅 알림, 친구 요청 알림, 매치메이킹 성사 알림 등의 기능을 활성화하는 데 필요합니다.

Request

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

Result

	타입	설명
item	EzWebSocketSession	갱신한 WebSocket 세션

구현 예제

    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();

    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;

    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();

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