Skip to main content
Version: 1.0.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.

caution

Vivox is available on the originally existing Vivox Developer Portal and Unity Gaming Services, which appeared in October 2021. The current Vivox wrapper is compatible with the Vivox Developer Portal. It is not compatible with Unity Gaming Services. We will consider supporting Unity Gaming Services in the future.

Specification​

The specifications of the Vivox wrapper are as follows.

  • You can use Vivox features.
  • You can add processing triggered by Vivox client state.

Architecture​

classDiagram VivoxClient --> VivoxAppConfig VivoxClient ..> VivoxAuthConfig VivoxClient ..> VivoxChannelConfig VivoxChannelConfig --> ChatType IDisposable <|.. 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 +VivoxClient(appConfig) +LoginAsync(authConfig) void +Logout() void +ConnectAsync(channelConfig) void +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 +VivoxAppConfig(apiEndPoint, domain, issuer, secretKey) } class VivoxAuthConfig { +DisplayName string +AccountName string +TokenExpirationDuration TimeSpan +Timeout TimeSpan +VivoxAuthConfig(displayName, accountName, tokenExpirationDuration, timeout) } class ChatType { <<enumeration>> TextAndAudio TextOnly AudioOnly } class VivoxChannelConfig { +ChannelName string +ChatType ChatType +ChannelType ChannelType +Properties Channel3DProperties +TransmissionSwitch bool +TokenExpirationDuration TimeSpan +Timeout TimeSpan VivoxChannelConfig(channelName, chatType, channelType, transmissionSwitch, tokenExpirationDuration, timeout) } class IDisposable { <<system>> }

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 the application to which the client will connect has been created in Vivox Developer Portal.

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);
}

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);

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)