GS2-Account SDK for Game Engine API Reference

Specifications of models and API references for 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	Required	Default	Value Limits	Description
userId	string	✓	UUID	~ 128 chars	User ID
password	string	✓		~ 128 chars	Password Stores the password for securing the account. Passwords can be up to 128 characters long and play an important role in protecting your account.
createdAt	long	*	Now		Datetime of creation Unix time, milliseconds * Set automatically by the server

EzTakeOver

Takeover Information

Takeover Information is used when changing devices or moving/sharing an account across platforms. It consists of a unique string that identifies an individual and a password; by entering the correct combination, an Account (GS2 anonymous account) can be retrieved.

Multiple sets of Takeover Information can be configured for a single Account. To configure multiple sets, you must assign each one to a different slot. Slots can be specified from 0 to 1024, allowing for up to 1,025 types of Takeover Information to be set.

A typical example would be to store the account information for “Sign in with Apple” in slot 0 and the information for a Google account in slot 1. It should be noted that this Takeover Information serves only as a data holder; the authentication mechanism for social accounts must be prepared separately.

	Type	Required	Default	Value Limits	Description
userId	string	✓		~ 128 chars	User ID
type	int	✓		0 ~ 1024	Slot Number Specified in the range of 0 to 1024 to distinguish different Takeover Information.
userIdentifier	string	✓		~ 1024 chars	User ID for takeover A unique key used to identify an individual when taking over an account. If the same userIdentifier is specified for different accounts, the value set later will take precedence.
createdAt	long	*	Now		Datetime of creation Unix time, milliseconds * Set automatically by the server

EzPlatformId

Platform ID

Holds IDs for various platforms such as X, Instagram, and Facebook. Other players can search for players using various platform IDs.

When importing Instagram followers or Facebook friends as in-game friends, it is used to identify the GS2-Account account.

	Type	Required	Default	Value Limits	Description
type	int	✓		0 ~ 1024	Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform.
userIdentifier	string	✓		~ 1024 chars	User ID on various platforms The user’s unique identifier on the external platform (e.g., social media user ID or email address). Used together with the slot number (type) to identify a specific platform account.
userId	string	✓		~ 128 chars	GS2-Account User ID The GS2-Account user ID that this platform ID is linked to. Used to map between external platform identities and GS2 anonymous accounts.
createdAt	long	*	Now		Datetime of creation Unix time, milliseconds * Set automatically by the server

EzPlatformUser

Various platform user information

Holds user information from external platforms. Contains the mapping between a platform-specific user identifier and the corresponding GS2-Account user ID, used for searching players by their platform identity.

	Type	Required	Value Limits	Description
type	int	✓	0 ~ 1024	Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform.
userIdentifier	string	✓	~ 1024 chars	User ID on various platforms The user’s unique identifier on the external platform (e.g., social media user ID or email address). Used together with the slot number (type) to identify a specific platform account.
userId	string	✓	~ 128 chars	GS2-Account User ID The GS2-Account user ID that this platform user is linked to. Used to map between external platform identities and GS2 anonymous accounts.

EzBanStatus

Account Ban Status

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.

	Type	Required	Default	Value Limits	Description
name	string	✓	UUID	~ 36 chars	Ban status name Maintains a unique name for each Ban status. The name can be set to any value. If omitted, it is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Ban status. This ID allows for easy tracking of multiple Ban statuses.
reason	string	✓		~ 256 chars	Reason for BAN Explains the specific reason for the BAN. It can be up to 256 characters long and helps to clarify the cause of the BAN. This information is not only referenced by the account administrator and the operations team, but also included in the response value to the game client.
releaseTimestamp	long	✓			Date and time when the BAN will be released Indicates the date and time when the Account Ban will be released. Once this date and time has passed, the account will be automatically released from the BAN and normal access will be possible.

Methods

authentication

