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.

	Type	Require	Default	Limitation	Description
userId	string	✓	UUID	~ 128 chars	User Id
password	string	✓		~ 128 chars	Password
createdAt	long	✓			Datetime 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.

	Type	Require	Limitation	Description
userId	string	✓	~ 128 chars	User Id
type	int	✓	~ 1024	Slot Number
userIdentifier	string	✓	~ 1024 chars	User ID for takeover
createdAt	long	✓		Datetime of creation

EzBanStatus

Account BAN information

	Type	Require	Default	Limitation	Description
name	string	✓	UUID	~ 36 chars	BAN status name
reason	string	✓		~ 256 chars	Reason for account BAN
releaseTimestamp	long	✓			Date 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

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 32 chars	Namespace name
userId	string	✓	~ 128 chars	User Id
keyId	string	✓	~ 1024 chars	encryption key GRN
password	string	✓	~ 128 chars	Password

Result

	Type	Description
item	EzAccount	Game Player Account
banStatuses	List<EzBanStatus>	Ban status list
body	string	Account information for signing subject
signature	string	signature

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
PasswordIncorrectException	UnauthorizedException	Incorrect password specified.
BannedInfinityException	UnauthorizedException	Account has been suspended.

Implementation Example

try {
    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Account(
        userId: "user-0001"
    );
    var result = await domain.AuthenticationAsync(
        keyId: "grn:gs2:ap-northeast-1:owner_id:key:namespace-0001:key:key-0001",
        password: "password-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(
        keyId: "grn:gs2:ap-northeast-1:owner_id:key:namespace-0001:key:key-0001",
        password: "password-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(
        "grn:gs2:ap-northeast-1:owner_id:key:namespace-0001:key:key-0001",
        "password-0001"
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        if (Gs2::Account::Error::FPasswordIncorrectError::TypeString == Task->GetTask().Error()->Type())
        {
            // Incorrect password specified.
        }
        if (Gs2::Account::Error::FBannedInfinityError::TypeString == Task->GetTask().Error()->Type())
        {
            // Account has been suspended.
        }
        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();
    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

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

Result

	Type	Description
item	EzAccount	Game 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 (!TestFalse(WHAT, Future2->GetTask().IsError())) return false;
    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

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 32 chars	Namespace name
accessToken	string	✓	~ 128 chars	User Id
type	int	✓	~ 1024	Slot Number
userIdentifier	string	✓	~ 1024 chars	User ID for takeover
password	string	✓	~ 128 chars	Password

Result

	Type	Description
item	EzTakeOver	Takeover 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(
        AccessToken
    )->TakeOver(
        0, // type
        "user-0001@gs2.io" // userIdentifier
    );
    const auto Future = Domain->AddTakeOverSetting(
        "password-0001"
    );
    Future->StartSynchronousTask();
    if (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();

deleteTakeOverSetting

Delete `Takeover Settings

Deletes the takeover settings that have been set.

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 32 chars	Namespace name
accessToken	string	✓	~ 128 chars	User Id
type	int	✓	~ 1024	Slot Number

Result

	Type	Description
item	EzTakeOver	Deleted 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(
        AccessToken
    )->TakeOver(
        0, // type
        "user-0001@gs2.io" // userIdentifier
    );
    const auto Future = Domain->DeleteTakeOverSetting(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

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

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 32 chars	Namespace name
type	int	✓	~ 1024	Slot Number
userIdentifier	string	✓	~ 1024 chars	User ID for takeover
password	string	✓	~ 128 chars	Password

Result

	Type	Description
item	EzAccount	Game Player Account

Error

Type	Base Type	Description
PasswordIncorrectException	UnauthorizedException	Incorrect 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,
        "user-0001@gs2.io",
        "password-0001"
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        if (Gs2::Account::Error::FPasswordIncorrectError::TypeString == Task->GetTask().Error()->Type())
        {
            // Incorrect password specified.
        }
        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();

get

Get takeover settings by specifying user ID

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 32 chars	Namespace name
accessToken	string	✓	~ 128 chars	User Id
type	int	✓	~ 1024	Slot Number

Result

	Type	Description
item	EzTakeOver	takeover 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(
        AccessToken
    )->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(
        AccessToken
    )->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);

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.

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

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 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<EzTakeOver>	List of Takeover Setting
nextPageToken	string	Page 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(
        AccessToken
    );
    const auto It = Domain->TakeOvers(
    );
    for (auto Item : *It)
    {

    }

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

    // Stop event handling
    Domain->UnsubscribeTakeOvers(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.

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

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 32 chars	Namespace name
accessToken	string	✓	~ 128 chars	User Id
type	int	✓	~ 1024	Slot Number
oldPassword	string	✓	~ 128 chars	Old Password
password	string	✓	~ 128 chars	Password

Result

	Type	Description
item	EzTakeOver	Takeover settings

Error

Type	Base Type	Description
PasswordIncorrectException	UnauthorizedException	Incorrect 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(
        AccessToken
    )->TakeOver(
        0, // type
        "user-0001@gs2.io" // userIdentifier
    );
    const auto Future = Domain->UpdateTakeOverSetting(
        "password-0001",
        "password-1001"
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        if (Gs2::Account::Error::FPasswordIncorrectError::TypeString == Task->GetTask().Error()->Type())
        {
            // Incorrect password specified.
        }
        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();