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

モデル

EzAccount

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

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

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

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

EzTakeOver

引継ぎ情報

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

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

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

型必須デフォルト値の制限説明
userIdstring✓~ 128文字ユーザーID
typeint✓~ 1024スロット番号
userIdentifierstring✓~ 1024文字引き継ぎ用ユーザーID
createdAtlong✓作成日時

EzBanStatus

アカウントBANの情報

型必須デフォルト値の制限説明
namestring✓UUID~ 36文字BANステータス名
reasonstring✓~ 256文字アカウントBANされた理由
releaseTimestamplong✓BANが解除される日時

メソッド

authentication

アカウントの認証

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

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

Request

型必須デフォルト値の制限説明
namespaceNamestring✓~ 32文字ネームスペース名
userIdstring✓~ 128文字ユーザーID
keyIdstring✓~ 1024文字暗号鍵GRN
passwordstring✓~ 128文字パスワード

Result

型説明
itemEzAccountゲームプレイヤーアカウント
banStatusesList<EzBanStatus>BAN状態リスト
bodystring署名対象のアカウント情報
signaturestring署名

Error

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

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

実装例

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

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

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

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

Request

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

Result

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

実装例

    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

型必須デフォルト値の制限説明
namespaceNamestring✓~ 32文字ネームスペース名
accessTokenstring✓~ 128文字ユーザーID
typeint✓~ 1024スロット番号
userIdentifierstring✓~ 1024文字引き継ぎ用ユーザーID
passwordstring✓~ 128文字パスワード

Result

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

実装例

    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

型必須デフォルト値の制限説明
namespaceNamestring✓~ 32文字ネームスペース名
accessTokenstring✓~ 128文字ユーザーID
typeint✓~ 1024スロット番号

Result

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

実装例

    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

型必須デフォルト値の制限説明
namespaceNamestring✓~ 32文字ネームスペース名
typeint✓~ 1024スロット番号
userIdentifierstring✓~ 1024文字引き継ぎ用ユーザーID
passwordstring✓~ 128文字パスワード

Result

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

Error

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

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

実装例

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

型必須デフォルト値の制限説明
namespaceNamestring✓~ 32文字ネームスペース名
accessTokenstring✓~ 128文字ユーザーID
typeint✓~ 1024スロット番号

Result

型説明
itemEzTakeOver引き継ぎ設定

実装例

    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;
    }
値の変更イベントハンドリング
    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).TakeOver(
        type: 0,
        userIdentifier: "user-0001@gs2.io"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    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
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Account::Model::FTakeOver> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    Domain->Unsubscribe(CallbackId);

listTakeOverSettings

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

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

Request

型必須デフォルト値の制限説明
namespaceNamestring✓~ 32文字ネームスペース名
accessTokenstring✓~ 128文字ユーザーID
pageTokenstring~ 1024文字データの取得を開始する位置を指定するトークン
limitint✓301 ~ 1000データの取得件数

Result

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

実装例

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

    }
値の変更イベントハンドリング
    var domain = gs2.Account.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeTakeOvers(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    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
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->SubscribeTakeOvers(
        []() {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    Domain->UnsubscribeTakeOvers(CallbackId);

updateTakeOverSetting

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

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

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

Request

型必須デフォルト値の制限説明
namespaceNamestring✓~ 32文字ネームスペース名
accessTokenstring✓~ 128文字ユーザーID
typeint✓~ 1024スロット番号
oldPasswordstring✓~ 128文字古いパスワード
passwordstring✓~ 128文字パスワード

Result

型説明
itemEzTakeOver引き継ぎ設定

Error

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

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

実装例

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