Authenticate a game player using the user ID and password obtained at account creation. On successful login, account credentials and a signature are issued. Pass these to GS2-Auth::Login to obtain an access token for using GS2 services.

Typically, you can use GS2-Profile::Login to combine this step with GS2-Auth::Login in a single call. See the sample programs in “Getting Started” for details.

The account credentials and signature expire after 1 hour.

Request

	Type	Required	Default	Value Limits	Description
namespaceName	string	✓		~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId	string	✓		~ 128 chars	User ID
keyId	string		“grn:gs2:{region}:{ownerId}:key:default:key:default”	~ 1024 chars	Encryption Key GRN
password	string	✓		~ 128 chars	Password Stores the password for securing the account. Passwords can be up to 128 characters long and play an important role in protecting your account.

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(
        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.PasswordIncorrectException e) {
    // Incorrect password specified.
} catch(Gs2.Gs2Account.Exception.BannedInfinityException 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.ModelFuture();
    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 game player account

Call this when the game is launched for the first time to create a player account. On success, a user ID and password are returned. Save these two values to persistent storage (e.g., PlayerPrefs or local save data) for future logins.

The password is automatically generated as a random value and cannot be set by the player. If you want players to transfer their account using a familiar identifier (such as an email address or social media account), register Takeover Information separately.

Request

	Type	Condition	Required	Default	Value Limits	Description
namespaceName	string		✓		~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).

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

Set up account recovery so that the player can restore their account after changing devices or reinstalling the app. By registering a takeover user ID (such as an email address) and a takeover password, the player can transfer their account to another device by entering the same combination.

Multiple takeover methods can be set up for a single account. By using different slot numbers, you can store different types of credentials — for example, an email address in slot 0 and a social media account in slot 1. Slot numbers can be specified in the range of 0 to 1024.

Note: This feature only stores data. Authentication with social accounts (OAuth, etc.) must be implemented separately on the game side.

Request

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession	GameSession	✓		GameSession
type	int	✓	0 ~ 1024	Slot Number Specified in the range of 0 to 1024 to distinguish different Takeover Information.
userIdentifier	string	✓	~ 1024 chars	User ID for takeover A unique key used to identify an individual when taking over an account. If the same userIdentifier is specified for different accounts, the value set later will take precedence.
password	string	✓	~ 128 chars	Password For security reasons, this password is treated as confidential information and only the hash value is stored.

Result

	Type	Description
item	EzTakeOver	Takeover Information created

Implementation Example

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).TakeOver(
        type: 0,
    );
    var result = await domain.AddTakeOverSettingAsync(
        userIdentifier: "user-0001@gs2.io",
        password: "password-0001"
    );
    var item = await result.ModelAsync();

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

addTakeOverSettingOpenIdConnect

Register takeover information using authentication results from external login services such as Google or Apple (OpenID Connect). With this method, no password setup is required.

To use this feature, you must configure the association between slot numbers and authentication services in the master data beforehand. Once OpenID Connect is configured for a slot, the standard “user ID + password” takeover method cannot be used for that slot.

Request

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession	GameSession	✓		GameSession
type	int	✓	0 ~ 1024	Slot Number Specified in the range of 0 to 1024 to distinguish different Takeover Information.
idToken	string	✓	~ 10240 chars	OpenID Connect ID Token

Result

	Type	Description
item	EzTakeOver	Takeover Information created

