GS2-Account SDK for Game Engine API リファレンス

モデル

EzAccount

ゲームプレイヤーアカウント

ゲームプレイヤーを識別するID情報のエンティティです。ゲームプレイヤーアカウントは匿名アカウントであり、ユーザーID(UUID)とパスワード(ランダムな32文字の文字列)で構成されるため、ゲームプレイヤーはメールアドレスなどの情報を入力する必要はありません。

発行されたゲームプレイヤーアカウントは、デバイスのローカルストレージに保存しておき、次回以降ログインに使用します。

	型	必須	デフォルト	値の制限	説明
userId	string	✓	UUID	~ 128文字	ユーザID
password	string	✓		~ 128文字	パスワード
createdAt	long	✓			作成日時

EzTakeOver

引継ぎ情報

引継ぎ情報とは、デバイスの機種変更やプラットフォーム間のアカウントの移動・共有時に使用する情報です。個人を識別するユニークな文字列とパスワードで構成され、その適切な組み合わせを入力することで、Account(匿名アカウント)を取得することができます。

1つの Account に対して複数の引継ぎ情報を設定できます。複数の引継ぎ情報を設定するにはそれぞれ異なるスロットを指定する必要があります。スロットには0～1024を指定できますので、最大1025種類の引継ぎ情報を設定可能です。

具体的な用例としては 0 には Twitter のアカウント情報を、1 には Sign-in Apple のアカウント情報を、2 には Google のアカウント情報を保存するようにする。というような使い方が想定されています。あくまでこの引継ぎ情報はデータホルダーであり、ソーシャルアカウントとの認証の仕組みは別途用意する必要があります。

	型	必須	値の制限	説明
userId	string	✓	~ 128文字	ユーザーID
type	int	✓	~ 1024	スロット番号
userIdentifier	string	✓	~ 1024文字	引き継ぎ用ユーザーID
createdAt	long	✓		作成日時

メソッド

authentication

アカウントの認証

create 関数で発行したユーザID・パスワードを使用してゲームプレイヤーの認証を行います。認証が完了すると アカウント認証情報 と 署名 が発行されます。 アカウント認証情報 と 署名 を GS2-Auth::Login にわたすことで、GS2の各サービスにアクセスするための アクセストークン を得ることができます。なおこのAPIとGS2-Auth::LoginをひとまとめにしたものがGS2-Profile::Loginではじめかた⇒サンプルプログラムで解説しています。

アカウント認証情報 と 署名 は1時間の有効期限が存在します。

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 32文字	ネームスペース名
userId	string	✓	~ 128文字	ユーザID
keyId	string	✓	~ 1024文字	暗号鍵GRN
password	string	✓	~ 128文字	パスワード

Result

	型	説明
item	EzAccount	ゲームプレイヤーアカウント
body	string	署名対象のアカウント情報
signature	string	署名

Error

このAPIには特別な例外が定義されています。 GS2-SDK for GameEngine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。一般的なエラーの種類や、ハンドリング方法はこちらのドキュメントを参考にしてください。

型	基底クラス	説明
PasswordIncorrectException	UnauthorizedException	パスワードの指定が不適切です
BannedInfinityException	UnauthorizedException	アカウントが利用停止されています

