Documentation index for AI agents

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

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

모델

EzAcceptVersion

승인한 버전

앱 버전이나 에셋 버전처럼 데이터에 연결된 버전이 아니라
동의한 이용약관의 버전처럼 사용자별로 버전 관리가 필요한 엔티티에서 사용합니다.

타입활성화 조건필수기본값값 제한설명
versionNamestring
~ 128자버전 이름
이 승인 레코드가 연결되어 있는 버전 모델의 이름입니다. 사용자의 승인을 특정 버전 모델 정의에 연결합니다.
userIdstring
~ 128자사용자ID
versionEzVersion
버전
사용자가 승인 또는 거부한 버전 번호입니다. “active” 스코프의 버전 모델에서 사용되는 경우, 버전 체크 시 모델의 현재 버전과 비교됩니다.

EzVersionModel

버전 모델

버전 모델에는 로그인은 허용하지만 버전 업그레이드가 가능함을 알리는 경고 버전과, 로그인을 허용하지 않는 에러 버전을 설정할 수 있습니다.

현재 버전을 클라이언트에 신고하도록 할 때, 서명 유무를 지정할 수 있습니다.
서명 있음을 선택한 경우, 클라이언트는 허위 버전을 신고할 수 없게 됩니다.

타입활성화 조건필수기본값값 제한설명
namestring
~ 128자버전 모델 이름
버전 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
metadatastring~ 2048자메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다.
warningVersionEzVersion{type} == “simple”
✓※
버전 업그레이드를 촉구하는 버전
업그레이드 알림을 표시하는 최소 버전 임계값입니다. 클라이언트의 버전이 이 값보다 낮은 경우에도 로그인은 허용되지만 사용자에게 업그레이드가 권장됩니다. 비교는 메이저, 마이너, 마이크로 순으로 계층적으로 수행됩니다.

※ type이(가) “simple” 이면 필수
errorVersionEzVersion{type} == “simple”
✓※
버전 체크에서 에러로 판정되는 버전
로그인을 허용하는 최소 버전 임계값입니다. 클라이언트의 버전이 이 값보다 낮으면 버전 체크가 에러로 판정되어 로그인이 차단됩니다. 비교는 메이저, 마이너, 마이크로 순으로 계층적으로 수행됩니다.

※ type이(가) “simple” 이면 필수
scope문자열 열거형
enum {
  “passive”,
  “active”
}
판정에 사용할 버전 값의 종류
버전 체크에 사용할 버전 값을 얻는 방법을 결정합니다. “passive"는 체크 시점에 클라이언트가 현재 버전을 신고하는 방식이며, “active"는 사용자가 과거에 명시적으로 승인한 버전(이용약관 동의 등)을 사용하는 방식입니다.
정의설명
passive클라이언트에서 전송
active과거 명시적으로 승인한 버전
currentVersionEzVersion{type} == “simple” and {scope} == “active”
✓※
현재 버전
이 버전 모델의 최신 버전입니다. “simple” 모드의 “active” 스코프에서만 사용되며, 사용자가 버전 업데이트를 승인·확인할 때 현재 버전을 알립니다.

※ type이(가) “simple"이고 scope이(가) “active” 이면 필수
needSignaturebool{scope} == “passive”
✓※
판정할 버전 값에 서명 검증이 필요한지 여부
활성화하면 클라이언트는 버전 신고와 함께 암호 서명을 제공해야 합니다. 이를 통해 클라이언트가 버전 체크를 회피하기 위해 허위 버전을 신고하는 것을 방지합니다. 스코프가 “passive"인 경우에만 적용됩니다.

※ scope이(가) “passive” 이면 필수

EzVersion

버전

3단계 계층(메이저, 마이너, 마이크로)으로 구성된 버전 번호를 나타냅니다. 버전 비교는 메이저, 마이너, 마이크로 순으로 계층적으로 수행됩니다. 버전 체크의 경고·에러 임계값 정의에 사용됩니다.

