API Reference of GS2-Version SDK for Game Engine

Model

EzVersion

Version

	Type	Require	Limitation	Description
major	int	✓	~ 2147483646	Major version
minor	int	✓	~ 2147483646	Minor version
micro	int	✓	~ 2147483646	Micro version

EzVersionModel

Version Model

You can set a warning version that accepts login but notifies you that you can upgrade, and an error version that does not accept login.

You can specify whether or not to have the client declare the current version with or without a signature. If you select signed, the client will not be able to declare a false version.

	Type	Require	Limitation	Description
name	string	✓	~ 128 chars	Version Model Name
metadata	string		~ 2048 chars	metadata
warningVersion	EzVersion	{type} == “simple”		Version that prompts for version upgrade
errorVersion	EzVersion	{type} == “simple”		Version that is determined to be an error by the version check
scope	enum { “passive”, “active” }	✓	~ 128 chars	Type of version value used for judgment
currentVersion	EzVersion	{type} == “simple” and {scope} == “active”		Current Version
needSignature	bool	{scope} == “passive”		Whether the version value to be determined requires signature verification

Enumeration type definition to specify as scope

Enumerator String Definition	Description
passive	Sent by Client
active	Version explicitly approved in the past

EzAcceptVersion

Approved Version

Not a version tied to data, such as an app version or asset version. Used for entities that require version control on a per-user basis, such as a version of an agreed upon Terms of Use.

	Type	Require	Limitation	Description
versionName	string	✓	~ 128 chars	Approved Version Name
userId	string	✓	~ 128 chars	User Id
version	EzVersion	✓		Approved Version

EzStatus

Version Status

Indicates the result of version verification.

	Type	Require	Default	Limitation	Description
versionModel	EzVersionModel	✓			Version Model
currentVersion	EzVersion				Current Version

EzTargetVersion

Version to be verified

	Type	Require	Limitation	Description
versionName	string	✓	~ 128 chars	Version Model Name
version	EzVersion	{signature} == ""		Version
body	string		~ 1048576 chars	Body
signature	string		~ 256 chars	Signature

Methods

getVersionModel

Get version settings

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name
versionName	string	✓		~ 128 chars	Version Model Name

Result

	Type	Description
item	EzVersionModel	Version Setting

Implementation Example

    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.Model();
    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;
    }

Value change event handling

    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    ).VersionModel(
        versionName: "version-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);

    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    ).VersionModel(
        versionName: "version-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Version->Namespace(
        "namespace-0001" // namespaceName
    )->VersionModel(
        "version-0001" // versionName
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Version::Model::FVersionModel> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

Warning

This event is called when the value in the local cache that the SDK has is changed.

The local cache will only be changed by executing the SDK’s API, or by executing a stamp sheet via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.

listVersionModels

Get list of version settings

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name

Result

	Type	Description
items	List<EzVersionModel>	List of Version Settings

Implementation Example

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

Value change event handling

    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // Start event handling
    var callbackId = domain.SubscribeVersionModels(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeVersionModels(callbackId);

    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
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeVersionModels(
        []() {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    Domain->UnsubscribeVersionModels(CallbackId);

Warning

This event is called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.

accept

Approve Version

Used for terms of use, etc.

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 128 chars	Namespace name
accessToken	string	✓	~ 128 chars	User Id
versionName	string	✓	~ 128 chars	Approved Version Name
version	EzVersion			Approved Version

Result

	Type	Description
item	EzAcceptVersion	Approved Version

Error

Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.

Type	Base Type	Description
AcceptVersionInvalidException	BadRequestException	Error as a result of an updated server version during the approval process

Implementation Example

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.AcceptVersionInvalid 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.Model();
    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;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

delete

Delete the approved version

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 128 chars	Namespace name
accessToken	string	✓	~ 128 chars	User Id
versionName	string	✓	~ 128 chars	Approved Version Name

Result

	Type	Description
item	EzAcceptVersion	Deleted approved version

Implementation Example

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

list

Get list of approved versions

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name
accessToken	string	✓		~ 128 chars	User Id
pageToken	string			~ 1024 chars	Token specifying the position from which to start acquiring data
limit	int	✓	30	1 ~ 1000	Number of data acquired

Result

	Type	Description
items	List<EzAcceptVersion>	List of Approved Versions
nextPageToken	string	Page token to retrieve the rest of the listing

Implementation Example

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

Value change event handling

    var domain = gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // Start event handling
    var callbackId = domain.SubscribeAcceptVersions(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeAcceptVersions(callbackId);

    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
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeAcceptVersions(
        []() {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    Domain->UnsubscribeAcceptVersions(CallbackId);

Warning

This event is called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.

checkVersion

Perform version check

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name
accessToken	string	✓		~ 128 chars	User Id
targetVersions	List<EzTargetVersion>		[]	~ 1000 items	List of Versions to be verified

Result

	Type	Description
projectToken	string	Signed in to the project token.
warnings	List<EzStatus>	Version Verification Results List of Warnings
errors	List<EzStatus>	Version Verification Results List of errors

Implementation Example

    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;