実装例

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 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.Authentication(
        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 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 Body = Result->Body;
    const auto Signature = Result->Signature;

create

ゲームプレイヤーを識別するアカウントを新規作成

このAPIの実行に成功すると、作成したアカウントの情報が返ります。返ったアカウント情報のうち、認証処理に使用するユーザIDとパスワードを永続化してください。

ここで発行されるパスワードはランダム値であり、ゲームプレイヤーの任意の値を指定することはできません。 引き継ぎ設定 としてゲームプレイヤーにとってわかりやすい識別子を登録することができます。

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 32文字	ネームスペース名

Result

	型	説明
item	EzAccount	作成したゲームプレイヤーアカウント

実装例

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

引き継ぎ設定 を追加

引き継ぎ設定 は機種変更などを行ったときにアカウントの引き継ぎをできるようにする設定です。 引き継ぎ設定 は 引き継ぎ用ユーザーID と 引き継ぎ用パスワード の組み合わせで実行できるようにします。

スロット番号 に異なる値を指定することで、1つのアカウントに対して複数の 引き継ぎ設定 を保持できます。たとえば、 スロット番号:0 にメールアドレス・パスワードを、 スロット番号:1 にソーシャルメディアのID情報を格納するようにし、ゲームプレイヤーは好みの引き継ぎ手段を選択できるようにする。といった運用が可能です。

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 32文字	ネームスペース名
accessToken	string	✓	~ 128文字	ユーザーID
type	int	✓	~ 1024	スロット番号
userIdentifier	string	✓	~ 1024文字	引き継ぎ用ユーザーID
password	string	✓	~ 128文字	パスワード

Result

	型	説明
item	EzTakeOver	作成した引き継ぎ設定

実装例

    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.AddTakeOverSetting(
        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

引き継ぎ設定 の削除

設定されている 引き継ぎ設定 を削除します。

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 32文字	ネームスペース名
accessToken	string	✓	~ 128文字	ユーザーID
type	int	✓	~ 1024	スロット番号

Result

	型	説明
item	EzTakeOver	削除した引き継ぎ設定

実装例

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

引き継ぎを実行

指定された 引き継ぎ用ユーザID と 引き継ぎ用パスワード が一致していた場合、設定されたアカウント情報を応答します。応答されたアカウント情報から ユーザID と パスワード を永続化して利用してください。

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 32文字	ネームスペース名
type	int	✓	~ 1024	スロット番号
userIdentifier	string	✓	~ 1024文字	引き継ぎ用ユーザーID
password	string	✓	~ 128文字	パスワード

Result

	型	説明
item	EzAccount	ゲームプレイヤーアカウント

Error

型	基底クラス	説明
PasswordIncorrectException	UnauthorizedException	パスワードの指定が不適切です

実装例

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.DoTakeOver(
        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

ユーザーIDを指定して引き継ぎ設定を取得

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 32文字	ネームスペース名
accessToken	string	✓	~ 128文字	ユーザーID
type	int	✓	~ 1024	スロット番号

Result

	型	説明
item	EzTakeOver	引き継ぎ設定

実装例

    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 item = Domain.Model();

listTakeOverSettings

設定されている 引き継ぎ設定 の一覧を取得

ゲームプレイヤーが設定した 引き継ぎ設定 の一覧を取得できます。設定されている 引き継ぎ用パスワード の値は取得できません。

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 32文字	ネームスペース名
accessToken	string	✓		~ 128文字	ユーザーID
pageToken	string			~ 1024文字	データの取得を開始する位置を指定するトークン
limit	int	✓	30	1 ~ 1000	データの取得件数

Result

	型	説明
items	List<EzTakeOver>	引き継ぎ設定のリスト
nextPageToken	string	リストの続きを取得するためのページトークン

実装例

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

    }

updateTakeOverSetting

引き継ぎ設定 のパスワードを変更する

このAPIを経由して 引き継ぎ用パスワード を更新するためには、すでに設定されている 引き継ぎ用パスワード を知っていなければ実行できません。セキュアな 引き継ぎ設定 の更新を実現したい場合に使用します。

このAPIを使用する際には、 引き継ぎ設定 の削除APIのアクセス権限を剥奪することを忘れないようにしてください。ゲームプレイヤーが自分の 引き継ぎ設定 の削除するにはパスワードの認証が必要ありません。削除して再作成することで、実質的に 引き継ぎ用パスワード の変更ができてしまいます。

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 32文字	ネームスペース名
accessToken	string	✓	~ 128文字	ユーザーID
type	int	✓	~ 1024	スロット番号
oldPassword	string	✓	~ 128文字	古いパスワード
password	string	✓	~ 128文字	パスワード

Result

	型	説明
item	EzTakeOver	引き継ぎ設定

Error

型	基底クラス	説明
PasswordIncorrectException	UnauthorizedException	パスワードの指定が不適切です

実装例

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