GS2-Version

Version check function

Provides the ability to determine the version of the application, the version of any additional assets, and the version that agrees to the terms of service.

If the version check passes, a new temporary GS2 client ID/secret can be issued.

Using this feature, the GS2 client ID/secret embedded in the application only has the authority to call the API that performs the login and version check, and only after passing the version check can it obtain a client ID/secret with sufficient authority to actually play the game.

Version model

Multiple items can be set for version checks, and only if all version checks are passed will the check pass.

There are two types of version models: “version check based on the version sent by the application” and “version check based on the version of the agreement that the logged-in user has agreed to in the past”. The former is called “passive version checking” and the latter is called “active version checking”.

Version number format.

{major}.{minor}.{micro}
format version numbers are available, and an integer value can be specified for each element.

Example of version number setting and judgment

targetVersion is set to the version number of the application, etc., and the warningVersion and errorVersion on the master data side are compared.

targetVersionerrorVersionjudgment
1.0.11.0.0Passed
1.0.01.0.0Error
0.9.01.0.0Error

If targetVersion is greater than errorVersion, passage is allowed.

targetVersionwarningVersionjudgment
1.0.11.0.0Passed
1.0.01.0.0Warning
0.9.01.0.0Warning

If targetVersion is greater than warningVersion, it can be passed as is. If targetVersion is equal to or less than warningVersion, it can be treated as a version that prompts version-up but allows passage.

Passive version check

Used to check the version of the game’s executable binaries and each asset downloaded by the game.

In the master data, you can set a “Version Threshold for Warnings” and “Version Threshold for Errors” for each version model. The warning threshold is used in situations where a newer version can be downloaded from the application distribution site provided by the platformer, but the game can be launched as is. Error literally means that the version check fails with an error and the game cannot be started.

Version Signature

The version number sent by the game is not reliable information. Therefore, the version number can be signed. The signature must be precomputed for each version number using the GS2 API.

By sending the signature along with the version number and setting the version model properties to require a signature, an error can be generated for unsigned requests or requests where the version number and signature do not match.

Active Version Check

This function keeps track of the version of the Terms of Service and other terms to which the player has consented, and is used to determine whether the player has consented to the current Terms of Service.

The master data defines the version number of the currently delivered TOS, and when the player calls the Consent API, the value is recorded in the database. The version check process then retrieves the previously recorded version information from the database and compares it to the threshold defined in the master data.

Example of setting version number for active version check

Set the version number, etc. of the convention to currentVersion of the master data and compare it with errorVersion.

approval version number recorded in GS2VersionerrorVersionjudgment
no approved version number1.0.0Error
Approved for 0.9.01.0.0Error
Approved for 1.0.01.0.0Error
Approved with 1.0.11.0.0Passed

If currentVersion is set to a higher version number than errorVersion and the API is called and approved, the decision is that passage is possible.

Example Implementation

Execute version check

    var result = await gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Checker(
    ).CheckVersionAsync(
        targetVersions: new [] {
            new Gs2.Unity.Gs2Version.Model.EzTargetVersion
            {
                VersionName = "app",
                Version =
                {
                    Major = 1,
                    Minor = 2,
                    Micro = 3,
                },
            },
            new Gs2.Unity.Gs2Version.Model.EzTargetVersion
            {
                VersionName = "asset",
                Version =
                {
                    Major = 1,
                    Minor = 2,
                    Micro = 3,
                },
            },
        }
    );
    var projectToken = result.ProjectToken;
    var warnings = result.Warnings;
    var errors = result.Errors;
    const auto Future = Gs2->Version->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Checker(
    )->CheckVersion(
        []
        {
            const auto v = MakeShared<TArray<TSharedPtr<Gs2::Version::Model::FTargetVersion>>>();
            v->Add({'versionName': 'app', 'version': {'major': 1, 'minor': 2, 'micro': 3}});
            v->Add({'versionName': 'asset', 'version': {'major': 1, 'minor': 2, 'micro': 3}});
            return v;
        }() // targetVersions
    );
    Future->StartSynchronousTask();
    if (!TestFalse(WHAT, Future->GetTask().IsError())) return false;
    const auto ProjectToken = Result->ProjectToken;
    const auto Warnings = Result->Warnings;
    const auto Errors = Result->Errors;

Agree to active version check

    var result = await gs2.Version.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).AcceptVersion(
        versionName: "eula"
    ).AcceptAsync(
    );
    const auto Future = Gs2->Version->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->AcceptVersion(
        "eula" // versionName
    )->Accept(
    );
    Future->StartSynchronousTask();
    if (!TestFalse(WHAT, Future->GetTask().IsError())) return false;

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (!TestFalse(WHAT, Future2->GetTask().IsError())) return false;
    const auto Result = Future2->GetTask().Result();

More practical information

Version Update Operating Procedures

When upgrading a version, you may want to kick out all players who are playing and allow them to play only with the latest version. GS2-Version can stop new logins, but for players already logged in, it is possible to continue access until the expiration of the Client ID/Client Secret temporarily issued after the version check.

So, disconnect the always-on session for notification provided by the GS2 gateway for all players, and let the game handle the session disconnection and reconnection process after the version check. If the version check fails, the game will go directly into the version update sequence.

This will update the version and force all playing players to version check as well.

Detailed Reference.