Chat using Vivox

What for?

Vivoxをアプリケーションで使いやすくするラッパーを提供します。

Vivoxをラップしているこの機能をVivoxラッパーと呼ぶことにします。

VivoxのAPIを使ったログイン/ログアウトやチャンネルへの接続/切断といった実装はどのようなアプリケーションでも同じような実装になります。 VivoxラッパーはそのようなVivoxを使う場合に共通する実装を機能として提供します。

あなたのアプリケーションでVivoxラッパーを使うことでVivoxの導入がスムーズになることを目指しています。

注意

VivoxラッパーはVivoxを使いやすくしますが、Vivoxを知らなくてもVivoxラッパーだけ知っていればボイス/テキストチャットを実現できるわけではありません。 VivoxラッパーはVivoxをそのまま使う場合に使いにくい点や足りない機能を補いますが、ボイス/テキストチャットの処理はVivoxに移譲します。 そのため、Vivoxラッパーを使うにはVivoxを知っていることが前提です。 Vivoxを知らない場合はLearningを参照してVivoxについて学習してください。 このガイドはVivoxを知っている前提で説明しています。

Specification

Vivoxラッパーの仕様は次の通りです。

• Vivoxの機能を使用できます。
• 通信が切断されたときに再接続できます。
• Vivoxのクライアント状態をトリガーに処理を追加できます。

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

Vivoxラッパーは次のパッケージを使います。

• Extreal.Core.Logging
• Extreal.Core.Common
• Vivox Unity SDK
• UniTask
• UniRx

モジュールバージョンと各パッケージバージョンの対応はReleaseを参照ください。

Settings

VivoxClientを初期化します。

クライアントからの接続先となる、VivoxがセットアップされたプロジェクトがUnity Cloudで作成されているものとします。

VivoxClientの初期化にはVivoxへの接続情報を保持するVivoxAppConfigが必要です。 今回は一例としてScriptableObjectでVivoxへの接続情報を設定する方法を紹介します。 VivoxAppConfigを生成するScriptableObjectを作成し、インスペクタでVivoxへの接続情報を設定します。

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

備考

VivoxAppConfigには接続情報の他に次の設定を行えます。

• VivoxConfig
• 通信切断時の再接続で使うリトライ戦略
  • 詳細は通信切断時に再接続するを参照してください。

VContainerを使ってVivoxClientを初期化します。

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

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

Usage

Vivoxの機能を使用する

Vivoxの機能はVivoxClientが提供します。 VivoxClientが提供していない機能はVivoxClientからVivoxが提供するClientやILoginSessionを取得して実装してください。

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

ここではVivoxClientの基本的な使い方をいくつか紹介します。

ボイス/テキストチャットを行うにはまずVivoxのアプリケーションにログインが必要です。 ログインはVivoxClientのLoginAsyncを使います。

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

ログアウトはVivoxClientのLogoutを使います。

vivoxClient.Logout();

チャンネルへの入室はVivoxClientのConnectAsyncを使います。

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

VivoxChannelConfigはデフォルトでボイスチャットとテキストチャットを有効にします。 ボイスチャットのみ、テキストチャットのみに制限したい場合はChatTypeを指定します。 ボイスチャットのみに制限する場合の例は次の通りです。

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

空間内でのみボイスチャットやテキストチャットをできるようにする場合など、空間からの退室時点で全てのチャンネルから退室する場合はVivoxClientのDisconnectAllChannelsを使います。

vivoxClient.DisconnectAllChannels();

グループチャット機能を提供している場合など、特定のチャンネルから退室する場合はVivoxClientのDisconnectを使います。

vivoxClient.Disconnect(channelId);

テキストチャットのメッセージ送信はVivoxClientのSendTextMessageを使います。

vivoxClient.SendTextMessage(message, channelId);

テキストチャットのメッセージ受信はVivoxClientが発行するイベント通知のOnTextMessageReceivedを使用します。

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

通信が切断されたときに再接続する

