Skip to main content
Version: 1.3.0

Chat using Vivox

What for?​

We provide a wrapper that makes Vivox easier to use in applications.

We will call this feature, which wraps Vivox, the Vivox wrapper.

The implementation of login/logout or connecting/disconnecting to a channel using Vivox's API is similar in any application. The Vivox wrapper provides features that are common to such implementations when using Vivox.

The goal is to make Vivox introduction smooth by using the Vivox wrapper in your applications.

caution

The Vivox wrapper makes Vivox easier to use, but it does not mean that you only need to know the Vivox wrapper to realize voice/text chat without knowing Vivox. The Vivox wrapper compensates for the difficulties and lack of features when using Vivox as it is, but transfers the voice/text chat process to Vivox. Therefore, to use the Vivox wrapper, it is assumed that you know Vivox. If you do not know Vivox, please refer to Learning to learn about Vivox. This guide assumes you know Vivox.

Specification​

The specifications of the Vivox wrapper are as follows.

  • You can use Vivox features.
  • Reconnect when communication is disconnected.
  • You can add processing triggered by Vivox client state.

Architecture​

classDiagram VivoxClient --> VivoxAppConfig VivoxClient ..> VivoxAuthConfig VivoxClient ..> VivoxChannelConfig VivoxClient ..> VivoxConnectionException VivoxChannelConfig --> ChatType DisposableBase <|-- VivoxClient class VivoxClient { +Client Client +LoginSession ILoginSession +OnLoggedIn IObservable +OnLoggedOut IObservable +OnRecoveryStateChanged IObservable +OnChannelSessionAdded IObservable +OnChannelSessionRemoved IObservable +OnUserConnected IObservable +OnUserDisconnected IObservable +OnTextMessageReceived IObservable +OnAudioEnergyChanged IObservable +OnConnectRetrying IObservable +OnConnectRetried IObservable +VivoxClient(appConfig) +LoginAsync(authConfig, retryCancellationToken) void +Logout() void +ConnectAsync(channelConfig, connectCancellationToken) ChannelId +Disconnect(channelId) void +DisconnectAllChannels() void +SendTextMessage(message, channelIds, language, applicationStanzaNamespace, applicationStanzaBody) void +SendTextMessage(message, channelId, language, applicationStanzaNamespace, applicationStanzaBody) void +SetTransmissionMode(transmissionMode, channelId) void +GetAudioInputDevicesAsync() IAudioDevices +SetAudioInputDeviceAsync(device) void +GetAudioOutputDevicesAsync() IAudioDevices +SetAudioOutputDeviceAsync(device) void } class VivoxAppConfig { +ApiEndPoint string +Domain string +Issuer string +SecretKey string +VivoxConfig VivoxConfig +LoginRetryStrategy IRetryStrategy +VivoxAppConfig(apiEndPoint, domain, issuer, secretKey, vivoxConfig, loginRetryStrategy) } class VivoxAuthConfig { +DisplayName string +AccountName string +TokenExpirationDuration TimeSpan +VivoxAuthConfig(displayName, accountName, tokenExpirationDuration) } class ChatType { <<enumeration>> TextAndAudio TextOnly AudioOnly } class VivoxChannelConfig { +ChannelName string +ChatType ChatType +ChannelType ChannelType +Properties Channel3DProperties +TransmissionSwitch bool +TokenExpirationDuration TimeSpan +VivoxChannelConfig(channelName, chatType, channelType, transmissionSwitch, tokenExpirationDuration) } class VivoxConnectionException { +VivoxConnectionException(message) +VivoxConnectionException(message, innerException) } class DisposableBase { <<extreal>> }

Installation​

Package​

https://github.com/extreal-dev/Extreal.Integration.Chat.Vivox.git

Dependencies​

The Vivox wrapper uses the following packages.

Please refer to Release for the correspondence between module version and each package version.

Settings​

VivoxClient is initialized.

It is assumed that you have created a project with Vivox set up in Unity Cloud to which the client will connect.

To initialize VivoxClient, VivoxAppConfig, which holds the connection information to Vivox, is required. As an example, we will show how to set the connection information to Vivox with a ScriptableObject. Create a ScriptableObject that generates VivoxAppConfig and set the connection information to Vivox in the inspector.

[CreateAssetMenu(
    menuName = "Config/" + nameof(ChatConfig),
    fileName = nameof(ChatConfig))]
public class ChatConfig : ScriptableObject
{
    [SerializeField] private string apiEndPoint;
    [SerializeField] private string domain;
    [SerializeField] private string issuer;
    [SerializeField] private string secretKey;

    public VivoxAppConfig ToVivoxAppConfig()
        => new VivoxAppConfig(apiEndPoint, domain, issuer, secretKey);
}
info

Additionally to the connection information, VivoxAppConfig contains the following settings.

Initialize VivoxClient with VContainer.

public class ChatControlScope : LifetimeScope
{
    [SerializeField] private ChatConfig chatConfig;

    protected override void Configure(IContainerBuilder builder)
    {
        builder.RegisterComponent(chatConfig.ToVivoxAppConfig());
        builder.Register<VivoxClient>(Lifetime.Singleton);
    }
}

Usage​

Use Vivox features​