Implementation Example

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).TakeOver(
        type: 0,
    );
    var result = await domain.AddTakeOverSettingOpenIdConnectAsync(
        idToken: "0123456789"
    );
    var item = await result.ModelAsync();

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).TakeOver(
        type: 0,
    );
    var future = domain.AddTakeOverSettingOpenIdConnectFuture(
        userIdentifier: "user-0001@gs2.io",
        idToken: "0123456789"
    );
    yield return future;
    if (future.Error != null)
    {
        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->Account->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->TakeOver(
        0, // type
    );
    const auto Future = Domain->AddTakeOverSettingOpenIdConnect(
        "user-0001@gs2.io", // userIdentifier
        "0123456789" // idToken
    );
    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 information

Deletes a registered takeover setting. After deletion, the account can no longer be recovered using this takeover information.

Request

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession	GameSession	✓		GameSession
type	int	✓	0 ~ 1024	Slot Number Specified in the range of 0 to 1024 to distinguish different Takeover Information.

Result

	Type	Description
item	EzTakeOver	Takeover Information deleted

Implementation Example

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var result = await domain.DeleteTakeOverSettingAsync(
        type: 0
    );

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var future = domain.DeleteTakeOverSettingFuture(
        type: 0
    );
    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
    );
    const auto Future = Domain->DeleteTakeOverSetting(
        0 // type
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

doTakeOver

Execute account takeover

Transfer an account by entering the takeover user ID and takeover password. If the entered information matches, the linked account’s user ID and password are returned. Save the returned user ID and password to your game’s persistent storage for future logins.

Request

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
type	int	✓	0 ~ 1024	Slot Number Specified in the range of 0 to 1024 to distinguish different Takeover Information.
userIdentifier	string	✓	~ 1024 chars	User ID for takeover A unique key used to identify an individual when taking over an account. If the same userIdentifier is specified for different accounts, the value set later will take precedence.
password	string	✓	~ 128 chars	Password For security reasons, this password is treated as confidential information and only the hash value is stored.

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.PasswordIncorrectException 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.ModelFuture();
    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();

doTakeOverOpenIdConnect

Execute account takeover using OpenID Connect

Transfer an account using authentication from login services such as Google or Apple (OpenID Connect). The user ID and password of the account linked to the authentication are returned. Save the returned user ID and password to your game’s persistent storage for future logins.

Request

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
type	int	✓	0 ~ 1024	Slot Number Specified in the range of 0 to 1024 to distinguish different Takeover Information.
idToken	string	✓	~ 10240 chars	OpenID Connect ID Token

Result

	Type	Description
item	EzAccount	Game Player Account

Implementation Example

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    );
    var result = await domain.DoTakeOverOpenIdConnectAsync(
        type: 0,
        idToken: "0123456789"
    );
    var item = await result.ModelAsync();

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    );
    var future = domain.DoTakeOverOpenIdConnectFuture(
        type: 0,
        idToken: "0123456789"
    );
    yield return future;
    if (future.Error != null)
    {
        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->Account->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto Future = Domain->DoTakeOverOpenIdConnect(
        0, // type
        "0123456789" // idToken
    );
    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();

get

Get takeover information by type

Retrieves a single takeover setting by specifying its slot number (type). Use this to check which takeover method has been configured. For security reasons, the takeover password is not included in the response.

Request

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession	GameSession	✓		GameSession
type	int	✓	0 ~ 1024	Slot Number Specified in the range of 0 to 1024 to distinguish different Takeover Information.

Result

	Type	Description
item	EzTakeOver	Takeover Information

Implementation Example

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).TakeOver(
        type: 0,
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).TakeOver(
        type: 0,
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Account->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->TakeOver(
        0, // type
    );
    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,
    );
    
    // 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,
    );
    
    // 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);

    const auto Domain = Gs2->Account->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->TakeOver(
        0, // type
    );
    
    // 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 triggered when the value stored in the SDK’s local cache changes.

The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.

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

getAuthorizationUrl

Get the OpenID Connect authorization URL

Retrieves the URL for redirecting the player to the authentication page of an external login service such as Google or Apple. By directing the player to this URL, you can initiate the registration of takeover information or the execution of account takeover using OpenID Connect.

Request

	Type	Condition	Required	Default	Value Limits	Description
namespaceName	string		✓		~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
type	int		✓		0 ~ 1024	Slot Number Specified in the range of 0 to 1024 to distinguish different Takeover Information.

Result

	Type	Description