타입활성화 조건필수기본값값 제한설명
majorint
0 ~ 2147483646메이저 버전
버전 비교에서 가장 우선순위가 높은 구성 요소입니다. 메이저 버전의 차이는 마이너 버전 및 마이크로 버전보다 우선합니다.
minorint
0 ~ 2147483646마이너 버전
버전 비교에서 두 번째로 우선순위가 높은 구성 요소입니다. 메이저 버전이 동일한 경우에만 비교됩니다.
microint
0 ~ 2147483646마이크로 버전
버전 비교에서 가장 우선순위가 낮은 구성 요소입니다. 메이저 버전과 마이너 버전이 모두 동일한 경우에만 비교됩니다.

EzStatus

버전 상태

버전 검증 결과를 나타냅니다. 체크에 사용된 버전 모델과, 클라이언트로부터 신고되었거나 사용자 승인으로부터 기록된 현재 버전을 포함합니다. 버전 체크 결과의 일부로 반환되어, 버전이 최신인지, 업그레이드 경고가 필요한지, 차단되는지를 클라이언트에 통지합니다.

타입활성화 조건필수기본값값 제한설명
versionModelEzVersionModel
버전 모델
이 버전 체크에 사용된 버전 모델 정의입니다. 체크 결과를 결정한 경고·오류 버전 임계값, 스코프, 기타 설정을 포함합니다.
currentVersionEzVersion현재 버전
버전 체크 시 평가된 버전입니다. “passive” 스코프의 경우 클라이언트가 신고한 버전이고, “active” 스코프의 경우 사용자가 과거에 승인한 버전입니다. 버전 정보를 사용할 수 없는 경우 존재하지 않을 수 있습니다.

EzTargetVersion

검증할 버전

버전 체크를 위해 클라이언트가 전송하는 버전 신고를 나타냅니다. 서명 없음 모드에서는 버전을 직접 지정합니다. 서명 있음 모드에서는 변조 방지를 위해 암호 서명과 함께 버전이 바디에 포함됩니다.

타입활성화 조건필수기본값값 제한설명
versionNamestring
~ 128자버전 모델 이름
버전 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
versionEzVersion{signature} == "”
✓※
버전
검증 대상 버전 번호입니다. 서명 검증이 필요하지 않은 경우(서명이 제공되지 않은 경우)에 사용됩니다. 서명이 제공된 경우, 버전은 서명된 바디에서 추출됩니다.

※ signature이(가) "” 이면 필수
bodystring~ 1048576자바디
버전 정보를 포함하는 서명된 페이로드입니다. 서명 검증이 활성화된 경우(needSignature가 true)에 사용됩니다. 바디에는 서명과 대조하여 검증할 수 있는 형식으로 버전 데이터가 포함됩니다.
signaturestring~ 256자서명
바디 내용을 검증하기 위한 암호 서명입니다. 제공된 경우, 서버는 버전 모델에 설정된 GS2-Key 암호화 키를 사용하여 서명을 검증한 후 신고된 버전을 받아들입니다.

메서드

getVersionModel

특정 버전 체크 정의의 상세 정보 조회

버전 이름을 지정하여 체크 규칙과 임계값을 포함한 상세 정보를 조회합니다.

응답에는 다음이 포함됩니다:

  • 스코프: “passive” 체크(앱 버전 — 클라이언트가 버전을 보고)인지 “active” 체크(이용약관 — 플레이어가 명시적으로 동의해야 함)인지
  • 경고 버전: 이 임계값을 밑돌면 소프트한 경고가 표시됩니다(예: “새 버전을 사용할 수 있습니다. 업데이트해 주세요.”)
  • 에러 버전: 이 임계값을 밑돌면 강제 차단이 적용됩니다(예: “플레이를 계속하려면 업데이트가 필요합니다.”)
  • 현재 버전: 최신 버전입니다(active 스코프의 경우, 플레이어가 동의해야 하는 버전)
  • 스케줄 설정: GS2-Schedule과 연동된 경우, 시간 경과에 따라 변화하는 버전 임계값(예: 대규모 업데이트 이후 최소 버전을 단계적으로 인상)

