11. ユーティリティ

本章では、NEX が提供するユーティリティ機能について説明します。

11.1. ユーティリティ利用の流れ

ユーティリティ機能を利用する基本的な流れは以下のとおりです。

  1. ゲームサーバーにログインする
  2. サービスクライアントを初期化する( 11.2.
  3. ユーティリティの各種機能を利用する
    • パスワード付き NEX ユニーク ID を利用する( 11.3.2.
    • アプリケーション向けの設定値を取得する( 11.4.3.
    • その他、各 API を呼び出す
  4. サービスクライアントの終了処理を行い、ゲームサーバーからログアウトする

11.2. サービスクライアントの初期化・終了

ユーティリティ機能 のサービスクライアント( UtilityClient )の初期化および終了処理は、マッチメイクでの処理と同じです( 4.3. )。

11.3. NEX ユニーク ID

NEX ユニーク ID は、ゲームサーバーから発行されるユニークな ID です。

UtilityClient::AcquireNexUniqueId()、UtilityClient::AcquireNexUniqueIdWithPassword() により取得します。 後者はパスワード付きの ID で、パスワードが必要な機能では後者を使用します。 これらの関数が呼ばれる度に新しい NEX ユニーク ID が発行されます。 どちらも同一の ID 体系になっていてパスワードが返るかどうかだけが異なります。 UtilityClient::IsValidNexUniqueId() により、 NEX ユニーク ID がサーバーから発行された妥当な ID であるかどうかを検証できます。

注意

NEX ユニーク ID は、ゲームサーバーを跨いでのユニーク性はありません。 サーバ環境の違いに対しても同様ですので、開発環境や製品環境の間でユニーク性を確保するものではありません。

11.3.1. パスワードなし NEX ユニーク ID の利用

ランキングでは、パスワードのない NEX ユニーク ID を利用します。

11.3.1.1. ランキングでの NEX ユニーク ID の利用

ランキングでは、 NEX ユニーク ID を利用することで、 プリンシパル ID よりも細かい単位でスコアを登録することができます。

例えば、以下のような場合に利用します。

  • 1 つのセーブデータを複数のユーザーが共有し、各ユーザーが別々にスコアを登録したい場合
  • 1 人のユーザーが複数のキャラクタでゲームをプレイし、各キャラクタごとにスコアを登録したい場合

NEX ユニーク ID を利用する場合、ランキング初回利用時に NEX ユニーク ID の取得を行い、 取得した NEX ユニーク ID を各ランキング関数の引数に与えてください。 一度取得した NEX ユニーク ID はセーブデータ内に保存し、 次回以降はセーブデータから取得して利用するようにしてください。

プリンシパル ID 単位でスコアを登録する場合は、 NEX ユニーク ID に nn::nex::INVALID_UNIQUEID(デフォルト) を指定します。

注意

ゲームサーバーから発行される NEX ユニーク ID を使用する場合は、OMAS にて利用方法を明記し、下記の点について考慮してください。

  • セーブデータをユーザーが削除した場合、使用していた NEX ユニーク ID を特定する方法がなくなり、 サーバー上のデータを更新、削除できずに残り続けることになります。
  • 同じユーザーが、セーブデータの作成、ハイスコアのアップロード、セーブデータの削除、 を繰り返すことで、上位ランキングを同じユーザーが独占してしまう可能性があります。
  • フレンドランキングでは、プリンシパル ID を元にランキングを取得するため、 自分やフレンドが複数の NEX ユニーク ID でスコアを登録していた場合、 全ての NEX ユニーク ID のスコアがリストに含まれることになります。

11.3.2. パスワード付き NEX ユニーク ID の利用

MatchmakeReferee 機能およびランキング 2 では、パスワード付き NEX ユニーク ID を利用します。

パスワード付き NEX ユニーク ID を利用するには、まず、 UtilityClient::AcquireNexUniqueIdWithPassword() により、 パスワード付き NEX ユニーク ID とそのパスワードのセットを取得します。

取得した NEX ユニーク ID とパスワードのセットを UtilityClient::AssociateNexUniqueIdWithMyPrincipalId() を使用してサーバー側に登録し、プリンシパル ID との関連付けを行います。

プリンシパル ID に対して関連付けを行った NEX ユニーク ID を、そのプリンシパル ID の 関連 NEX ユニーク ID と呼びます。 リストで登録することで、1 つのプリンシパル ID が複数の関連 NEX ユニーク ID を持つことができます。 関連 NEX ユニーク ID のうち、先頭に登録したものを プライマリ関連 NEX ユニーク ID と呼びます。

UtilityClient::AssociateNexUniqueIdWithMyPrincipalId() を呼んだ際、 そのプリンシパル ID に対して以前登録されていた関連 NEX ユニーク ID が含まれていないと、 その関連 NEX ユニーク ID に紐づくデータは削除されます。 そのため、削除対象でない NEX ユニーク ID は、たとえ以前登録済みのものであっても、関数呼び出し時に毎回リストに含める必要があります。

例として、セーブデータが 3 つあるアプリで、セーブデータごとにサーバー上のデータを分けたい場合について考えます。 まず、セーブデータが新規作成されたときに、サーバーから新しい NEX ユニーク ID を取得します。これをセーブデータに保存します。

次に、セーブデータが選択されたときに、 そのセーブデータが持つ NEX ユニーク ID を先頭にした全セーブデータ分の NEX ユニーク ID リストを関連付けます。 既に登録している NEX ユニーク ID もリストに含める必要があるため、個別のセーブデータのほかに、共通のセーブデータを用意する必要があります。 この処理は、初回だけでなくセーブデータが切り替わるごとに毎回必要です。 この状態で各種機能を呼び出すと、NEX ユニーク ID 単位での処理が行われます。

最後に、セーブデータが削除されたときに、保存されている NEX ユニーク ID を削除します。 直後、あるいは次回のセーブデータ選択時に、その NEX ユニーク ID がリストに入っていない状態で関連付けを行うことで、 削除された NEX ユニーク ID に紐づいていたサーバー上のデータが削除されます。

11.3.2.1. MatchmakeReferee 機能での NEX ユニーク ID の利用

MatchmakeReferee 機能では、パスワード付きの NEX ユニーク ID を利用することで、 プリンシパル ID よりも細かい単位で個人統計を管理することができます。

関連 NEX ユニーク ID を登録しておくと、以後の処理で個人統計は、プライマリ関連 NEX ユニーク ID 単位で記録されます。

関連 NEX ユニーク ID の削除時には、それらに紐付く個人統計が削除されます。

11.3.2.2. ランキング 2 での NEX ユニーク ID の利用

ランキング 2 では、パスワード付きの NEX ユニーク ID を利用することで、 プリンシパル ID よりも細かい単位でスコアやユーザー共通データを管理することができます。

関連 NEX ユニーク ID を登録しておくと、そのユーザーに対するそれ以降の処理を NEX ユニーク ID 単位で行います。

関連 NEX ユニーク ID の登録時には、NEX ユニーク ID を関連付けていないときに登録したスコアとユーザー共通データが削除されます。 関連 NEX ユニーク ID の削除時には、それらに紐付くスコアとユーザー共通データが削除されます。

従来のランキングではパスワードなしの NEX ユニーク ID を使用していましたが、 関連付けが必要なため、パスワード付きのものを使用しています。 これにより、セーブデータ作成と削除とを繰り返すことでランキングに複数のスコアを登録できる問題などが解消されています。

11.4. アプリケーション向けの設定値の管理

NEX ではアプリケーション向けの設定値をサーバで保存しておき、アプリケーションからその設定値を取得することができます。

この設定値に従って動作を変えるようにアプリケーション側を実装しておくと、アプリケーションの ROM を更新せずに、サーバ側で保持している設定値を変更するだけで、アプリケーションの挙動を変えることができます。

11.4.1. 想定しているユースケース

アプリケーション向けの設定値は、以下のようなユースケースを想定しています。 いずれのケースも、アプリケーション側の処理で使用する閾値をサーバー上で保持し、クライアント側はサーバーから取得した閾値を使用するようにしています。

  • DataStore のデータアップロード時の足切り率

    一定の条件以上ならデータをアップロードするような仕様の場合に、足切り条件の閾値をサーバーで保持することで、アップロードされるデータの数を調整することができます。

  • レーティングの閾値

    プレイヤーのスキルをレーティングとしてクライアント上で表示する際に、レーティングの判定条件の閾値をサーバーで保持することで、プレイヤー数やプレイ状況に応じてレーティングを調整することができます。

上記以外の用途で使用される場合は、事前に弊社にご相談ください。

11.4.2. 設定値の内容

設定値は、以下の要素で構成されます。

Table 11.1 アプリケーション向けの設定値の構成
項目名 概要 設定可能な値
設定インデックス 設定値の切り替えに使用します。最大 20 個の設定インデックスを使用できます。 0 ~ 19 の整数
キー 設定値のキー。1 つの設定インデックスに対して、最大 100 個のキーを登録できます。 16 ビットの非負整数
設定値。 32 ビットの整数
説明 設定値の内容についての説明。 UTF-8 の文字列

設定インデックスを切り替えることで、設定値を複数種類用意することができます。例えばキーは同じままで、リージョン毎に設定値を変えたい場合などは、リージョン毎に設定インデックスを用意し、各設定インデックスに対して設定値を登録してください。

アプリケーション向けの設定値の登録や削除は、NMAS や WebAPI から実行できます。 WebAPI の詳細は「 12.7.2. アプリケーション向けの設定値の管理 」を参照してください。

11.4.3. 設定値を取得する

アプリケーションから設定値を取得する際は、取得対象の設定インデックスを指定して、UtilityClient::GetIntegerSettings() を使用します。

11.4.4. 利用時の注意点

  • サーバーの負荷軽減のため、アプリケーションから設定値を取得する際は NEX サーバーへのログイン直後などに行い、取得した設定値はアプリケーション側で一定期間保持して使いまわすようにしてください。
  • 設定インデックを使用してデバッグ用と製品用で設定を分ける場合は、専用のデバッグメニューを用意して設定インデックスを切り替えるなどして、デバッグ用の設定インデックスのまま製品が出されることがないように十分注意してください。
  • サーバーで保存している設定値を変更する際は、以下の点に注意してください。
    • 設定値の変更直後は、アプリケーションからの取得タイミングによっては、古い設定値のクライアントと新しい設定値のクライアントが混在することがあります。設定値が異なるクライアントが混在しても、挙動がおかしくならないようにしてください。例えば、古い設定値のクライアントと新しい設定値のクライアントとで同じマッチメイクセッションに入れたくない場合は、マッチメイクセッションの属性値を変えるなどの対応を行ってください。
    • いきなりすべての端末に設定を反映をするのではなく、一部の端末にのみ設定値の変更を反映して動作を確認したい場合は、いつの間に通信をご利用ください。