ドキュメント

Vivox Unity SDK

Vivox Unity SDK

Vivox Unity SDK 16.0.0 アップグレードガイド

Upgrade from previous Vivox versions to version 16.0.0.
読み終わるまでの所要時間 20 分最終更新 8ヶ月前
注
バージョン 15.1.x 以前の Vivox Unity からアップグレードする場合は、こちらのガイドに従います。
このガイドには Vivox Unity SDK バージョン 16.0.0 にアップグレードする方法に関する詳細と、2 つのバージョンの SDK の違いが示されています。
バージョン 16.0.0 は機能が簡略化されているほか、以下の関連する領域にも変更が必要です。
  • SDK の初期化
  • ログイン/ログアウト
  • プレイヤーのブロック
  • チャンネルへの接続
  • チャンネル参加者の管理
  • オーディオデバイスの管理
    • アクティブなデバイスの設定
    • デバイスのゲイン/音量の設定
    • デバイスのミュート

SDK の設定と初期化

Vivox API にアクセスするために、
using VivoxUnity;
を 
using Unity.Services.Vivox;
に置き換えます。
VivoxUnity 名前空間はなくなりました。
さらに、元の SDK を初期化する手段であった Client がなくなりました。

認証の使用

注
Vivox デベロッパーポータルの認証情報を使用している場合は、こちらのセクションをスキップし、Vivox デベロッパーポータルの Credentials セクションに移動してください。
Unity Authentication パッケージを使用している場合は、以下の例に示すように、まずは 
await UnityServices.InitializeAsync()
、次に 
await AuthenticationService.Instance.SignInAnonymously()
を呼び出してから、
await VivoxService.Instance.InitializeAsync()
 を呼び出します。
async void InitializeAsync(){    await UnityServices.InitializeAsync();    await AuthenticationService.Instance.SignInAnonymouslyAsync();    await VivoxService.Instance.InitializeAsync();}
AuthenticationService.Instance
で指定されたその他のサインインオプションを使用することもできます。
プロジェクトで Unity Dashboard の認証情報を使用しているものの、AuthenticationService パッケージを使用しない場合は、テストモード をオンにして、
AuthenticationService
サインイン呼び出しを省略できます。テストモード をオンにするには、Unity エディターで Project Settings > Services > Vivox (プロジェクト設定 > サービス > Vivox) に移動し、Test Mode (テストモード) とラベル付けされたボックスにチェックマークを入れます。
注
テストモードをオンにすると、クライアント上のプロジェクトのトークン署名キーがキャッシュされます。これはテスト目的でのみ使用してください。テストモードは、Vivox アクセストークンをゲームクライアントにベンディングできる安全なサーバーがプロビジョニングされた時点で、オフに切り替える必要があります。テストモードを無効にすると、トークン署名キーがプロジェクトから削除されます。
以下の例は、AuthenticationService パッケージを使用せず、かつ テストモード がオンになっている初期化の設定を示します。
async void InitializeAsync(){    await UnityServices.InitializeAsync();    await VivoxService.Instance.InitializeAsync();}

Vivox デベロッパーポータルの認証情報の使用

Vivox デベロッパーポータルの従来の認証情報がある場合は、それらの認証情報を 
InitializationOptions
を通じて 
VivoxService.Instance.InitializeAsync
 に指定します。これらの認証情報にテスト目的で署名キーを指定できます。