authorizationUrl	string	Authorization URL

Implementation Example

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var result = await domain.GetAuthorizationUrlAsync(
        type: 0
    );
    var authorizationUrl = result.AuthorizationUrl;

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var future = domain.GetAuthorizationUrlFuture(
        type: 0
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var authorizationUrl = future.Result.AuthorizationUrl;

    const auto Domain = Gs2->Account->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto Future = Domain->GetAuthorizationUrl(
        0 // type
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();
    const auto AuthorizationUrl = Result->AuthorizationUrl;

listTakeOverSettings

Get a list of registered takeover settings

Retrieves the list of takeover information registered for this player. For security reasons, takeover passwords are not included in the response.

Request

	Type	Required	Default	Value Limits	Description
namespaceName	string	✓		~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession	GameSession	✓			GameSession
pageToken	string			~ 1024 chars	Token specifying the position from which to start acquiring data
limit	int		30	1 ~ 1000	Number of data items to retrieve

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(
        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
    );
    
    // Start event handling
    var callbackId = domain.SubscribeTakeOvers(
        () => {
            // Called when an element of the list changes.
        }
    );

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

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

Warning

This event is triggered when the value stored in the SDK’s local cache changes.

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

updateTakeOverSetting

Change the takeover password

Changes the password of a takeover setting. To make the change, the current (old) password must be provided.

Note: If you want to enforce secure password changes using this API, make sure to disable access to the “delete takeover information” API. Since deleting does not require password verification, a player could effectively change their password by deleting and re-creating the takeover setting.

Request

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession	GameSession	✓		GameSession
type	int	✓	0 ~ 1024	Slot Number Specified in the range of 0 to 1024 to distinguish different Takeover Information.
oldPassword	string	✓	~ 128 chars	Old Password
password	string	✓	~ 128 chars	Password For security reasons, this password is treated as confidential information and only the hash value is stored.

Result

	Type	Description
item	EzTakeOver	Takeover Information updated

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,
    );
    var result = await domain.UpdateTakeOverSettingAsync(
        oldPassword: "password-0001",
        password: "password-1001"
    );
    var item = await result.ModelAsync();
} catch(Gs2.Gs2Account.Exception.PasswordIncorrectException e) {
    // Incorrect password specified.
}

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).TakeOver(
        type: 0,
    );
    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.ModelFuture();
    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
    );
    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();

addPlatformIdSetting

Saves a user ID from an external service such as X (formerly Twitter), Instagram, or Facebook, linked to the game account.

Specify a type (slot number) in the range of 0 to 1024 to distinguish between platform types. Specify the user identifier as the user ID on each platform.

Other players can search for a player by specifying the type and user identifier. For example, this can be used to implement a feature that adds social media friends as in-game friends.

Request

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession	GameSession	✓		GameSession The GS2-Account user ID that this platform ID is linked to. Used to map between external platform identities and GS2 anonymous accounts.
type	int	✓	0 ~ 1024	Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform.
userIdentifier	string	✓	~ 1024 chars	User ID on various platforms The user’s unique identifier on the external platform (e.g., social media user ID or email address). Used together with the slot number (type) to identify a specific platform account.

Result

	Type	Description
item	EzPlatformId	Platform ID created

Implementation Example

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).PlatformId(
        type: 0,
        userIdentifier: "123456"
    );
    var result = await domain.AddPlatformIdSettingAsync(
    );
    var item = await result.ModelAsync();

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).PlatformId(
        type: 0,
        userIdentifier: "123456"
    );
    var future = domain.AddPlatformIdSettingFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        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->Account->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->PlatformId(
        0, // type
        "123456" // userIdentifier
    );
    const auto Future = Domain->AddPlatformIdSetting(
    );
    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();

deletePlatformIdSetting

Delete a Platform ID

Deletes a registered Platform ID. After deletion, the player can no longer be found by searching with that Platform ID.

