API Reference of GS2-Account SDK for Game Engine

Model

EzAccount

Game Player Account

An entity of identity information that identifies a game player. Game player accounts are anonymous accounts and consist of a user ID (UUID) and password (a random 32-character string), so game players do not need to enter their email address or other information.

The issued game player account is stored in the device’s local storage and is used for future logins.

TypeRequireDefaultLimitationDescription
userIdstringUUID~ 128 charsUser Id
passwordstring~ 128 charsPassword
createdAtlongDatetime of creation

EzTakeOver

Takeover Setting

Takeover Setting is information used when changing device models or moving/sharing accounts between platforms. It consists of a unique string of characters that identifies an individual and a password, the appropriate combination of which can be entered to obtain an Account (anonymous account).

Multiple takeover setting can be set up for one Account. To set up multiple handover information, you must specify different slots for each. The number of slots can be from 0 to 1024, which means that a maximum of 1025 different takeover setting can be set.

For example, 0 can be used to store Twitter account information, 1 to store Sign-in Apple account information, and 2 to store Google account information. The following usage is assumed. This takeover setting is only a data holder, and the authentication mechanism with social accounts needs to be prepared separately.

TypeRequireDefaultLimitationDescription
userIdstring~ 128 charsUser Id
typeint~ 1024Slot Number
userIdentifierstring~ 1024 charsUser ID for takeover
createdAtlongDatetime of creation

EzBanStatus

Account BAN information

Represents information about the BAN (access restriction) status applied to a game player account. This type includes detailed information such as the reason for the BAN, the name of the BAN, and the scheduled date and time for the BAN to be lifted. BAN status can be applied to an account for various reasons, such as cheating or violation of the terms of service, and this type helps to manage that status. The system uses this information to control the account’s access permissions and to restrict or release access as necessary.

TypeRequireDefaultLimitationDescription
namestringUUID~ 36 charsBAN status name
reasonstring~ 256 charsReason for BAN
releaseTimestamplongDate and time when the BAN will be released

Methods

authentication

Account Authentication

Authenticate game players using the user ID and password issued by the create function. When the authentication is completed, account authentication information and signature are issued. By passing the account credentials and signature to GS2-Auth::Login, you can get an access token to access GS2 services. GS2-Profile::Login is a combination of this API and GS2-Auth::Login, which is explained in How to start => Sample Programs.

The account credentials and signature have an expiration time of 1 hour.

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
userIdstring~ 128 charsUser Id
keyIdstring“grn:gs2:{region}:{ownerId}:key:default:key:default”~ 1024 charsencryption key GRN
passwordstring~ 128 charsPassword

Result

TypeDescription
itemEzAccountGame Player Account
banStatusesList<EzBanStatus>Ban status list
bodystringAccount information for signing subject
signaturestringsignature

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.

TypeBase TypeDescription
PasswordIncorrectExceptionUnauthorizedExceptionIncorrect password specified.
BannedInfinityExceptionUnauthorizedExceptionAccount has been suspended.

Implementation Example

try {
    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Account(
        userId: "user-0001"
    );
    var result = await domain.AuthenticationAsync(
        password: "password-0001",
        keyId: "grn:gs2:ap-northeast-1:owner_id:key:namespace-0001:key:key-0001"
    );
    var item = await result.ModelAsync();
    var banStatuses = result.BanStatuses;
    var body = result.Body;
    var signature = result.Signature;
} catch(Gs2.Gs2Account.Exception.PasswordIncorrect e) {
    // Incorrect password specified.
} catch(Gs2.Gs2Account.Exception.BannedInfinity e) {
    // Account has been suspended.
}
    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Account(
        userId: "user-0001"
    );
    var future = domain.AuthenticationFuture(
        password: "password-0001",
        keyId: "grn:gs2:ap-northeast-1:owner_id:key:namespace-0001:key:key-0001"
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Account.Exception.PasswordIncorrectException)
        {
            // Incorrect password specified.
        }
        if (future.Error is Gs2.Gs2Account.Exception.BannedInfinityException)
        {
            // Account has been suspended.
        }
        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;
    var banStatuses = future.Result.BanStatuses;
    var body = future.Result.Body;
    var signature = future.Result.Signature;
    const auto Domain = Gs2->Account->Namespace(
        "namespace-0001" // namespaceName
    )->Account(
        "user-0001" // userId
    );
    const auto Future = Domain->Authentication(
        "password-0001", // password
        "grn:gs2:ap-northeast-1:owner_id:key:namespace-0001:key:key-0001" // keyId
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::Account::Error::FPasswordIncorrectError::Class))
        {
            // Incorrect password specified.
        }
        if (e->IsChildOf(Gs2::Account::Error::FBannedInfinityError::Class))
        {
            // Account has been suspended.
        }
        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();
    const auto BanStatuses = Result->BanStatuses;
    const auto Body = Result->Body;
    const auto Signature = Result->Signature;

