Vivox アクセストークンと UAS の併用#

どのプレイヤーがどのチャンネルにアクセスできるかを完全に制御するために、自分のバックエンドで Vivox アクセストークン (VAT) を作成できます。

前提条件:

1. Unity Cloud プロジェクトを設定する
   • プロジェクト ID、環境 ID、環境名を確認してください。
2. UAS カスタム ID プロバイダーを有効にする
   • この設定のサービスアカウントの認証情報が手元にあることを確認してください。

以下の図は、この設定の全体的なフローを示しています。

VAT の作成#

1. Vivox SDK は、カスタムプロバイダー実装を使用する際に VAT が必要な場合にバックエンドに VAT をリクエストします。
2. GetTokenAsync メソッド内で VAT をリクエストするときに、accessToken をバックエンドへのリクエストに追加します。
3. バックエンドで、トークンから必要な情報を検証して抽出し、Vivox アクセストークンを作成してそれをクライアントに送り返します。

クライアント側の設定

ゲームクライアントでは、Vivox SDK の IVivoxTokenProvider インターフェースを実装するクラスを作成し、それを VivoxService に登録します。

IVivoxTokenProvider の実装を VivoxService.Instance.SetTokenProvider を呼び出すことで登録すると、Vivox はトークンが必要なアクション (サインインなど) で常にその実装の IVivoxTokenProvider.GetTokenAsync メソッドを呼び出します。

ペイロードを作成するのに必要な情報が、オーバーライドされた IVivoxTokenProvider.GetTokenAsync メソッドの入力として提供されます。この情報は、VAT を作成するときに使用されます。

その場合でも、サーバー側トークンベンディングを設定し、オーバーライドされた IVivoxTokenProvider.GetTokenAsync メソッド内でそのトークンをフェッチする必要があります。

サブスクライブするには#

プレイヤーをサインインする前に、以下を使用して IVivoxTokenProvider の実装を登録する必要があります。

VivoxService.Instance.SetTokenProvider(new CustomTokenProvider());

トークンをフェッチする#

オーバーライドされたメソッドで提供されているすべてのパラメーター (一部は空の場合あり) を使用してペイロードを作成し、安全なサーバーに送信して、Vivox アクセストークンを作成します。

すべてのパラメーターを送信することをお勧めします。ペイロードで必要なもののみが返されます。そのペイロードを GetTokenAsync メソッドの入力として使用します。

さらに、リクエストのペイロード内の UAS accessToken を送信して、サーバーがそれを検証してそこから Vivox アクセストークンを生成できるようにする必要があります。

トークンによって、空になるパラメーターが異なります。例えば、サインイントークンでは targetUserUri と channelUri が空になります。これは想定されている動作です。

トークン生成の例を以下に示します。

public class VoiceManager : MonoBehaviour
{
    async void Start()
    {
        // Must be done before any other Vivox action otherwise tokens will not be generated properly.
        VivoxService.Instance.SetTokenProvider(new VivoxTokenProvider());
        await UnityServices.InitializeAsync();
        await VivoxService.Instance.InitializeAsync();
    }
}

class VivoxTokenProvider : IVivoxTokenProvider
{
    public Task<string> GetTokenAsync(string issuer = null, TimeSpan? expiration = null, string targetUserUri = null, string action = null, string channelUri = null, string fromUserUri = null, string realm = null)
    {
        if (!AuthenticationService.Instance.SessionTokenExists)
        {
          // Player not logged in!
        }
        var accessToken = AuthenticationService.Instance.AccessToken
        // Implement token fetching logic here.
        // The method parameters together with the accessToken from the AuthenticationService contain the necessary information for crafting the request payload.
        // This will be called whenever a token is needed for a Vivox action
    }
}

サーバー側の設定#

バックエンドサービスは、クライアントが必要なときに VAT を受け取るために 上記 の GetTokenAsync 関数内で呼び出すことができる API 関数を公開する必要があります。

VAT の作成方法に関する実装の詳細については、安全なサーバー上でのトークンの生成 を参照してください。

トークンのペイロードの詳細については、アクセストークンのペイロード を参照してください。

VAT を作成するときは、以下のユーザー SIP URI を subject として使用する必要があります。

sip:.issuer.unity_player_id.unity_environment_id.@domain.vivox.com

issuer は、Unity プロジェクトの Vivox 発行者を指します。unity_player_id は、UAS プレイヤー ID を指します。unity_environment_id は、Unity Cloud 環境の環境 ID を指します。

これらの値はいずれも、GetTokenAsync メソッド内でクライアントからバックエンドへ送信される accessToken から抽出できます。

その後、accessToken は トークン ID の検証 で説明されている手順に従って検証されます。

トークンの sub クレームには、UAS プレイヤー ID が含まれています。トークンの aud クレームには、環境 ID が含まれています。aud 値は大文字小文字が区別される文字列の配列で、それぞれ StringOrURI 値が含まれています。

{
  "header": {
    "alg": "RS256",
    "kid": "<id>",
    "typ": "JWT"
  },
  "payload": {
    "aud": [
      "upid:{{unity_project_id}}",
      "envName:{{environment_name}}",
      "envId:{{unity_environment_id}}" // unity environment id
    ],
    "exp": 1617677595, // expires at
    "iat": 1617673872, // issued at
    "nbf": 1617673872, // not valid before
    "sub": "{{unity_player_id}}", // UAS player ID
    "project_id": "{{unity_project_id}}" // unity project id
  }
}

それを使用して VAT を作成し、クライアントに送り返すことができます。