Vivox features are provided by VivoxClient. For features that are not provided by VivoxClient, please obtain the Client or ILoginSession provided by Vivox from VivoxClient and implement them.

var client = vivoxClient.Client;
var loginSession = vivoxClient.LoginSession;

Here are some basic instructions for using VivoxClient.

To conduct voice/text chat, you must first log in to the Vivox application. Login is done using LoginAsync in VivoxClient.

var vivoxAuthConfig = new VivoxAuthConfig("Guest");
vivoxClient.LoginAsync(vivoxAuthConfig).Forget();

Logout is done using Logout in VivoxClient.

vivoxClient.Logout();

You can use VivoxClient's ConnectAsync to enter the channel.

var vivoxChannelConfig = new VivoxChannelConfig("GuestChannel");
vivoxClient.ConnectAsync(vivoxChannelConfig).Forget();

VivoxChannelConfig enables voice and text chat by default. If you want to restrict to voice chat only or text chat only, specify ChatType. An example of restricting to voice chat only is as follows.

var vivoxChannelConfig = new VivoxChannelConfig("GuestChannel", ChatType.AudioOnly);

If you want to exit from all channels at the point of exiting the space, such as when allowing voice or text chat only within a space, use DisconnectAllChannels in VivoxClient.

vivoxClient.DisconnectAllChannels();

You can use Disconnect in VivoxClient to leave a specific channel, such as when a group chat feature is provided.

vivoxClient.Disconnect(channelId);

You can use SendTextMessage in VivoxClient to send text chat messages.

vivoxClient.SendTextMessage(message, channelId);

Text chat messages are received via OnTextMessageReceived, an event notification published by VivoxClient.

vivoxClient.OnTextMessageReceived
    .Subscribe(message => /* do something with message */)
    .AddTo(disposables);

Reconnect when communication is disconnected​

VivoxClient uses the retry processing provided by Common to reconnect when communication is disconnected. The following description assumes that you are familiar with the retry processing, so if you have not checked the retry processing, please check the retry processing first.

VivoxClient does not reconnect by default. If a retry strategy is specified in VivoxAppConfig, it will reconnect.

new VivoxAppConfig(apiEndPoint, domain, issuer, secretKey, loginRetryStrategy: new CountingRetryStrategy());

The reconnection processing handled by VivoxClient is as follows.

  • When to run reconnection
    • If login failed
    • If Vivox Unity SDK automatic connection recovery failed
      • If communication is lost after login, Vivox Unity SDK will try to recover the connection automatically for 30 seconds.
      • If the automatic connection recovery failed, the client will be logged out by Vivox Unity SDK.
  • Reconnection processing details
    • If login failed
      • Repeat login according to retry strategy.
    • If Vivox Unity SDK automatic connection recovery failed
      • Repeat login according to retry strategy.
      • If the login succeeds, it connects to all channels to which it was connected before disconnection.

VivoxClient reconnection only covers the login processing, because if automatic connection recovery fails, the client is logged out and must start over from login.

Use event notifications if you want to run processing based on the status of retry processing.

Add a processing triggered by Vivox client state​

VivoxClient has the following event notifications.

  • OnLoggedIn
    • Timing: Immediately after login
    • Type: IObservable
    • Parameters: None
  • OnLoggedOut
    • Timing: Immediately after logout
    • Type: IObservable
    • Parameters: None
  • OnRecoveryStateChanged
    • Timing: Immediately after the recovery state changes on unexpected network disconnection
    • Type: IObservable
    • Parameters: Recovery state
  • OnChannelSessionAdded
    • Timing: Immediately after a channel is added
    • Type: IObservable
    • Parameters: ID of the added channel
  • OnChannelSessionRemoved
    • Timing: Immediately after a channel is removed
    • Type: IObservable
    • Parameters: ID of the removed channel
  • OnUserConnected
    • Timing: Immediately after a participant connects to the channel.
      • The user who originated the event is also notified of this event.
    • Type: IObservable
    • Parameters: Participant who connected to the channel.
      • IParticipant
      • The IsSelf property of IParticipant determines if the participant is the user itself who entered the channel.
  • OnUserDisconnected
    • Timing: Immediately after a participant disconnects from the channel.
      • The user who originated the event is also notified of this event.
    • Type: IObservable
    • Parameters: Participant who disconnected from the room
      • IParticipant
      • The IsSelf property of IParticipant determines if the participant is the user itself who left the channel.
  • OnTextMessageReceived
    • Timing: Immediately after a message is received on the channel
    • Type: IObservable
    • Parameters: Incoming message
  • OnAudioEnergyChanged
    • Timing: Immediately after a change in the participant's audio loudness
    • Type: IObservable
    • Parameters: Participant and audio volume (tuple)
  • OnConnectRetrying
    • Timing：Just before retrying the connection
    • Type：IObservable
    • Parameters：Retry count
      • The first time is 1 and the second time is 2.
      • 1 means the start of retry strategy running.
  • OnConnectRetried
    • Timing：Immediately after connection retry is finished
      • If the retry is canceled, it will not be notified.
    • Type：IObservable
    • Parameters：Retry result
      • true: If the retry strategy is run and the retry is successful
      • false: If the retry strategy is run and the retry is not successful finally