create

Create a new account that identifies the game player

Successful execution of this API will return information about the account created. Of the account information returned, make the user ID and password persistent for use in the authentication process.

The password issued here is a random value and cannot be an arbitrary value for the game player. You can register an identifier that is easy for the game player to understand as a takeover setting.

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name

Result

TypeDescription
itemEzAccountGame player account created

Implementation Example

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    );
    var result = await domain.CreateAsync(
    );
    var item = await result.ModelAsync();
    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    );
    var future = domain.CreateFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        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->Account->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto Future = Domain->Create(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        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();

addTakeOverSetting

Add Takeover Settings

The Takeover Settings allow you to takeover your account when you change your phone model, etc. The Takeover Settings can be executed with the combination of a Takeover User ID and a Takeover Password.

Multiple Takeover Settings can be held for a single account by specifying different values for the Slot Number. For example, you could store the email address/password in Slot number:0 and the social media ID information in Slot number:1, and then use the Slot number:2 to store the social media ID information. Game players can choose their preferred means of takeover. The game player can choose his or her preferred takeover method.

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
accessTokenstring~ 128 charsUser Id
typeint~ 1024Slot Number
userIdentifierstring~ 1024 charsUser ID for takeover
passwordstring~ 128 charsPassword

Result

TypeDescription
itemEzTakeOverTakeover settings created

Implementation Example

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).TakeOver(
        type: 0,
        userIdentifier: "user-0001@gs2.io"
    );
    var result = await domain.AddTakeOverSettingAsync(
        password: "password-0001"
    );
    var item = await result.ModelAsync();
    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).TakeOver(
        type: 0,
        userIdentifier: "user-0001@gs2.io"
    );
    var future = domain.AddTakeOverSettingFuture(
        password: "password-0001"
    );
    yield return future;
    if (future.Error != null)
    {
        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->Account->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->TakeOver(
        0, // type
        "user-0001@gs2.io" // userIdentifier
    );
    const auto Future = Domain->AddTakeOverSetting(
        "password-0001" // password
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        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();

deleteTakeOverSetting

Delete `Takeover Settings

Deletes the takeover settings that have been set.

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
accessTokenstring~ 128 charsUser Id
typeint~ 1024Slot Number

Result

TypeDescription
itemEzTakeOverDeleted takeover settings

Implementation Example

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).TakeOver(
        type: 0,
        userIdentifier: "user-0001@gs2.io"
    );
    var result = await domain.DeleteTakeOverSettingAsync(
    );
    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).TakeOver(
        type: 0,
        userIdentifier: "user-0001@gs2.io"
    );
    var future = domain.DeleteTakeOverSettingFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    const auto Domain = Gs2->Account->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->TakeOver(
        0, // type
        "user-0001@gs2.io" // userIdentifier
    );
    const auto Future = Domain->DeleteTakeOverSetting(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

doTakeOver

Execute takeover

If the specified user ID for takeover and password for takeover match, the set account information is responded. Please make the user ID and password from the responded account information permanent and use them.

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
typeint~ 1024Slot Number
userIdentifierstring~ 1024 charsUser ID for takeover
passwordstring~ 128 charsPassword

Result

TypeDescription
itemEzAccountGame Player Account

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.

TypeBase TypeDescription
PasswordIncorrectExceptionUnauthorizedExceptionIncorrect password specified.

Implementation Example

try {
    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    );
    var result = await domain.DoTakeOverAsync(
        type: 0,
        userIdentifier: "user-0001@gs2.io",
        password: "password-0001"
    );
    var item = await result.ModelAsync();
} catch(Gs2.Gs2Account.Exception.PasswordIncorrect e) {
    // Incorrect password specified.
}
    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    );
    var future = domain.DoTakeOverFuture(
        type: 0,
        userIdentifier: "user-0001@gs2.io",
        password: "password-0001"
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Account.Exception.PasswordIncorrectException)
        {
            // Incorrect password specified.
        }
        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->Account->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto Future = Domain->DoTakeOver(
        0, // type
        "user-0001@gs2.io", // userIdentifier
        "password-0001" // password
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::Account::Error::FPasswordIncorrectError::Class))
        {
            // Incorrect password specified.
        }
        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();

get

Get takeover settings by specifying user ID

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
accessTokenstring~ 128 charsUser Id
typeint~ 1024Slot Number

Result

TypeDescription
itemEzTakeOvertakeover settings

Implementation Example

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).TakeOver(
        type: 0,
        userIdentifier: "user-0001@gs2.io"
    );
    var item = await domain.ModelAsync();
    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).TakeOver(
        type: 0,
        userIdentifier: "user-0001@gs2.io"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Account->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->TakeOver(
        0, // type
        "user-0001@gs2.io" // userIdentifier
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
Value change event handling
    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).TakeOver(
        type: 0,
        userIdentifier: "user-0001@gs2.io"
    );
    
    // 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.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).TakeOver(
        type: 0,
        userIdentifier: "user-0001@gs2.io"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Account->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->TakeOver(
        0, // type
        "user-0001@gs2.io" // userIdentifier
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Account::Model::FTakeOver> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

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

listTakeOverSettings

Get list of Takeover Settings that have been set

You can retrieve list of takeover settings set by the game player. You cannot get the value of the takeover password that has been set.

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
accessTokenstring~ 128 charsUser Id
pageTokenstring~ 1024 charsToken specifying the position from which to start acquiring data
limitint301 ~ 1000Number of data acquired

Result

TypeDescription
itemsList<EzTakeOver>List of Takeover Setting
nextPageTokenstringPage token to retrieve the rest of the listing

Implementation Example

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.TakeOversAsync(
    ).ToListAsync();
    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.TakeOvers(
    );
    List<EzTakeOver> items = new List<EzTakeOver>();
    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->Account->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->TakeOvers(
    );
    TArray<Gs2::UE5::Account::Model::FEzTakeOverPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }
Value change event handling
    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // Start event handling
    var callbackId = domain.SubscribeTakeOvers(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeTakeOvers(callbackId);
    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.TakeOvers(
    );
    List<EzTakeOver> items = new List<EzTakeOver>();
    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->Account->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeTakeOvers(
        []() {
            // Called when an element of the list changes.
        }
    );

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

updateTakeOverSetting

Change the password for the `takeover setting

In order to update the password for takeover via this API, you must already know the password for takeover that has been set. Use this API when you want to achieve secure update of the takeover settings.

When using this API, remember to revoke access to the delete takeover settings API. No password authorization is required for game players to delete their takeover settings. By deleting and recreating it, you are effectively changing the takeover password.

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
accessTokenstring~ 128 charsUser Id
typeint~ 1024Slot Number
oldPasswordstring~ 128 charsOld Password
passwordstring~ 128 charsPassword

Result

TypeDescription
itemEzTakeOverTakeover settings

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.

TypeBase TypeDescription
PasswordIncorrectExceptionUnauthorizedExceptionIncorrect password specified.

Implementation Example

try {
    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).TakeOver(
        type: 0,
        userIdentifier: "user-0001@gs2.io"
    );
    var result = await domain.UpdateTakeOverSettingAsync(
        oldPassword: "password-0001",
        password: "password-1001"
    );
    var item = await result.ModelAsync();
} catch(Gs2.Gs2Account.Exception.PasswordIncorrect e) {
    // Incorrect password specified.
}
    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).TakeOver(
        type: 0,
        userIdentifier: "user-0001@gs2.io"
    );
    var future = domain.UpdateTakeOverSettingFuture(
        oldPassword: "password-0001",
        password: "password-1001"
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Account.Exception.PasswordIncorrectException)
        {
            // Incorrect password specified.
        }
        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->Account->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->TakeOver(
        0, // type
        "user-0001@gs2.io" // userIdentifier
    );
    const auto Future = Domain->UpdateTakeOverSetting(
        "password-0001", // oldPassword
        "password-1001" // password
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::Account::Error::FPasswordIncorrectError::Class))
        {
            // Incorrect password specified.
        }
        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();