버전 체크의 상세 정보를 표시하거나 커스텀 버전 체크 UI 로직을 구축할 때 사용합니다.

Request

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
versionNamestring
~ 128자버전 모델 이름
버전 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.

Result

타입설명
itemEzVersionModel버전 모델

구현 예제

    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    ).VersionModel(
        versionName: "version-0001"
    );
    var item = await domain.ModelAsync();
    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    ).VersionModel(
        versionName: "version-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Version->Namespace(
        "namespace-0001" // namespaceName
    )->VersionModel(
        "version-0001" // versionName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
var domain = ez.version.namespace_(
        "namespace-0001"
    ).version_model(
        "version-0001"
    )

var async_result = await domain.model()
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result
값 변경 이벤트 핸들링
    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    ).VersionModel(
        versionName: "version-0001"
    );

    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);
    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    ).VersionModel(
        versionName: "version-0001"
    );

    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);
    const auto Domain = Gs2->Version->Namespace(
        "namespace-0001" // namespaceName
    )->VersionModel(
        "version-0001" // versionName
    );

    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Version::Model::FVersionModel> value) {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->Unsubscribe(CallbackId);
var domain = ez.version.namespace_(
        "namespace-0001"
    ).version_model(
        "version-0001"
    )

# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
    # 값이 변화했을 때 호출됨
    # value에는 변경 후의 값이 전달됩니다
    pass
)

# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)

listVersionModels

버전 체크 정의 목록 조회

네임스페이스에 정의되어 있는 모든 버전 모델을 조회합니다.
각 버전 모델은 버전 체크 규칙을 나타냅니다. 예를 들어 “앱 버전”, “이용약관”, “에셋 버전” 등입니다.

GS2-Version은 2가지 유형의 버전 체크를 지원합니다:

  1. 앱 버전 체크(passive 스코프): 게임 클라이언트가 자신의 버전(예: “1.2.3”)을 보고하고, 서버가 최소 요구 버전을 충족하는지 체크합니다.
  • 클라이언트 버전이 “경고” 임계값을 밑돌면 → 업데이트 권장(플레이는 허용)
  • 클라이언트 버전이 “오류” 임계값을 밑돌면 → 업데이트 강제(플레이 차단)
  1. 이용약관 체크(active 스코프): 플레이어가 현재 버전의 약관에 명시적으로 동의해야 합니다.
  • 플레이어가 최신 버전에 동의하지 않은 경우 → 이용약관 다이얼로그 표시
  • 플레이어가 이미 동의한 경우 → 체크 통과

어떤 버전 체크가 설정되어 있는지 확인하고, 적절한 시작 흐름(버전 체크 화면, 업데이트 안내, 약관 다이얼로그 등)을 구성할 때 사용합니다.

Request

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.

Result

타입설명
itemsList<EzVersionModel>버전 모델 목록

구현 예제

    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.VersionModelsAsync(
    ).ToListAsync();
    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.VersionModels(
    );
    List<EzVersionModel> items = new List<EzVersionModel>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }
    const auto Domain = Gs2->Version->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->VersionModels(
    );
    TArray<Gs2::UE5::Version::Model::FEzVersionModelPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }
