Vivox Unity SDK 16.0.0 升级指南
Upgrade from previous Vivox versions to version 16.0.0.
阅读时间9 分钟最后更新于 1 个月前
注意
如果要从 Vivox Unity 版本 15.1.x 或更低版本进行升级，请遵循本指南。
- SDK 初始化
- 登录/注销
- 屏蔽玩家
- 连接到频道
- 频道参与者管理
- 音频设备管理
- 设置活动设备
- 设置设备增益/音量
- 设备静音
SDK 设置和初始化
将using VivoxUnity;using Unity.Services.Vivox;使用 Authentication
注意
如果您使用的是 Vivox 开发者门户中的凭据，请跳过此部分并跳转到“Vivox 开发者门户凭据”部分。
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.InstanceAuthenticationService注意
启用测试模式会在客户端上缓存项目的令牌签名密钥，只能用于测试目的。一旦配置了可以向游戏客户端供应 Vivox 访问令牌的安全服务器，就应关闭测试模式。禁用测试模式将从项目中移除令牌签名密钥。
async void InitializeAsync(){ await UnityServices.InitializeAsync(); await VivoxService.Instance.InitializeAsync();}
使用 Vivox 开发者门户凭据
如果您有旧版 Vivox 开发者门户凭据，请通过InitializationOptionsVivoxService.Instance.InitializeAsyncasync 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();}
注意
在发布应用程序之前，请从 调用中移除签名密钥（上述示例中的“_key”）。此处还假设已经预配了能够向游戏客户端供应 Vivox 访问令牌的服务器。
options.SetVivoxCredentials(...)登录生命周期更改
ILoginSession.BeginLoginVivoxService.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);}
ILoginSession.Logout()VivoxService.Instance.LogoutAsyncLoginSession.PropertyChangedLoginState.LoggedInLoginState.LoggedOutVivoxService.Instance.LoggedInVivoxService.Instance.LoggedOutvoid 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.SetCrossMutedCommunicationsVivoxServince.Instance.BlockPlayerAsync(string playerId)VivoxService.Instance.UnblockPlayerAsync(string playerId)playerIdAccountId频道生命周期更改
加入和离开频道
所有与ChannelSession.BeginConnectJoinGroupChannelAsync(string channelName, ChatCapability chatCapability, ChannelOptions channelOptions = null);JoinPositionalChannelAsync(string channelName, ChatCapability chatCapability, Channel3DProperties positionalChannelProperties, ChannelOptions channelOptions = null);JoinEchoChannelAsync(string channelName, ChatCapability chatCapability, ChannelOptions channelOptions = null);
注意
根据频道通信能力，将 ChatCapability 设置为 Text、Audio 或 TextandAudio。
ChannelSession.Disconnect()- ，用于离开特定频道。
VivoxService.Instance.LeaveChannelAsync(string channelName) - ，用于离开所有活动频道。如果任何时候只加入一个频道，我们建议使用此方法。
VivoxService.Instance.LeaveAllChannelsAsync()
ILoginSession.ChannelSessionsVivoxService.Instance.ActiveChannelsVivoxService.Instance.ActiveChannelsVivoxParticipantsAudioStateTextStateVivoxService.Instance.ChannelJoinedVivoxService.Instance.ChannelLeftVivoxService.Instance.ChannelJoinedVivoxService.Instance.ChannelLeftvoid 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.LoginAsyncLoginOptions.DisableAutomaticChannelTransmissionSwapVivoxService.Instance.SetChannelTransmissionModeAsync(TransmissionMode transmissionMode, string channelName = null)频道参与者管理
VivoxParticipant 已取代 ChannelParticipant。 如果使用了正确的键（频道名称），可以通过从VivoxService.Instance.ActiveChannelsVivoxService.Instance.ParticipantAddedToChannelVivoxServince.Instance.ParticipantRemovedFromChannelvoid 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 - ，指明参与者的音频能量是否超过了 Vivox SDK 将音频视为语音的阈值。
VivoxParticipant.SpeechDetected
ParticipantMuteStateChangedParticipantSpeechDetectedParticipantAudioEnergyChanged
注意
这些事件所属的对象应具有对所表示的参与者的引用，以便轻松更新 UI。
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将本地玩家静音
本地玩家静音已更改为使用VivoxService.Instance.MuteInputDevice()VivoxService.Instance.UnmuteInputDevice()调节输入/输出设备音量
现在可以使用VivoxService.Instance.SetInputDeviceVolume(int value)VivoxService.Instance.SetOutputDeviceVolume(int value)更改活动输入/输出设备
可以通过调用VivoxService.Instance.SetActiveOutputDeviceAsync(VivoxOutputDevice device)VivoxService.Instance.SetActiveInputDeviceAsync(VivoxInputDevice device)VivoxService.Instance.AvailableInputDevicesVivoxService.Instance.AvailableOututDevicesVivoxInputDevicesVivoxOutputDevicesusing 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 类的简化版本，演示了如何更改活动输入/输出设备、调节输入/输出设备音量以及对设备列表更改做出反应。