以下の例は、Vivox デベロッパーポータルの認証情報を使用した初期化の設定を示します。
async void InitializeAsync(){    InitializationOptions options = new InitalizationOptions();    // _key can be excluded from SetVivoxCredentials if an implementation of IVivoxTokenProvider has been provided to the SDK.    options.SetVivoxCredentials(_server, _domain, _issuer, _key);    await UnityServices.InitializeAsync(options);    await VivoxService.Instance.InitializeAsync();}
注
アプリケーションをリリースする前に、
options.SetVivoxCredentials(...)
の呼び出しから署名キー (上の例では "_key") を削除してください。また、これにより、Vivox アクセストークンをゲームクライアントにベンディングできるサーバーがプロビジョニングされていると見なすことができます。

サインインのライフサイクルの変更

Vivox サービスにサインインするための 
ILoginSession.BeginLogin
が 
VivoxService.Instance.LoginAsync(LoginOptions options = null)
 に置き換わっています。
LoginOptions
には以下のプロパティが含まれます。
  • DisplayName
  • テキスト音声変換を有効にする
  • 新しいチャンネルに参加するときに自動チャンネル伝送スワップを無効にする
  • サインイン時に現在のプレイヤーのブロック (クロスミュート) 対象の PlayerID のリストをキャッシュする
  • SDK が参加者の更新イベントを受け取る頻度を設定する
 async void LoginToVivoxAsync(List<string> blockedList, string displayName){    LoginOptions options = new LoginOptions();    options.DisplayName = displayName;    options.BlockedUserList = blockedList;    await VivoxService.Instance.LoginAsync(options);}
Vivox サービスからサインアウトするための 
ILoginSession.Logout()
が 
VivoxService.Instance.LogoutAsync
 に置き換わっています。
LoginSession.PropertyChanged
イベントに結び付けられた PropertyName が "State" のロジックと、
LoginState.LoggedIn
または 
LoginState.LoggedOut
のどちらかを、別の関数に移動します。以下の例に示すように、それぞれ 
VivoxService.Instance.LoggedIn
 と 
VivoxService.Instance.LoggedOut
 でトリガーされるように、サインインとサインアウトのロジックを分割します。
void Start(){    VivoxService.Instance.LoggedIn += OnUserLoggedIn;    VivoxService.Instance.LoggedOut += OnUserLoggedOut;}void OnDestroy(){    //Cleanup events if the GameObject is destroyed to prevent unexpected behavior.    VivoxService.Instance.LoggedIn -= OnUserLoggedIn;    VivoxService.Instance.LoggedOut -= OnUserLoggedOut;}void OnUserLoggedIn(){    Debug.Log("The user has successfully logged in");    // Other logic such as attempting a default channel join or changing the state of voice UIs to indicate the character is logged in can be done here.}void OnUserLoggedOut(){    Debug.Log("The user has logged out");    // The LoggedOut event will fire after a VivoxService.Instance.LogoutAsync call has been completed successfully    // or after an internet disruption has caused Automatic Connection Recovery to declare the attempted recovery a failure.}

プレイヤーのブロック

ILoginSession.SetCrossMutedCommunications
が 
VivoxServince.Instance.BlockPlayerAsync(string playerId)
 と 
VivoxService.Instance.UnblockPlayerAsync(string playerId)
 に置き換わり、入力として 
AccountId
の代わりに 
playerId
が必要になりました。

チャンネルのライフサイクルの変更

チャンネルへの参加と退出

ChannelSession.BeginConnect
に関連するすべてのロジックが、以下のメソッドに置き換わっています。
注
チャンネルのコミュニケーション機能に応じて、ChatCapability を Text、Audio、または TextandAudio に設定します。
ChannelSession.Disconnect()
が以下に置き換わっています。
ILoginSession.ChannelSessions
は 
VivoxService.Instance.ActiveChannels
 に置き換わっています。
VivoxService.Instance.ActiveChannels
は、現在アクティブなすべてのチャンネルがキー、すべてのチャンネルのリストの 
VivoxParticipants
が値となるディクショナリです。
以前は、ユーザーがそのチャンネルに接続されているかどうかを判断するのに、実装は 
AudioState
と 
TextState
に頼っていました。それら 2 つのプロパティの状態の変更を追跡するイベントを、
VivoxService.Instance.ChannelJoined
と 
VivoxService.Instance.ChannelLeft
に関連する関数に置き換えます。
VivoxService.Instance.ChannelJoined
 と 
VivoxService.Instance.ChannelLeft
 は、参加したチャンネルまたはイベントにバインドされたコールバックに残ったチャンネルの名前を提供します。
以下のコードサンプルは、これらの変更の例です。
void BindToChannelActions(){    //Connecting/Disconnecting channel actions can be done upon VivoxService.Instance.LoggedIn and LoggedOut events being fired, respectively,    //for basic lifecycle control    VivoxService.Instance.ChannelJoined += OnChannelJoined;    VivoxService.Instance.ChannelLeft += OnChannelLeft;}void UnbindChannelActions(){    VivoxService.Instance.ChannelJoined -= OnChannelJoined;    VivoxService.Instance.ChannelLeft -= OnChannelLeft;}void OnChannelJoined(string channelName){    //The channel with name channelName has been successfully joined, and any UI updates should be done for it    //Additionally, if multiple channels are being handled, keeping track of the channelName and knowing which channel is for which purpose should be done    //on the side of the implementation based on this event.}void OnChannelLeft(string channelName){    //The channel with name channelName has been successfully left, and any UI updates should be done for it    //This also means that the channelName can likely be safely lost, although if the channelName is specific and might be rejoined,    //it should be held on to by the implementation.}

チャンネルの伝送

デフォルトでは、チャンネルの伝送 (発話しているチャンネル) は直近で参加したチャンネルに切り替わります。その LoginOptions オブジェクトを入力として使用して 
VivoxService.Instance.LoginAsync
を呼び出す前に、
LoginOptions.DisableAutomaticChannelTransmissionSwap
を true に設定することでこれを無効にできます。
チャンネルの伝送は 
VivoxService.Instance.SetChannelTransmissionModeAsync(TransmissionMode transmissionMode, string channelName = null)
メソッドを使用して手動で変更できます。
この API を使用すると、メソッドの入力に基づいて、伝送するチャンネルを特定のチャンネル、すべてのチャンネルに指定するか、チャンネルに伝送しないかを設定できます。

チャンネル参加者の管理

ChannelParticipant は VivoxParticipant に置き換わっています。
アクティブな各チャンネルの VivoxParticipant のコレクションは、正しいキー (チャンネル名) が使用されている条件で、
VivoxService.Instance.ActiveChannels
インデックスから値を取得することでアクセスできます。
VivoxParticipant がチャンネルに追加またはチャンネルから削除されたタイミングを知るには、
VivoxService.Instance.ParticipantAddedToChannel
 と 
VivoxServince.Instance.ParticipantRemovedFromChannel
 を使用します。
イベントは、それらにバインドされた任意のコールバックに対する入力として、関連する VivoxParticipant を指定します。VivoxParticipant オブジェクトには、参加者の PlayerId、参加者が参加または退出したチャンネルの名前のほか、その参加者がローカルプレイヤーであるかどうか、またはその表示名などの重要な情報が含まれます。以下の例にこれらの種類のイベントを示します。
void BindToParticipantEvents(){    //These events can be connected at the same time as the channel events from the previous sections for convenience purposes    VivoxService.Instance.ParticipantAddedToChannel += OnParticipantAdded;    VivoxService.Instance.ParticipantRemovedFromChannel += OnParticipantRemoved;}void UnbindParticipantEvents(){    VivoxService.Instance.ParticipantAddedToChannel -= OnParticipantAdded;    VivoxService.Instance.ParticipantRemovedFromChannel -=OnParticipantRemoved;}void OnParticipantAdded(VivoxParticipant participant){    // Use VivoxParticipant to establish some UI element tied to that specific VivoxParticipant, which can then be used to control things such as muting    // volume, and blocking, along with UI that can track certain states - such as whether the player is currently muted or is currently speaking.}void OnParticipantRemoved(VivoxParticipant participant){    // At this point, any UI created to display information about this VivoxParticipant can be safely disposed of.}

VivoxParticipant オブジェクト

VivoxParticipant
 には、以下のような参加者の現在の状態に関する情報が含まれます。
  • VivoxParticipant.IsSelf
    。参加者がローカルプレイヤーであるかどうかを示します。
  • VivoxParticipant.SpeechDetected
    。参加者のオーディオエネルギーが Vivox SDK によって音声と見なされるしきい値を超えているかどうかを示します。
また、VivoxParticipant には以下のイベントがあります。
  • ParticipantMuteStateChanged
  • ParticipantSpeechDetected
  • ParticipantAudioEnergyChanged
これらのイベントを使用して、機能するボリュームユニット (VU) メーターや音声インジケーターを作成できます。これらのイベントを、各参加者の個別の UI レベルでつなぎます。
注
それらが一部を占めるオブジェクトには、UI を簡単に更新するために、表現される参加者への参照が必要です。
以下のサンプルクラスは、ChatChannelSample 内の RosterItem の簡略化されたバージョンです。
public class RosterItem : MonoBehaviour{    public VivoxParticipant Participant;    public Text PlayerNameText;    public void SetupRosterItem(VivoxParticipant participant)    {        Participant = participant;        PlayerNameText.text = Participant.DisplayName;        Participant.ParticipantMuteStateChanged += OnMuteStateChanged;        Participant.ParticipantSpeechDetected += OnSpeechDetected;    }    void OnMuteStateChanged()    {        if(Participant.IsMuted)        {            //Participant has been muted        }        else        {            //Participant has been unmuted        }    }    void OnSpeechDetected()    {        //Participant AudioEnergy has exceeded the value required to be considered speech    }}

チャンネル参加者のミュート

VivoxParticipant.MutePlayerLocally()
 と 
VivoxParticipant.UnmutePlayerLocally()
 を使用して、チャンネル内の特定の参加者をミュート/ミュート解除できます。
注
これら VivoxParticipant のミュート/ミュート解除 API は、ローカルプレイヤーには影響しません。

オーディオデバイスの管理

Client オブジェクトを利用してデバイスを管理できなくなりました。ミュート、音量変更、アクティブデバイスの切り替えなどのデバイスの調整は、
VivoxService.Instance
を使用して行えるようになりました。

ローカルプレイヤーのミュート

自分をローカルでミュートする方法が、IAudioDevice オブジェクトで API を使用して行うのではなく、関数 
VivoxService.Instance.MuteInputDevice()
 と 
VivoxService.Instance.UnmuteInputDevice()
 を使用するか、チャンネルの伝送を none に切り替える方法に変更されました。これらの API は、ローカルユーザーの入力デバイスをミュートまたはミュート解除します。

入出力デバイスの音量調整

VivoxService.Instance.SetInputDeviceVolume(int value)
 と 
VivoxService.Instance.SetOutputDeviceVolume(int value)
 を使用してデバイスの音量を調整できるようになりました。

アクティブな入出力デバイスの変更

VivoxService.Instance.SetActiveOutputDeviceAsync(VivoxOutputDevice device)
 または 
VivoxService.Instance.SetActiveInputDeviceAsync(VivoxInputDevice device)
 のいずれかを呼び出すことで、アクティブな入出力デバイスを調整できます。
プロパティ 
VivoxService.Instance.AvailableInputDevices
 と 
VivoxService.Instance.AvailableOututDevices
 にアクセスすることで、
VivoxInputDevices
と 
VivoxOutputDevices
のコレクションを取得できます。
以下の例は、Vivox SDK オーディオデバイス API を使用して、アクティブな入力デバイスを変更する機能を提供する、入力デバイスのドロップダウンリストを入力する方法を示します。
using System.Linq;using Unity.Services.Vivox;using UnityEngine;using UnityEngine.UI;public class AudioDeviceSettings : MonoBehaviour{    public Dropdown InputDeviceDropdown;    private void Start()    {        VivoxService.Instance.AvailableInputDevicesChanged += RefreshInputDeviceList;        InputDeviceDropdown.onValueChanged.AddListener((i) =>        {            InputDeviceValueChanged(i);        });    }    void OnEnable()    {        RefreshInputDeviceList();    }    void OnDestroy()    {        // Unbind all UI actions        InputDeviceDropdown.onValueChanged.RemoveAllListeners();        VivoxService.Instance.AvailableInputDevicesChanged -= RefreshInputDeviceList;    }    private void RefreshInputDeviceList()    {        InputDeviceDropdown.Hide();        InputDeviceDropdown.ClearOptions();        InputDeviceDropdown.options.AddRange(VivoxService.Instance.AvailableInputDevices.Select(v => new Dropdown.OptionData() { text = v.DeviceName }));        InputDeviceDropdown.SetValueWithoutNotify(InputDeviceDropdown.options.FindIndex(option => option.text == VivoxService.Instance.ActiveInputDevice.DeviceName));        InputDeviceDropdown.RefreshShownValue();    }    void InputDeviceValueChanged(int index)    {        VivoxService.Instance.SetActiveInputDeviceAsync(VivoxService.Instance.AvailableInputDevices.Where(device => device.DeviceName == InputDeviceDropdown.options[index].text).First());    }}
注
これは ChatChannelSample のサンプルで使用されている AudioDeviceSettings クラスの簡略化されたバージョンで、アクティブな入出力デバイスを変更する方法、入出力デバイスの音量を調整する方法、デバイスリストの変更に反応する方法を示します。