값 변경 이벤트 핸들링
    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    );

    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeVersionModels(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeVersionModels(callbackId);
    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    );

    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeVersionModels(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeVersionModels(callbackId);
    const auto Domain = Gs2->Version->Namespace(
        "namespace-0001" // namespaceName
    );

    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->SubscribeVersionModels(
        []() {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->UnsubscribeVersionModels(CallbackId);

accept

버전을 승인한다(이용약관에 동의한다)

플레이어가 지정된 버전을 승인(동의)했음을 기록합니다.
이는 이용약관, 개인정보 처리방침, 또는 이와 유사한 법적 동의 사항에 대한 “동의합니다” 버튼에 해당합니다.

일반적인 흐름:

  1. 플레이어가 최신 버전에 동의하지 않았기 때문에 CheckVersion이 “terms_of_service"에 대해 에러를 반환합니다
  2. 게임이 전문을 포함한 이용약관 다이얼로그를 표시합니다
  3. 플레이어가 내용을 읽고 “동의합니다"를 탭합니다
  4. 게임이 표시된 버전 번호로 Accept를 호출합니다
  5. 다음 CheckVersion 호출에서 약관 체크가 통과합니다

중요: 반드시 플레이어에게 실제로 표시된 버전 번호를 전달하세요. 플레이어가 약관을 읽는 동안 서버에서 약관이 업데이트된 경우, 이전 버전을 전달하면 에러가 발생합니다 — 이를 통해 플레이어가 항상 최신 약관에 동의하도록 보장됩니다.

버전을 지정하지 않으면 최신 버전이 사용됩니다. 다만 경쟁 상태(race condition)를 방지하기 위해 버전을 명시적으로 지정하는 것을 권장합니다.

Request

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
gameSessionGameSession
GameSession
versionNamestring
~ 128자버전 이름
이 승인 레코드가 연결되어 있는 버전 모델의 이름입니다. 사용자의 승인을 특정 버전 모델 정의에 연결합니다.
versionEzVersion승인한 버전

Result

타입설명
itemEzAcceptVersion승인한 버전

Error

이 API에는 특별한 예외가 정의되어 있습니다.
GS2-SDK for Game Engine에서는 게임 내에서 핸들링이 필요할 것으로 예상되는 에러를, 일반적인 예외에서 파생된 특수화된 예외로 제공하여 다루기 쉽게 하고 있습니다.
일반적인 에러의 종류와 핸들링 방법은 여기 문서를 참고해 주세요.

타입베이스 클래스설명
AcceptVersionInvalidExceptionBadRequestException승인 처리 도중 서버 버전이 갱신되어 오류가 발생했습니다

구현 예제

try {
    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).AcceptVersion(
        versionName: "eula"
    );
    var result = await domain.AcceptAsync(
        version: new Gs2.Unity.Gs2Version.Model.EzVersion {
            Major = 2,
            Minor = 2,
            Micro = 2,
        }
    );
    var item = await result.ModelAsync();
} catch(Gs2.Gs2Version.Exception.AcceptVersionInvalidException e) {
    // Error as a result of an updated server version during the approval process
}
    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).AcceptVersion(
        versionName: "eula"
    );
    var future = domain.AcceptFuture(
        version: new Gs2.Unity.Gs2Version.Model.EzVersion {
            Major = 2,
            Minor = 2,
            Micro = 2,
        }
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Version.Exception.AcceptVersionInvalidException)
        {
            // Error as a result of an updated server version during the approval process
        }
        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->Version->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->AcceptVersion(
        "eula" // versionName
    );
    const auto Future = Domain->Accept(
        MakeShared<Gs2::UE5::Version::Model::FEzVersion>()
            ->WithMajor(2)
            ->WithMinor(2)
            ->WithMicro(2)
        ) // version
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::Version::Error::FAcceptVersionInvalidError::Class))
        {
            // Error as a result of an updated server version during the approval process
        }
        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.version.namespace_(
        "namespace-0001"
    ).me(game_session).accept_version(
        "eula"
    )

var async_result = await domain.accept(
    (Gs2VersionVersion.new()
        .with_major(2)
        .with_minor(2)
        .with_micro(2)) # version
)
if async_result.error != null:
    if async_result.error is Gs2VersionAcceptVersionInvalidException:
        # 승인 처리 도중 서버 버전이 갱신되어 오류가 발생했습니다
        pass
    push_error(str(async_result.error))
    return

var result = async_result.result

delete

버전 승인 기록을 삭제한다

지정된 버전 모델에 대한 플레이어의 승인 또는 거부 기록을 삭제합니다.
삭제 후 다음 CheckVersion 호출에서는 플레이어가 이 버전 체크에 한 번도 응답하지 않은 것으로 처리됩니다.