VivoxClientはCommonが提供するリトライ処理を使って通信切断時の再接続を実現しています。 リトライ処理を知っている前提で以降の説明をするため、リトライ処理を確認していない方は先にリトライ処理を確認してください。

VivoxClientはデフォルトで再接続を行いません。 VivoxAppConfigにリトライ戦略を指定すると再接続を行います。

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

VivoxClientが行う再接続の処理内容は次の通りです。

• 再接続を実行するタイミング
  • ログインが失敗した場合
  • Vivox Unity SDKの自動接続回復が失敗した場合
    • ログイン後に通信が切断されるとVivox Unity SDKは自動接続回復を30秒間試みます。
    • 自動接続回復が失敗した場合はVivox Unity SDKによりクライアントはログアウトされます。
• 再接続の処理内容
  • ログインが失敗した場合
    • リトライ戦略に応じてログインを繰り返します。
  • Vivox Unity SDKの自動接続回復が失敗した場合
    • リトライ戦略に応じてログインを繰り返します。
    • ログインが成功した場合は切断前に接続していた全てのチャンネルに接続します。

自動接続回復が失敗した場合はログアウト状態となり、ログインからやり直す必要があるため、VivoxClientの再接続はログイン処理のみを対象としています。

リトライ処理の状況に応じて処理を実行したい場合はイベント通知を使用してください。

Vivoxのクライアント状態をトリガーに処理を追加する

VivoxClientは次のイベント通知を設けています。

• OnLoggedIn
  • タイミング：ログインした直後
  • タイプ：IObservable
  • パラメータ：なし
• OnLoggedOut
  • タイミング：ログアウトした直後
  • タイプ：IObservable
  • パラメータ：なし
• OnRecoveryStateChanged
  • タイミング：予期しないネットワーク切断時のリカバリ状態が変化した直後
  • タイプ：IObservable
  • パラメータ：リカバリ状態
    • ConnectionRecoveryState
• OnChannelSessionAdded
  • タイミング：チャンネルが追加された直後
  • タイプ：IObservable
  • パラメータ：追加されたチャンネルのID
    • ChannelId
• OnChannelSessionRemoved
  • タイミング：チャンネルが削除された直後
  • タイプ：IObservable
  • パラメータ：削除されたチャンネルのID
    • ChannelId
• OnUserConnected
  • タイミング：チャンネルに参加者が入室した直後
    • イベント発生元になったユーザーにもこのイベントが通知されます。
  • タイプ：IObservable
  • パラメータ：入室した参加者
    • IParticipant
    • 参加者がチャンネルに入室したユーザー自身かどうかはIParticipantのIsSelfプロパティで判定します。
• OnUserDisconnected
  • タイミング：チャンネルから参加者が退室した直後
    • イベント発生元になったユーザーにもこのイベントが通知されます。
  • タイプ：IObservable
  • パラメータ：退室した参加者
    • IParticipant
    • 参加者がチャンネルから退室したユーザー自身かどうかはIParticipantのIsSelfプロパティで判定します。
• OnTextMessageReceived
  • タイミング：チャンネルにメッセージが着信した直後
  • タイプ：IObservable
  • パラメータ：着信したメッセージ
    • IChannelTextMessage
• OnAudioEnergyChanged
  • タイミング：参加者の音声の大きさに変化があった直後
  • タイプ：IObservable
  • パラメータ：参加者と音声の大きさ（タプル）
    • IParticipant
    • AudioEnergy
• OnConnectRetrying
  • タイミング：接続をリトライする直前
  • タイプ：IObservable
  • パラメータ：リトライ回数
    • 1回目は1、2回目は2となります。
    • 1はリトライ戦略の実行開始を意味します。
• OnConnectRetried
  • タイミング：接続のリトライが終了した直後
    • リトライがキャンセルされた場合は通知されません。
  • タイプ：IObservable
  • パラメータ：リトライ結果
    • true：リトライ戦略を実行してリトライが成功した場合
    • false：リトライ戦略を実行して最終的にリトライが成功しなかった場合