Request

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession	GameSession	✓		GameSession The GS2-Account user ID that this platform ID is linked to. Used to map between external platform identities and GS2 anonymous accounts.
type	int	✓	0 ~ 1024	Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform.

Result

	Type	Description
item	EzPlatformId	Platform ID deleted

Implementation Example

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).PlatformId(
        type: 0,
        userIdentifier: "123456"
    );
    var result = await domain.DeletePlatformIdSettingAsync(
    );

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).PlatformId(
        type: 0,
        userIdentifier: "123456"
    );
    var future = domain.DeletePlatformIdSettingFuture(
    );
    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
    )->PlatformId(
        0, // type
        "123456" // userIdentifier
    );
    const auto Future = Domain->DeletePlatformIdSetting(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

findPlatformUser

Search for a player by Platform ID

Search for a game player by specifying the platform type and user identifier. For example, this can be used to find in-game players from a social media friends list.

Request

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
type	int	✓	0 ~ 1024	Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform.
userIdentifier	string	✓	~ 1024 chars	User ID on various platforms The user’s unique identifier on the external platform (e.g., social media user ID or email address). Used together with the slot number (type) to identify a specific platform account.

Result

	Type	Description
item	EzPlatformUser	Various platform user information

Implementation Example

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).PlatformId(
        type: 0,
        userIdentifier: "123456"
    );
    var result = await domain.FindPlatformUserAsync(
    );
    var item = await result.ModelAsync();

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).PlatformId(
        type: 0,
        userIdentifier: "123456"
    );
    var future = domain.FindPlatformUserFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        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->Account->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->PlatformId(
        0, // type
        "123456" // userIdentifier
    );
    const auto Future = Domain->FindPlatformUser(
    );
    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();

getPlatformId

Get a Platform ID by type

Retrieves a single Platform ID by specifying its slot number (type). Use this to check which user ID is linked to a specific platform.

Request

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession	GameSession	✓		GameSession The GS2-Account user ID that this platform ID is linked to. Used to map between external platform identities and GS2 anonymous accounts.
type	int	✓	0 ~ 1024	Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform.

Result

	Type	Description
item	EzPlatformId	Platform ID

Implementation Example

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).PlatformId(
        type: 0,
        userIdentifier: "123456"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).PlatformId(
        type: 0,
        userIdentifier: "123456"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Account->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->PlatformId(
        0, // type
        "123456" // 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
    ).PlatformId(
        type: 0,
        userIdentifier: "123456"
    );
    
    // 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
    ).PlatformId(
        type: 0,
        userIdentifier: "123456"
    );
    
    // 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);

    const auto Domain = Gs2->Account->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->PlatformId(
        0, // type
        "123456" // userIdentifier
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Account::Model::FPlatformId> 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 triggered when the value stored in the SDK’s local cache changes.

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

listPlatformIdSettings

Get a list of registered Platform IDs

Retrieves the list of external service IDs linked to this player. Use this to check which platform IDs have been registered.

Request

	Type	Required	Default	Value Limits	Description
namespaceName	string	✓		~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSession	GameSession	✓			GameSession
pageToken	string			~ 1024 chars	Token specifying the position from which to start acquiring data
limit	int		30	1 ~ 1000	Number of data items to retrieve

Result

	Type	Description
items	List<EzPlatformId>	List of Platform IDs
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.PlatformIdsAsync(
    ).ToListAsync();

    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.PlatformIds(
    );
    List<EzPlatformId> items = new List<EzPlatformId>();
    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->PlatformIds(
    );
    TArray<Gs2::UE5::Account::Model::FEzPlatformIdPtr> 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.SubscribePlatformIds(
        () => {
            // Called when an element of the list changes.
        }
    );

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

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

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

    const auto Domain = Gs2->Account->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribePlatformIds(
        []() {
            // Called when an element of the list changes.
        }
    );

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

Warning

This event is triggered when the value stored in the SDK’s local cache changes.

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