사용 사례:

  • 플레이어가 선택적 동의 사항에 대한 결정을 번복할 수 있도록 함(예: 데이터 수집 동의 철회)
  • 테스트 또는 디버깅 목적으로 승인 상태를 초기화
  • 버전 번호를 변경하지 않고 플레이어가 업데이트된 약관을 다시 읽도록 재승인을 강제

active 스코프 체크(이용약관)의 경우, 승인 기록을 삭제하면 플레이어는 다음 로그인 또는 버전 체크 시 다시 동의를 요청받게 됩니다.

Request

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
gameSessionGameSession
GameSession
versionNamestring
~ 128자버전 이름
이 승인 레코드가 연결되어 있는 버전 모델의 이름입니다. 사용자의 승인을 특정 버전 모델 정의에 연결합니다.

Result

타입설명
itemEzAcceptVersion삭제한 승인 버전

구현 예제

    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).AcceptVersion(
        versionName: "eula"
    );
    var result = await domain.DeleteAsync(
    );
    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).AcceptVersion(
        versionName: "eula"
    );
    var future = domain.DeleteFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    const auto Domain = Gs2->Version->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->AcceptVersion(
        "eula" // versionName
    );
    const auto Future = Domain->Delete(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();
var domain = ez.version.namespace_(
        "namespace-0001"
    ).me(game_session).accept_version(
        "eula"
    )

var async_result = await domain.delete(
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

list

플레이어가 승인 또는 거부한 버전 목록 조회

현재 플레이어의 모든 버전 승인/거부 기록을 조회합니다.
각 기록에는 플레이어가 어떤 버전 모델에 응답했는지, 어떤 버전을 승인 또는 거부했는지가 포함됩니다.

주로 이용약관 및 개인정보 처리방침 관리에 사용됩니다. 예를 들면:

  • 플레이어가 이미 동의한 약관과 그 버전을 표시
  • 플레이어가 업데이트된 약관에 다시 동의해야 하는지 확인
  • 플레이어가 동의한 내용을 확인할 수 있는 “약관 및 정책” 설정 화면 표시

앱 버전 체크(passive 스코프)에서는 승인 기록이 사용되지 않습니다. 클라이언트가 보고한 버전을 직접 비교하여 체크됩니다. 이 목록에는 active 스코프 체크(플레이어가 명시적으로 승인/거부한 경우)의 기록만 포함됩니다.

Request

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
gameSessionGameSession
GameSession
pageTokenstring~ 1024자데이터 취득을 시작할 위치를 지정하는 토큰
limitint301 ~ 1000취득할 데이터 건수

Result

타입설명
itemsList<EzAcceptVersion>승인한 버전 목록
nextPageTokenstring목록의 나머지를 취득하기 위한 페이지 토큰

구현 예제

    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.AcceptVersionsAsync(
    ).ToListAsync();
    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.AcceptVersions(
    );
    List<EzAcceptVersion> items = new List<EzAcceptVersion>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }
    const auto Domain = Gs2->Version->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->AcceptVersions(
    );
    TArray<Gs2::UE5::Version::Model::FEzAcceptVersionPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }
값 변경 이벤트 핸들링
    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );

    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeAcceptVersions(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeAcceptVersions(callbackId);
    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );

    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeAcceptVersions(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeAcceptVersions(callbackId);
    const auto Domain = Gs2->Version->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );

    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->SubscribeAcceptVersions(
        []() {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->UnsubscribeAcceptVersions(CallbackId);

reject

버전을 거부한다(선택적 약관을 거절한다)

플레이어가 지정된 버전을 거부(거절)했음을 기록합니다.
이는 “거절합니다” 또는 “괜찮습니다” 버튼에 해당하지만, 동의가 필수가 아닌 선택적 약관에 대해서만 사용할 수 있습니다.

이 기능은 버전 모델의 승인 요건이 “optional"로 설정된 경우에만 사용할 수 있습니다. 승인이 필수(mandatory)인 경우, 플레이어는 반드시 동의해야 하며 거부 옵션은 존재하지 않습니다.

선택적 약관의 사용 사례:

  • 선택적 데이터 수집 동의: “게임 개선을 위해 이용 데이터를 수집해도 될까요?” → 동의함 / 거절함
  • 선택적 마케팅 알림: “프로모션 이메일 수신을 원하십니까?” → 동의함 / 거절함
  • 선택적 베타 기능: “실험적인 기능을 사용해 보시겠습니까?” → 동의함 / 거절함

플레이어가 거부하더라도 거부한 사실이 기록되므로, 프롬프트를 확인하고 응답했다는 것을 알 수 있습니다. 다음 CheckVersion에서는 (선택 사항이므로) 버전 체크가 통과하며, 게임은 거부 기록을 확인하여 그에 맞게 동작을 조정할 수 있습니다.

Request

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
gameSessionGameSession
GameSession
versionNamestring
~ 128자버전 이름
이 승인 레코드가 연결되어 있는 버전 모델의 이름입니다. 사용자의 승인을 특정 버전 모델 정의에 연결합니다.
versionEzVersion거부한 버전

Result

타입설명
itemEzAcceptVersion거부한 버전

Error

이 API에는 특별한 예외가 정의되어 있습니다.
GS2-SDK for Game Engine에서는 게임 내에서 핸들링이 필요할 것으로 예상되는 에러를, 일반적인 예외에서 파생된 특수화된 예외로 제공하여 다루기 쉽게 하고 있습니다.
일반적인 에러의 종류와 핸들링 방법은 여기 문서를 참고해 주세요.

타입베이스 클래스설명
AcceptVersionInvalidExceptionBadRequestException승인 처리 도중 서버 버전이 갱신되어 오류가 발생했습니다

구현 예제

try {
    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).AcceptVersion(
        versionName: "version-0001"
    );
    var result = await domain.RejectAsync(
        version: null
    );
    var item = await result.ModelAsync();
} catch(Gs2.Gs2Version.Exception.AcceptVersionInvalidException e) {
    // Error as a result of an updated server version during the approval process
}
    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).AcceptVersion(
        versionName: "version-0001"
    );
    var future = domain.RejectFuture(
        version: null
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Version.Exception.AcceptVersionInvalidException)
        {
            // Error as a result of an updated server version during the approval process
        }
        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->Version->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->AcceptVersion(
        "version-0001" // versionName
    );
    const auto Future = Domain->Reject(
        // version
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::Version::Error::FAcceptVersionInvalidError::Class))
        {
            // Error as a result of an updated server version during the approval process
        }
        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.version.namespace_(
        "namespace-0001"
    ).me(game_session).accept_version(
        "version-0001"
    )

var async_result = await domain.reject(
    null # version
)
if async_result.error != null:
    if async_result.error is Gs2VersionAcceptVersionInvalidException:
        # 승인 처리 도중 서버 버전이 갱신되어 오류가 발생했습니다
        pass
    push_error(str(async_result.error))
    return

var result = async_result.result

checkVersion

모든 버전 체크를 한 번에 실행

게임 클라이언트의 버전과 플레이어의 약관 동의 상태를, 네임스페이스 내의 모든 버전 모델에 대해 체크합니다.
게임 시작 시 호출하여, 플레이어가 계속 진행할 수 있는지, 업데이트나 약관 동의가 필요한지를 판정하는 메인 API입니다.

일반적인 시작 흐름:

  1. 게임이 시작되고, 클라이언트의 현재 버전(앱 버전, 에셋 버전 등)을 전달하여 CheckVersion을 호출
  2. 서버가 각 버전 모델을 체크하고, 두 개의 목록을 반환:
  • warnings: 체크는 통과했지만 클라이언트가 권장 버전보다 낮음(“업데이트가 있습니다” 다이얼로그 표시)
  • errors: 체크 실패 — 클라이언트가 너무 오래되었거나 약관에 미동의(플레이어 차단)
  1. 오류가 있는 경우, 적절한 화면을 표시:
  • 앱 버전 오류 → “App Store / Google Play에서 업데이트해 주세요"라고 표시하고 리다이렉트
  • 이용약관 오류 → 약관 다이얼로그를 표시하고, 플레이어가 동의하면 Accept를 호출
  1. 경고만 있는 경우(오류 없음), 플레이어를 계속 진행시키되 필요에 따라 업데이트 권장을 표시
  2. 경고도 오류도 없으면, 플레이어는 평소대로 게임에 진입

targetVersions 파라미터에는 passive 스코프의 체크(앱 버전 등)용으로 클라이언트의 현재 버전 번호를 전달합니다. active 스코프의 체크(이용약관 등)는 플레이어의 동의 이력을 기반으로 자동으로 평가됩니다.

Request

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
gameSessionGameSession
GameSession
targetVersionsList<EzTargetVersion>[]0 ~ 1000 items검증할 버전 목록

Result

타입설명
projectTokenstring로그인한 프로젝트 토큰
warningsList<EzStatus>버전 검증 결과 경고 목록
errorsList<EzStatus>버전 검증 결과 오류 목록

구현 예제

    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Checker(
    );
    var result = await domain.CheckVersionAsync(
        targetVersions: new List<Gs2.Unity.Gs2Version.Model.EzTargetVersion> {
            new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
                VersionName = "app",
                Version =
                new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
                    Major = 1,
                    Minor = 2,
                    Micro = 3,
                },
            },
            new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
                VersionName = "asset",
                Version =
                new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
                    Major = 1,
                    Minor = 2,
                    Micro = 3,
                },
            },
        }
    );
    var projectToken = result.ProjectToken;
    var warnings = result.Warnings;
    var errors = result.Errors;
    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Checker(
    );
    var future = domain.CheckVersionFuture(
        targetVersions: new List<Gs2.Unity.Gs2Version.Model.EzTargetVersion> {
            new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
                VersionName = "app",
                Version =
                new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
                    Major = 1,
                    Minor = 2,
                    Micro = 3,
                },
            },
            new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
                VersionName = "asset",
                Version =
                new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
                    Major = 1,
                    Minor = 2,
                    Micro = 3,
                },
            },
        }
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var projectToken = future.Result.ProjectToken;
    var warnings = future.Result.Warnings;
    var errors = future.Result.Errors;
    const auto Domain = Gs2->Version->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Checker(
    );
    const auto Future = Domain->CheckVersion(
        []
        {
            auto v = MakeShared<TArray<TSharedPtr<Gs2::UE5::Version::Model::FEzTargetVersion>>>();
            v->Add(
                MakeShared<Gs2::UE5::Version::Model::FEzTargetVersion>()
                ->WithVersionName(TOptional<FString>("app"))
                ->WithVersion(MakeShared<Gs2::UE5::Version::Model::FEzVersion>()
                    ->WithMajor(TOptional<int32>(1))
                    ->WithMinor(TOptional<int32>(2))
                    ->WithMicro(TOptional<int32>(3))
                );
            );
            v->Add(
                MakeShared<Gs2::UE5::Version::Model::FEzTargetVersion>()
                ->WithVersionName(TOptional<FString>("asset"))
                ->WithVersion(MakeShared<Gs2::UE5::Version::Model::FEzVersion>()
                    ->WithMajor(TOptional<int32>(1))
                    ->WithMinor(TOptional<int32>(2))
                    ->WithMicro(TOptional<int32>(3))
                );
            );
            return v;
        }() // targetVersions
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();
    const auto ProjectToken = Result->ProjectToken;
    const auto Warnings = Result->Warnings;
    const auto Errors = Result->Errors;
var domain = ez.version.namespace_(
        "namespace-0001"
    ).me(game_session).checker(
    )

var async_result = await domain.check_version(
    [
        Gs2VersionEzTargetVersion.new()
            .with_version_name("app")
            .with_version(
            Gs2VersionEzVersion.new()
                .with_major(1)
                .with_minor(2)
                .with_micro(3)
            ),
        Gs2VersionEzTargetVersion.new()
            .with_version_name("asset")
            .with_version(
            Gs2VersionEzVersion.new()
                .with_major(1)
                .with_minor(2)
                .with_micro(3)
            ),
    ] # target_versions
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result