> For the complete documentation index, see [llms.txt](https://docs.digitalhumans.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalhumans.jp/dev/hosted-experience/hosted-experience-configuration-options.md).
# 設定オプション
## Constructor
Uneeqクラスは、以下のコンストラクタでインスタンス化されます。
```jsx
constructor(options);
```
**パラメータ**
* `options` (Object): Uneeqインスタンスを初期化するための設定オプション。
## Options
Uneeqクラスを初期化する際に渡すことができる設定オプション。
### コア必須
#### connectionUrl
（必須）接続エンドポイントの文字列URL。
接続するリージョンに対応する、ホステッドエクスペリエンスのconnectionUrlを設定しているか確認してください。
| リージョン | connectionUrl |
| -------------------------------- | ---------------------------------- |
| USリージョン（Global region） | `https://api.uneeq.io/` |
| エンタープライズリージョン（Enterprise region） | `https://api.enterprise.uneeq.io/` |
| ヨーロッパリージョン（Europe Region） | `https://api-eu.uneeq.io` |
```jsx
# USリージョンのお客様
connectionUrl: "https://api.uneeq.io"
# エンタープライズリージョンのお客様
connectionUrl: "https://api.enterprise.uneeq.io"
# ヨーロッパリージョンのお客様
connectionUrl: "https://api-eu.uneeq.io"
```
#### personaId
（必須）開始するデジタルヒューマンのID。この値は、DIP のデジタルヒューマン（ペルソナ）ページからコピーできます。
```jsx
personaId: "323d5c36-e01c-4c0d-9ef5-2c00de4aa166"
```
#### resolution
（オプション）セッション映像の解像度を指定する文字列。省略するとペルソナに設定された解像度が使用されます。ペルソナの設定上限を超える値を指定した場合は、自動的にペルソナの最大値に制限されます。APIキー方式でセッションを作成する際にバックエンドから指定することもできます。
**値:** `"480p"` / `"720p"` / `"1080p"` / `"1440p"` / `"4k"`
```jsx
resolution: "1080p"
```
### セッション管理
#### allowResumeSession
（オプション）既存のセッションがある場合に、前回のセッションを自動的に再開するかどうかを示すブール値です。`true`に設定すると、システムは保存されたセッションデータに基づいて、24時間以内の最後のアクティブなセッションの復元を試みます。セッションデータはpersonaIdごとに保存されるため、各ペルソナは独自のセッション履歴を保持します。falseまたは省略された場合、常に新しいセッションが作成されます。デフォルト値は`false`です。
```jsx
allowResumeSession: true
```
#### autoStart
（オプション）セッションを自動的に開始するかどうかを示すブール値。このオプションを設定すると、ページの読み込み時に`startSession()`を呼び出すことなくセッションが自動的に開始されます。デフォルト値は`false`です。
```jsx
autoStart: false
```
#### initLoadHandler
（オプション）デジタルヒューマンフレームをページ読み込み時に初期化するかどうかを示す真偽値。この値が`true`の場合、ページ読み込み時に（ページロードイベントハンドラーを通じて）デジタルヒューマンフレームが初期化されます。この値が`false`の場合、デジタルヒューマンフレームはページ読み込み時に追加されません。
この値を`false`に設定した場合、デジタルヒューマンフレームをロードしたいときに`uneeq.init()`を自分で呼び出す必要があります。これは、特定のデータの取得やアクションの実行を待つため、デジタルヒューマンスクリプトの読み込みを遅延または防止したい場合に望ましい設定です。
デフォルト値は`true`です。
```jsx
initLoadHandler: false
```
#### welcomePrompt
（オプション）セッション開始時に会話（LLM）システムに送信されるプロンプト。デフォルト値は"`Hello`"です。
注: この値は、セッション開始時にユーザーに話されるものではなく、ユーザーから言語モデルに送信されるプロンプト（質問）です。
```jsx
welcomePrompt: "こんにちは、私を歓迎し、何か手助けが必要かどうかを確認してください"
```
### 表示・レイアウト
#### layoutMode
（オプション）レイアウトモードを定義する文字列。
**オーバーレイ:**
* 値: `overlay`
* デジタルヒューマンをユーザーの画面の右下に小さくオーバーレイ表示します。このビューは、ユーザーが閲覧中のウェブサイトを引き続き見る必要がある場合に最適です。
**フルスクリーン:**
* 値: `fullScreen`
* デジタルヒューマンをユーザーの画面全体を覆うビューで表示します。ユーザーはホスティングウェブサイトを閲覧または操作することができません。このビューは、没入型のデジタルヒューマン体験に最適です。
**コンテインド:**
* デジタルヒューマンを、クライアントがページに追加し制御するHTMLの`div`コンテナ要素内に表示します。このレイアウトモードを使用するには、ページ上に`id`が`uneeqContainedLayout`の`div`要素が必要です。デジタルヒューマンはこのコンテナ内でレンダリングされ、クライアントはコンテナを再スタイルすることができます。たとえば、クライアントはコンテナの移動、サイズ変更、表示非表示をコンテキストに応じて行えます。
注意: コンテナ要素はセッションを終了せずにDOMから削除することはできません。
```jsx
layoutMode: "overlay"
```
#### displayCallToAction
（オプション）コールトゥアクションを表示するかどうかを示す真偽値。デフォルト値はtrueです。
```jsx
displayCallToAction: false
```
#### ctaThumbnailUrl
（オプション）コールトゥアクションのサムネイル画像を上書きするためのURL文字列。提供される画像は140pxの正方形の.jpg、.png、または.gif形式である必要があります。
```jsx
ctaThumbnailUrl: "https://cdn.your-domain.com/image1"
```
#### renderContent
（オプション）デジタルヒューマンフレーム内にHTMLコンテンツをレンダリングするかどうかを示すブール値。このオプションを`false`に設定した場合、クライアント実装でHTMLコンテンツメッセージを受け取り、独自のビュー内でコンテンツをレンダリングすることができます。
```jsx
renderContent: false
```
#### containedElementIdName
（オプション）`layoutMode: "contained"` を使用する場合に、デジタルヒューマンをレンダリングする `div` 要素の `id` を指定する文字列。デフォルト値は `"uneeqContainedLayout"` です。
```jsx
// HTML 側に対応する div を用意する
//
containedElementIdName: "myDigitalHuman"
```
#### containedAutoLayout
（オプション）`layoutMode: "contained"` を使用する場合に、コンテナ要素に合わせてレイアウトを自動調整するかどうかを示すブール値。デフォルト値は `false` です。
```jsx
containedAutoLayout: true
```
#### mobileViewWidthBreakpoint
（オプション）モバイルレイアウトに切り替えるブレークポイントをピクセル単位で指定する数値。ブラウザのビューポート幅がこの値以下になるとモバイルレイアウトが適用されます。モバイル表示を無効化したい場合は `1` など小さい値を設定してください。デフォルト値は `900` です。
```jsx
mobileViewWidthBreakpoint: 900
```
### カメラ制御
#### cameraAnchorHorizontal
（オプション）セッション開始時のカメラアンカーの初期水平位置を定義する文字列。
**値:**
* `left`
* `right`
* `center`
```jsx
cameraAnchorHorizontal: "right"
```
```jsx
cameraAnchorHorizontal: "left"
```
```jsx
cameraAnchorHorizontal: "right"
```
```jsx
cameraAnchorHorizontal: "center"
```
#### cameraAnchorDistance
(任意) セッション開始時のカメラアンカーの初期距離（ズーム）を定義する文字列。
**値:**
* `close_up`
* `loose_close_up`
* `tight_medium_shot`
* `medium_shot`
* `medium_full_shot`
* `full_shot`
```jsx
cameraAnchorDistance: "close_up"
```
```jsx
cameraAnchorDistance: "close_up"
```
```jsx
cameraAnchorDistance: "loose_close_up"
```
```jsx
cameraAnchorDistance: "tight_medium_shot"
```
```jsx
cameraAnchorDistance: "medium_shot"
```
```jsx
cameraAnchorDistance: "medium_full_shot"
```
```jsx
cameraAnchorDistance: "full_shot"
```
### 字幕・アクセシビリティ
#### showClosedCaptions
（オプション）ビュー内にクローズドキャプションを表示するかどうかを示すブール値。プラットフォームがサポートするリクエストレスポンスで接続できるチャットボット等でのみ字幕表示されます。応答に時間がかかりストリーミング接続するタイプの会話AIの場合は字幕表示出来ません。
この設定が無効の場合、クライアントはイベントをキャッチして、独自にクローズドキャプションをレンダリングすることができます。デフォルト値は`true`です。
```jsx
showClosedCaptions: false
```
#### captionsPosition
（オプション）クローズドキャプションの位置を定義する文字列。デフォルト値は`bottom-left`です。
**値:**
* `bottom-left`
* `bottom-right`
* `bottom`
* `top-left`
* `top-right`
* `top`
#### showUserInputInterface
（オプション）テキストメッセージを入力するためのテキスト入力要素とマイクのミュートボタンを含むユーザー入力インターフェースを表示するかどうかを示すブール値。この設定が無効な場合、UneeQフレーム外で独自の入力インターフェースを実装することを選択できます。
```jsx
showUserInputInterface: true
```
### 音声・音声認識
#### enableMicrophone
（オプション）セッション開始時にマイクの許可を要求するかどうかを示す真偽値。デフォルト値はfalseです。
```jsx
enableMicrophone: true
```
#### enableVad
（オプション）音声アクティビティ検出（VAD）を有効にするかどうかを示す真偽値。VADを使用すると、ユーザーは録音の開始/停止ボタンを押すことなく話すことができます。この値をfalseに設定すると、ユーザーは押して話す必要があります。デフォルト値はtrueです。
```jsx
enableVad: false
```
#### enableInterruptBySpeech
（オプション）デジタルヒューマンが発話中にユーザーの音声によって割り込みを許可するかどうかを示すブール値。`true` に設定すると、ユーザーが話し始めることでデジタルヒューマンの発話を中断できます。`false` の場合、デジタルヒューマンが話し終わるまでユーザーの音声入力は無視されます。デフォルト値は `false` です。
```jsx
enableInterruptBySpeech: true
```
#### microphoneDeviceId
（オプション）使用する特定のマイクのデバイスIDを指定する文字列。指定しない場合は、ブラウザのデフォルトマイクが使用されます。利用可能なデバイスIDは `navigator.mediaDevices.enumerateDevices()` で取得できます。
```jsx
microphoneDeviceId: "1234567890abcdef1234567890abcdef"
```
#### speakerDeviceId
（オプション）使用する特定のスピーカー（音声出力デバイス）のデバイスIDを指定する文字列。指定しない場合は、ブラウザのデフォルトスピーカーが使用されます。
```jsx
speakerDeviceId: "1234567890abcdef1234567890abcdef"
```
#### speechRecognitionProvider
（オプション）音声認識のトランスクリプションに使用するプロバイダーを指定する文字列です。デフォルト値は `"google"` です。
**値:**
* `google`
* `deepgram`（ベータ版）
> ⚠️ Deepgram音声認識はベータ版のため、本番環境での使用には注意が必要です。
```jsx
speechRecognitionProvider: "deepgram"
```
#### speechRecognitionLocales
（オプション）このオプションは、デジタルヒューマンが人の話す言語を理解するために最大4つのロケールを指定します（音声認識）。ロケールはBCP-47形式で指定し、例としては"en-US"などがあります。最初のロケールが主要なロケールと見なされます。ロケールはコロンで区切って指定してください。
```jsx
speechRecognitionLocales: ja-JP:en-US:en-GB:en-AU
```
音声認識のロケールコードの変更を行う場合は、会話AIやRAG、音声合成のロケールの統一対応など調整を行ってください。
| 認識させたい言語 | ロケールコード/BCP-47 |
| ------------- | -------------------------------------------------------------------- |
| 日本語 | `ja-JP` |
| 英語（オーストラリア） | `en-AU` |
| 英語（カナダ） | `en-CA` |
| 英語（インド） | `en-IN` |
| 英語（ニュージーランド） | `en-NZ` |
| 英語（英国） | `en-GB` |
| 英語（米国） | `en-US` |
| 中国語（簡体字、中国本土） | `cmn-Hans-CN` |
| 中国語（繁体字、台湾） | `cmn-Hant-TW` |
| 韓国語（韓国） | `ko-KR` |
| タイ語（タイ） | `th-TH` |
| ベトナム語（ベトナム） | `vi-VN` |
| その他 | [対応言語](https://cloud.google.com/speech-to-text/docs/languages?hl=ja) |
#### speechRecognitionHintPhrases
（オプション）スピーチ認識システムに予想される単語についてのヒントを与えるためのフレーズをカンマで区切った文字列。このヒントフレーズを提供することで、音声認識システムが特定の単語やフレーズを優先的に認識するように設計されており、特定のコンテキストや状況で使用されます。一般的な単語よりも、具体的な単語をヒントフレーズとして登録する方が効果的です。同じカテゴリの単語をまとめてヒントフレーズとして登録することで、認識精度を向上させることができます。
```jsx
speechRecognitionHintPhrases: "決定事項, 議題, 課題, 宿題, 持ち帰り, 確認事項, 参加者, 欠席者, 開始時間, 終了時間"
```
#### speechRecognitionHintPhrasesBoost
（オプション）音声内でヒントフレーズの単語が検出される可能性を高めるために使用できる0から20までの整数。
```jsx
speechRecognitionHintPhrasesBoost: 10
```
### Deepgram 固有
#### sttDeepgramModel
（オプション）Deepgramのトランスクリプションに使用するモデルを指定する文字列です。デフォルト値は `"nova-3"` です。
```jsx
sttDeepgramModel: "nova-3"
```
#### sttDeepgramLanguage
（オプション）音声認識に使用する言語コードをBCP-47形式で指定する文字列です。デフォルト値は `"en"` です。
```jsx
sttDeepgramLanguage: "en-US"
```
#### sttDeepgramUtteranceEndMs
（オプション）発話の終了を検出するために必要な無音時間をミリ秒単位で指定する数値です。デフォルト値は `1500` です。
```jsx
sttDeepgramUtteranceEndMs: 1500
```
#### sttDeepgramSmartFormat
（オプション）スマートフォーマットを有効にするかどうかを指定するブール値です。有効にすると、トランスクリプトに句読点や大文字が追加されます。デフォルト値は `true` です。
```jsx
sttDeepgramSmartFormat: true
```
#### sttDeepgramInterimResults
（オプション）中間結果を有効にするかどうかを指定するブール値です。有効にすると、ユーザーが話している間に部分的なトランスクリプトが提供されます。デフォルト値は `true` です。
```jsx
sttDeepgramInterimResults: true
```
#### sttDeepgramInterruptionWordThreshold
（オプション）デジタルヒューマンが話している間に割り込むために必要な、中間トランスクリプトの最小単語数を指定する数値です。デジタルヒューマンが話していない場合は、単語数に関係なくすべての発話が送信されます。デフォルト値は `3` です。
> 💡 注意: Deepgramをトランスクリプションに使用しながら音声割り込みを実質的に無効にするには、より高い値（例: 999）に設定してください。
```jsx
sttDeepgramInterruptionWordThreshold: 3
```
#### sttDeepgramFillerWords
（オプション）フィラーワード（um、uh、likeなど）をトランスクリプトに含めるかどうかを指定するブール値です。デフォルト値は `false` です。
```jsx
sttDeepgramFillerWords: false
```
#### sttDeepgramEndpointing
（オプション）無音検出のしきい値をミリ秒単位で指定する数値です。これにより、システムが発話中の間（ポーズ）をどれだけ早く検出するかが決まります。デフォルト値は `500` です。
```jsx
sttDeepgramEndpointing: 500
```
#### sttDeepgramKeyterms
（オプション）認識精度を高めたい用語をカンマで区切って指定する文字列です。製品名や固有名詞などをキータームとして登録すると、それらの語が優先的に認識されます。
```jsx
sttDeepgramKeyterms: "デジタルヒューマン, Renny, MiniPrem"
```
#### sttDeepgramNoDelay
（オプション）トランスクリプト配信から人工的な遅延を取り除き、より低いレイテンシで結果を受け取るかどうかを指定するブール値です。デフォルト値は `false` です。
```jsx
sttDeepgramNoDelay: false
```
### ローカライズ
#### languageStrings
（オプション）`languageStrings`プロパティを定義することで、ホステッドエクスペリエンスインターフェース内で表示されるテキストを更新できます。`languageStrings`オブジェクトには、[ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)言語コード（例 : `en`、`es`、`ja`など）に対応する値を含める必要があります。各言語コード値には、更新したい値のキーを含むオブジェクトを提供します。また、より正確な言語ターゲット設定のために、`en-US`、`en-GB`、`de-DE`、`pt-BR`などの特定のロケール/地域を指定することもできます。
ユーザーがデジタルヒューマンエクスペリエンスをロードする際、ブラウザはユーザーの好みの言語リスト（優先順の配列）を提供します。ホステッドエクスペリエンスは、ユーザーのブラウザで設定された言語の優先順位に基づいて、提供された`languageStrings`リストを順に検索し、キーに一致する言語を探します。ブラウザが好みの言語を検出する方法についての詳細は[こちら](https://developer.mozilla.org/ja/docs/Web/API/Navigator/languages)で確認できます。
言語コードが提供されていない場合は、`default`値が使用されます。`default`設定が指定されていない場合は、ホステッドエクスペリエンスの基本値が使用されます。
`languageStrings`キーの完全なリストは、こちらで確認できます: [表示文字列（多言語対応）](/dev/hosted-experience/hosted-experience-display-strings.md)
```json
languageStrings: {
es: {
callToActionText: "¡Hola! Haga clic aquí para iniciar una conversación.e",
textInputPlaceholder: "Escriba aquí...",
},
ja: {
callToActionText: "やあ！会話を始めるにはここをクリックしてください。",
textInputPlaceholder: "ここに入力...",
},
"de-DE": {
callToActionText: "Hi! Klicken Sie hier, um ein Gespräch zu beginnen.",
textInputPlaceholder: "Geben Sie hier ein ...",
},
default: {
callToActionText: "Hi! Click here to start a conversation.",
textInputPlaceholder: "Type here...",
},
}
```
### カスタマイズ
#### customMetadata
（オプション）すべてのチャットプロンプトまたは音声プロンプトに渡されるJSONデータ。この値は、実行時に`setCustomPromptMetadata()`を使用して上書きすることができます。`customMetadata`を介して設定されたデータは対話プラットフォームに送信され、応答を生成する際に使用されることがあります。
```jsx
customMetadata: {"name": "John"}
```
#### customStyles
（オプション）ホステッドエクスペリエンスフレームに適用されるカスタムCSSを定義する文字列。例えば、ホステッドエクスペリエンスフレーム内のボタンの色を変更する際に使用できます。
```jsx
customStyles: `h1 { font-size: 150%; }`
```
⚠️ **カスタムスタイリングのリスク**
デジタルヒューマンを表示しているフレーム内の要素のスタイリングは、ホステッドエクスペリエンスのアップデートなどで時々変更されるため、リスクを伴います。カスタムスタイリングは、ユーザーインターフェースを変更する際の最終手段として使用してください。
代わりに、設定オプションを使って要素を非表示にし、独自のインターフェースを作成することをお勧めします。例えば、`displayCallToAction: false` を使用して、独自のコールトゥアクションを作成する方法です。
ミッションクリティカルなUIには、決して `customStyles` を使用すべきではありません。
リスクを軽減するために、変更される可能性が低い `custom-style-` というプレフィックスを持つクラスを提供しています :
| クラス名 | 説明 |
| ----------------------------- | ----------------------------------------------------------------- |
| `custom-style-state-initial` | コールトゥアクションの吹き出し、例 : 「👋 やあ！お会いできて嬉しいです。」 |
| `custom-style-state-error` | エラーの吹き出し、例 : 「エラーが発生しました。」 |
| `custom-style-queue-position` | キューポジション（接続順番待ち位置）の吹き出し、例 : 「You are 1st in line to speak to me.」 |
`custom-style-state-initial`
`custom-style-queue-position`
例 : 順番待ち位置の吹き出し（`custom-style-queue-position`）を非表示にして、独自に実装するには :
```css
customStyles: `.custom-style-queue-position { display: none !important; }`
```
次に、イベントリスナーで `WaitingInQueue` メッセージをリスニングし、番号を示す「`position`」属性を抽出することで、適切な言語で独自の画面メッセージを作成することができます。
#### 例: ネットワーク品質警告バナーを非表示にする
⚠️ 以下で使用する .network-banner は、上記の custom-style- プレフィックス付き安定クラスとは異なります。ネットワーク品質が劣化した際に自動表示される`「ネットワークが不安定です。映像が一時停止する場合があります。Wi-Fiルーターに近づくか、通信環境をご確認ください。」`や`「Poor network connection — the video may pause. Try moving closer to your Wi-Fi router or improving your network speed.」`というバナー（ コンポーネント、`class="network-banner"`）は、`networkIndicator` オプション（バー/アイコン表示、`visibility: 'hidden'` で制御）とは別の独立した機能であり、専用の無効化オプションは提供されていません。
非表示にしたい場合は、以下の customStyles で対応可能です（2026-07-04時点、実機のネットワーク劣化環境で動作確認済み）。custom-style- プレフィックスクラスではないため、ホステッドエクスペリエンスのアップデートでクラス名やDOM構造が変更される可能性があります。定期的な動作確認を推奨します。
```css
customStyles: .network-banner { display: none !important; }
```
### ログ
#### logLevel
（オプション）目的のログレベルを定義する文字列。低いログレベルを選択すると、それより上のすべてのログレベルが含まれます。たとえば、`info`を使用すると、それより上の`warn`、`error`、`fatal`などのログレベルも含まれます。ホステッドエクスペリエンスからのログを最小限にするには、`error`を使用してください。
**値:**
* `error`: エラーが発生し、処理が中断される可能性がある重大な問題を示します。
* `warn`: 警告を示し、潜在的な問題があるが、処理は続行できる状況を指します。
* `info`: システムやアプリケーションの一般的な動作状況を示す情報を記録します。
* `debug`: デバッグ目的で使用され、詳細な診断情報を提供します。
* `trace`: トレース情報を記録し、システムの詳細な内部動作を追跡するのに用いられます。
```jsx
logLevel: "warn"
```
### ネットワーク品質
#### networkIndicator
（オプション）ネットワーク品質インジケーターをセッション開始時に自動的に表示するための設定オブジェクト。これは、セッション開始後に `setNetworkIndicatorEnabled` を呼び出すのと同等です。
| オプション | 型 | デフォルト | 説明 |
| ---------------------- | ------ | ----------------- | ---------------------------------------------------------------------------- |
| `visibility` | String | `"when-degraded"` | インジケーターの表示タイミング: `"always"`（常時）/ `"when-degraded"`（品質低下時のみ）/ `"hidden"`（非表示） |
| `position` | String | `"top-right"` | 表示位置（四隅）: `"top-left"` / `"top-right"` / `"bottom-left"` / `"bottom-right"` |
| `popupTrigger` | String | `"click"` | 詳細パネルの表示トリガー: `"click"` / `"hover"` / `"none"` |
| `collectionIntervalMs` | Number | `3000` | WebRTC 統計を収集する間隔（ミリ秒） |
| `expectedFrameRate` | Number | `30` | 映像 MOS（品質スコア）の算出に使用する想定ソースフレームレート |
**品質レベル:**
* **Good** — 緑・3本バー。接続は良好です。
* **Fair** — 黄・2本バー。体感できる品質低下があります。
* **Poor** — 赤・1本バー。重大な品質問題があります。
```jsx
networkIndicator: {
visibility: "when-degraded",
position: "top-right",
popupTrigger: "click",
}
```
## 機能拡張オプション（DHX）
ホステッドエクスペリエンス2.0では更にユーザー体験を上げる方法として機能オプション（Hosted Experience Extender / DHX）を提供しています。ホステッドエクスペリエンスのコードスニペット下に挿入してください。
{% hint style="warning" %}
SpeakAPIやローディングスピナーは**dhx.js**が読み込まれている場合のみ有効です。コードスニペットに**dhx.js**と**dhx.css**を新たに読み込み、`dhxOptions`、`connectionBaseUrl`、`personaIdentifier` を指定する必要があります。通常はコードスニペットサンプルをそのままご利用いただければ気にする必要はありません。
ただし、`showClosedCaptions`と`showCaptions`は似たような機能を提供していますが、以下の違いがあります :
* `showClosedCaptions`ではユーザーのリクエストやSpeakAPIを使用した発話指示の表示に対応していません。ホステッドエクスペリエンスのパラメータで表示位置を変更出来ます。\\
* `showCaptions`ではSpeakAPIを使用した発話指示の字幕表示にも対応していますが、パラメータで位置を設定できず、CSSで設定してください。
実際に設定してみて、どちらが用途に適しているかを判断してください。また、必要に応じてご自身で字幕を実装することも検討してみてください。
{% endhint %}
DHX サンプルコード
```html
```
```json
window.dhxOptions = {
"personaIdentifier": 'デジタルヒューマン株式会社から提供',
"uneeq": uneeq,
"connectionBaseUrl":"https://ai-orch-001.digitalhumans.ne.jp",
"showCaption": true,
"showWaitingSpinner": true,
"useDhxCustomEvent": true,
"cameraAnchorDuration": 2000,
"showEndSession": true,
"showWaitingMessage": true,
"dhxCustomStyles": ``
}
```
```html
```
### 接続・基本
#### personaIdentifier
**デフォルト : `なし`**
（必須）DHXを使用するための識別子。デジタルヒューマン株式会社から提供されます。DIPでも確認していただけます。
```jsx
personaIdentifier: '323d5c36-e01c-4c0d-9ef5-2c00de4aa166'
```
#### uneeq
**デフォルト : `なし`**
（必須）uneeqインスタンスを制御するために必要です。2025/4/1現在 ではオプションはありません。
```html
uneeq: uneeq
```
#### connectionBaseUrl
**デフォルト :** `https://ai-orch-001.digitalhumans.ne.jp`
DHXを使用するためのオーケストレーションサービスのエンドポイントURLです。専用のオーケストレーションをご提供している場合は、カスタマーサクセスより提供した値を設定してください。
```json
// 設定なしの場合は下記が自動的に設定されます。
connectionBaseUrl:"https://ai-orch-001.digitalhumans.ne.jp"
// connectionBaseUrl:"" の様に""内が空欄では動作しません。
```
### 字幕
#### showCaptions
**デフォルト :** `true`
（オプション）ビュー内にDHX字幕を表示するかどうかを示すブール値。この設定が無効の場合、クライアントはイベントをキャッチして、独自にクローズドキャプションをレンダリングすることができます。デフォルト値は`true`です。
ホステッドエクスペリエンス標準の[showClosedCaptions](/dev/hosted-experience/hosted-experience-configuration-options.md)とは別の字幕です。
```json
showCaptions: true
```
表示をカスタマイズする際のクラス名:
* `dhx-caption-area` : 字幕エリア全体
* `ai-caption` : デジタルヒューマンの字幕
* `user-caption` : ユーザーの字幕
デフォルト表示 :
### UI制御ボタン
#### showMute
**デフォルト**：`false`
デジタルヒューマンの表示エリア右上に「デジタルヒューマンをミュート・アンミュートする」ボタンを表示するかどうかを指定するブール値です。ユーザーが一時的にデジタルヒューマンをミュートしたい場合などに利用できます。
```json
showMute:true
```
表示をカスタマイズする際のクラス名 :
* `dhx-mute-area` : ミュート・アンミュートボタンエリア
* `dhx-mute-btn` : ミュート・アンミュートボタン
デフォルト表示 :
#### showStopSpeaking
**デフォルト**：`false`
デジタルヒューマンの表示エリア右上に「デジタルヒューマンの発話を矯正的に終了させる」ボタンを表示するかどうかを指定するブール値です。ユーザーがデジタルヒューマンの発話を停止したい場合などに利用できます。
```json
showStopSpeaking:true
```
表示をカスタマイズする際のクラス名 :
* `dhx-stop-speaking-area` : 発話停止ボタンエリア
* `dhx-stop-speaking-btn` : 発話停止ボタン
デフォルト表示 :
#### showEndSession
**デフォルト :** `false`
デジタルヒューマンの表示エリア右上に「セッションを終了する」ボタンを表示するかどうかを指定するブール値です。ユーザーが明示的にセッションを終了させたい場合などに利用できます。
```json
showEndSession:true
```
表示をカスタマイズする際のクラス名 :
* `dhx-end-session-area` : セッション終了ボタンエリア
* `dhx-end-session-btn` : セッション終了ボタン
デフォルト表示 :
### ローディング・スピナー
#### showStartupSpinner
**デフォルト :** `false`
デジタルヒューマンの起動処理開始から、デジタルヒューマンが表示されるまでの間にインジゲーターとしてローディングスピナーを表示します。 現在は1種類のみです。
```json
showStartupSpinner:true
```
表示をカスタマイズする際のクラス名 :
* `dhx-startup-spinner` : 起動処理ローディングスピナー
デフォルト表示 :
[Document - 11 July 2025.mp4](https://gitlab.digitalhumans.jp/docs/docs-digitalhumansjp/-/blob/main/development/hosted-experience/%E8%A8%AD%E5%AE%9A%E3%82%AA%E3%83%97%E3%82%B7%E3%83%A7%E3%83%B3/Document_-_11_July_2025.mp4)
#### showWaitingSpinner
**デフォルト :** `true`
ユーザの発話（デジタルヒューマンへの質問）後から、デジタルヒューマンがしゃべり出すまでの間にインジゲーターとしてローディングスピナーを表示します。スピナーの種類は後述する`waitingSpinnerType`パラメータで設定可能です。
```json
showWaitingSpinner: true
```
表示をカスタマイズする際のクラス名 : `dhx-waiting-spinner`
必要に応じて[イベント](https://gitlab.digitalhumans.jp/docs/docs-digitalhumansjp/-/blob/main/settings/experience/hosted-experience-speech-events.md)を取得し、オリジナルのローディングスピナーなどを実装してください。
デフォルト表示 :
#### waitingSpinnerType
**デフォルト :** `Default`
ユーザの発話（デジタルヒューマンへの質問）後から、デジタルヒューマンがしゃべり出すまでの間に表示するインジケータの種類を選択します。
選択肢（デザインを参考に設定してください）：`Default` , `growCircle` ,`aquaCircles` , `screenGrow`
```json
waitingSpinnerType: 'aquaCircles'
```
**デザイン**
Default
{% file src="/files/ri8CeaBfiXRz6ZotW3FC" %}
aquaCircles
{% file src="/files/GNZbJ7eTBgUyqt0hiODV" %}
growCircle
{% file src="/files/sxDT8sDg4B9y7RRDq5GD" %}
screenGrow
{% file src="/files/QKRzp2pUyQvsOkMBEdRv" %}
### 待機・キュー表示
#### showWaitingMessage
**デフォルト :** `false`
デジタルヒューマン起動時に、接続待ちの状態を表すメッセージ（例：順番に接続しますので、お待ちください。ただ今、他の方の対応をしております。１番目にお繋ぎいたします。）を表示するかどうかを指定するブール値です。順番待ちの情報をユーザーに知らせる場合に利用できます。
接続待ちの状態を表すメッセージは`dhxOptions.waitingMessageText` で設定できます。
```json
showWaitingMessage:true
```
表示をカスタマイズする際のクラス名 :
* `dhx-waiting-queue-message` : 接続待ちメッセージ
デフォルト表示 :
この表示は、`dhx.js` によって自動生成される以下のHTML構造を元に表示されます。お客様側で表示スタイルを変更する場合は、CSSにて以下のクラスを上書きすることでカスタマイズが可能です。
```html
順番に接続しますので、お待ちください。
ただ今、他の方の対応をしております。1番目にお繋ぎいたします。
```
```css
.dhx-waiting-message {
background-color: antiquewhite;
font-size: 14px !important;
}
```
#### waitingMessageText
**デフォルト :** `'順番に接続しますので、お待ちください。 ただ今、他の方の対応をしております。{position}番目にお繋ぎいたします。'`
接続待ちの状態をユーザーに通知する際に表示されるメッセージの文言を指定する文字列です。このメッセージは、`dhxOptions.showWaitingMessage` が `true` の場合に表示されます。`{position}` を含めることで、ユーザーの順番（待機番号）を動的に挿入できます。
```json
waitingMessageText: '接続待ちです。{position}番目です。'
```
### メンテナンス制御
#### enableMaintenanceMessage
デフォルト：`true`
```json
enableMaintenanceMessage:true
```
この設定では、**メンテナンス時間中のデジタルヒューマンの起動を制限する機能**を有効または無効にします。 有効にすると、メンテナンススケジュールを取得し、指定されたメンテナンス時間内であれば警告メッセージを表示して、デジタルヒューマンの起動を制限します。 無効（`false`）に設定すると、メンテナンス情報の取得および起動制御を行わず、常にデジタルヒューマンを起動できるようになります。
{% hint style="warning" %}
メンテナンス時間中は、デジタルヒューマンが起動できなかったり、起動できても会話が行えない場合があります。
{% endhint %}
メンテナンスメッセージは、CTA・独自スタートボタンがクリックされた際のデジタルヒューマンが起動処理を開始した時点で表示されます。
{% hint style="warning" %}
`uneeqOptions.autoStart`を`true`に設定している場合はユーザーのアクションなしでメッセージが表示されます。
{% endhint %}
表示をカスタマイズする際のクラス名 :
* `dhx-snackbar` : 表示するメッセージエリア
デフォルト表示 :
#### customerMaintenanceJsonUrl
デフォルト : なし
```json
customerMaintenanceJsonUrl: 'https://your-domain.com/maintenance/maintenance.json'
```
お客様独自のメンテナンススケジュールを定義したJSONファイルのURLを指定します。設定された場合、DHKKのメンテナンス情報と統合してメンテナンス時間をチェックします。どちらか一方でもメンテナンス時間内であれば、デジタルヒューマンの起動が制限されます。
メンテナンススケジュールを管理したい場合や、システム全体のメンテナンスとは別に個別のメンテナンス予定を設定したい場合に便利です。 URLが設定されていない場合は、DHKKのメンテナンス情報のみでチェックを行います。
{% hint style="warning" %}
注意事項
JSONファイルの構造が正しくない場合（必須プロパティの欠如、不正な日時形式、配列ではない等）、エラーが発生してメンテナンス機能が適切に動作しない可能性があります。
JSONファイルを作成・編集する際は、下記の構造に従って正確に記述してください。
{% endhint %}
**JSONファイル構造**
メンテナンススケジュールJSONは配列形式で複数のメンテナンス予定を定義できます：
```json
[
{
"title": "デジタルヒューマンプラットフォーム定期メンテナンス",
"message": "定期メンテナンスのため、一時的にサービスを停止しております。
メンテナンス予定時刻：2025/11/04 11:00 ~ 12:00",
"startTime": "2025-10-26T01:00:00+09:00",
"endTime": "2025-10-26T03:00:00+09:00",
"enabled": true
},
{
"title": "デジタルヒューマンプラットフォーム定期メンテナンス",
"message": "定期メンテナンスのため、一時的にサービスを停止しております。
メンテナンス予定時刻：2025/11/04 11:00 ~ 12:00",
"startTime": "2025-11-04T11:00:00+09:00",
"endTime": "2025-11-04T12:00:00+09:00",
"enabled": true
}
]
```
* `enabled`: メンテナンススケジュールの有効/無効（boolean）
* `title`: メンテナンスのタイトル（string）
* `message`: ユーザーに表示するメッセージ（string、HTMLタグ使用可能）
* `startTime`: メンテナンス開始時刻（ISO 8601形式の文字列）
* `endTime`: メンテナンス終了時刻（ISO 8601形式の文字列）
{% hint style="info" %}
メッセージ表示条件
* `enabled`が`true`に設定されている\\
* `dhx.js`の読み込み（または`dhxInit`の実行）時刻が`startTime`～`endTime`の間にある\\
* 表示されるメッセージは「`title`: `message`」の形式
{% endhint %}
### アイドル発話
#### idleSpeak
**デフォルト :** なし
デジタルヒューマンが最後に発話してから設定時間が経過した後、自動的に発話を行い、ユーザーへの呼びかけやセッションのタイムアウト更新を行います。エントランスや展示会などでご利用いただける機能です。
{% hint style="danger" %}
不特定多数がアクセスするWebサイト等で`idleSpeak`をご利用になると、デジタルヒューマンを表示したまま放置された際に、セッションが大量に消費される可能性がありますので、ご注意ください。
{% endhint %}
このパラメータを有効にする場合は、以下の関連パラメータも併せて設定してください。設定が無い場合はそれぞれのデフォルトが適用されます。
* `idleSpeakTime`
* `idleSpeakSelectMode`(任意)
発話する文章を配列で指定します。 各要素は以下のプロパティを持つオブジェクトです：
* content (必須) : 発話するテキスト内容
* instructions (任意) : 発話時に実行する追加の指示
* addCaption (任意, デフォルト: `true`) : 字幕表示の有無
```json
"idleSpeak": [
{
'content': 'おはようございます',
'addCaption': false,
},
{
'content': 'こんにちは',
'instructions': {
'displayHtml': {'html': '表示内容'}
},
'addCaption': true,
},
{
'content': 'こんばんは',
'instructions': {
'customMetadata': {
'data': 'goodEvening'
}
},
},
]
```
#### idleSpeakTime
**デフォルト :** `180`
`idleSpeak`で指定した文章を、最後のデジタルヒューマンの発話から何秒後に発話するかを数値で設定します。
```json
// 最後のデジタルヒューマン発話から180秒後（3分後）に自動的に発話する
idleSpeakTime: 180
```
#### idleSpeakSelectMode
**デフォルト :** `random`
`idleSpeak`で指定したリスト内の文章を選択する方法を指定します。以下のいずれかを設定してください。
* `random` : リストの中からランダムに1つの文章を選んで発話します。
* `sequential` : リストの先頭から順番に発話します。最後の要素を発話すると、再び先頭の要素に戻って繰り返します。
```json
idleSpeakSelectMode: 'sequential'
```
### カスタム STT
#### customStt
デフォルト : `false`
独自の音声認識（STT）システム（BYO STT / Custom STT）を使用するためのオプションです。
本オプションを `true` に設定し、あわせて **DIP 側でペルソナに STT アカウントを設定**することで、カスタム STT が利用可能になります。
カスタム STT を有効にした場合、セッション開始時に STT サービスが自動的に初期化され、
customStt 専用のコントロール UI（マイクボタン・テキスト入力欄など）が画面に表示されます。
```json
// デフォルト: カスタムSTTを使用しない
customStt: false
// カスタムSTTを使用する
customStt: true
```
{% hint style="warning" %}
customStt 機能を有効にする場合は、デジタルヒューマン標準のマイクコンポーネントを使用しない設定にしてください。
```json
uneeqOptions = {
enableMicrophone: false,
showUserInputInterface: false,
...
}
```
{% endhint %}
表示をカスタマイズする際のクラス名 :
* `dhx-custom-stt-area` : customSttエリア
* `dhx-custom-stt-btn` : customStt用マイクボタン
* `dhx-custom-stt-text-input` : customStt用テキスト入力欄
* `dhx-custom-stt-send-btn` ：テキスト入力送信ボタン
デフォルト表示 :
#### micDeviceId
デフォルト : なし
customStt機能で使用するマイクのデバイスIDを指定するオプションです。
特定のマイクデバイスを使用したい場合に、そのデバイスIDを文字列で指定します。
指定しない場合は、ブラウザのデフォルトマイクが使用されます。
```jsx
// デフォルト: デバイスIDを指定しない(ブラウザのデフォルトマイクを使用)
micDeviceId: undefined
// 特定のマイクデバイスを指定する
micDeviceId: "1234567890abcdef1234567890abcdef"
```
**micDeviceId関連サンプルコード**
**deviceIdの取得方法**
以下のコードで、利用可能なマイクデバイスの一覧とそのdeviceIdを取得できます。
```jsx
// マイクデバイスの一覧を取得
async function getMicDevices() {
const devices = await navigator.mediaDevices.enumerateDevices();
const audioDevices = devices.filter(device => device.kind === 'audioinput');
audioDevices.forEach(device => {
console.log('Microphone:', device.label, 'DeviceId:', device.deviceId);
});
return audioDevices;
}
```
**localStorageへの保存**
ユーザーが選択したマイクのdeviceIdをlocalStorageに保存します。
```jsx
// deviceIdをlocalStorageに保存
function saveMicDeviceId(deviceId) {
localStorage.setItem('selectedMicDeviceId', deviceId);
}
// 例: ユーザーがマイクを選択した場合
const selectedDeviceId = 'abc123def456...';
saveMicDeviceId(selectedDeviceId);
```
**次回アクセス時の自動設定**
localStorageからdeviceIdを取得し、`dhxOptions.micDeviceId`に設定します。
```jsx
// localStorageからdeviceIdを取得
const savedMicDeviceId = localStorage.getItem('selectedMicDeviceId');
// dhxOptionsに設定
const dhxOptions = {
customStt: true,
micDeviceId: savedMicDeviceId || undefined, // 保存されていればそれを使用、なければundefined
// ... 他のオプション
};
const uneeq = new Uneeq(dhxOptions);
```
#### selectMic
デフォルト : `false`
customStt機能で使用するマイクを、セッション開始時にユーザーが選択できるUIを表示するかどうかを制御するオプションです。
`true`に設定すると、利用可能なマイクデバイス一覧が表示され、ユーザーが使用するマイクを選択できます。
`micDeviceId`が指定されている場合は、そちらが優先されます。
```jsx
// デフォルト: マイク選択UIを表示しない
selectMic: false
// マイク選択UIを表示する
selectMic: true
```
表示をカスタマイズする際のクラス名 :
* `dhx-mic-select-modal` : マイク選択モーダル全体のコンテナ
* `dhx-mic-select-content` : モーダルのコンテンツ部分
* `dhx-mic-select-title` : モーダルのタイトル
* `dhx-mic-select-list` : マイクリストのコンテナ
* `dhx-mic-select-item` : 各マイク選択アイテム
デフォルト表示 :
### 静止画キャプチャ（VISION）
#### stillcam
デフォルト : `false`
静止画像キャプチャ機能を有効にするためのオプションです。
ユーザーの Web カメラで撮影した静止画像を、毎秒バックエンドに送信することができます。
送信された画像を実際に利用するためには、独自の NLP 実装（画像を処理する仕組み）が必要となります。
VISION 機能に対応した Chatbot と連携することで、最新の静止画像をもとにユーザーの状態を把握した応答や処理が可能になります。
{% hint style="warning" %}
本機能は 有料オプションとなっており、ペルソナごとに DHKK 側での利用許可が必要です。
{% endhint %}
```json
// デフォルト: 静止画キャプチャ機能を使用しない
stillcam: false
// 静止画キャプチャ機能を使用する
stillcam: true
```
表示をカスタマイズする際のクラス名 :
* `dhx-stillcam-video-container` : Webカメラの状態を表示するコンテナ
#### cameraDeviceId
デフォルト : なし
stillcam機能で使用するカメラのデバイスIDを指定するオプションです。
特定のカメラデバイスを使用したい場合に、そのデバイスIDを文字列で指定します。
指定しない場合は、ブラウザのデフォルトカメラが使用されます。
```jsx
// デフォルト: デバイスIDを指定しない(ブラウザのデフォルトカメラを使用)
cameraDeviceId: undefined
// 特定のカメラデバイスを指定する
cameraDeviceId: "1234567890abcdef1234567890abcdef"
```
**cameraDeviceId関連サンプルコード**
**deviceIdの取得方法**
以下のコードで、利用可能なカメラデバイスの一覧とそのdeviceIdを取得できます。
```jsx
// カメラデバイスの一覧を取得
async function getCameraDevices() {
const devices = await navigator.mediaDevices.enumerateDevices();
const videoDevices = devices.filter(device => device.kind === 'videoinput');
videoDevices.forEach(device => {
console.log('Camera:', device.label, 'DeviceId:', device.deviceId);
});
return videoDevices;
}
```
**localStorageへの保存**
ユーザーが選択したカメラのdeviceIdをlocalStorageに保存します。
```jsx
// deviceIdをlocalStorageに保存
function saveCameraDeviceId(deviceId) {
localStorage.setItem('selectedCameraDeviceId', deviceId);
}
// 例: ユーザーがカメラを選択した場合
const selectedDeviceId = 'abc123def456...';
saveCameraDeviceId(selectedDeviceId);
```
**次回アクセス時の自動設定**
localStorageからdeviceIdを取得し、`dhxOptions.cameraDeviceId`に設定します。
```jsx
// localStorageからdeviceIdを取得
const savedCameraDeviceId = localStorage.getItem('selectedCameraDeviceId');
// dhxOptionsに設定
const dhxOptions = {
stillcam: true,
cameraDeviceId: savedCameraDeviceId || undefined, // 保存されていればそれを使用、なければundefined
// ... 他のオプション
};
const uneeq = new Uneeq(dhxOptions);
```
#### selectCamera
デフォルト : `false`
stillcam機能で使用するカメラを、セッション開始時にユーザーが選択できるUIを表示するかどうかを制御するオプションです。
`true`に設定すると、利用可能なカメラデバイス一覧が表示され、ユーザーが使用するカメラを選択できます。
`cameraDeviceId`が指定されている場合は、そちらが優先されます。
```jsx
// デフォルト: カメラ選択UIを表示しない
selectCamera: false
// カメラ選択UIを表示する
selectCamera: true
```
表示をカスタマイズする際のクラス名 :
* `dhx-camera-select-modal` : カメラ選択モーダル全体のコンテナ
* `dhx-camera-select-content` : モーダルのコンテンツ部分
* `dhx-camera-select-title` : モーダルのタイトル
* `dhx-camera-select-list` : カメラリストのコンテナ
* `dhx-camera-select-item` : 各カメラ選択アイテム
デフォルト表示 :
#### showStillcamWipe
デフォルト : `true`
静止画キャプチャ（stillcam）使用時に、Web カメラに写っている映像（毎秒撮影される静止画）を画面上に表示するかどうかを制御するオプションです。
stillcam が有効な場合、ユーザーの Web カメラで撮影されている映像を確認できる表示エリア（ワイプ状の表示）が画面上に表示されます。
本オプションを `false` に設定すると、静止画の撮影・バックエンドへの送信は継続したまま、カメラ映像の表示エリアのみを非表示にすることができます。
```json
// デフォルト: ワイプエフェクトを表示する
showStillcamWipe: true
// ワイプエフェクトを表示しない
showStillcamWipe: false
```
{% hint style="warning" %}
* このオプションはstillcamがtrueの場合にのみ有効です。\\
* `showStillcamWipe: false` に設定しても、\\
* Web カメラでの静止画撮影\\
* 毎秒のバックエンド送信
は停止されません。
* ユーザーにカメラ映像を見せずに VISION 用の画像のみを送信したい場合に有効です。
{% endhint %}
**動的な表示切り替えについて**
`showStillcamWipe` の設定とは別に、実行中に Web カメラ表示エリアの表示／非表示を動的に切り替えることも可能です。
以下の関数を使用することで、JavaScript から任意のタイミングで切り替えできます。
```jsx
// Webカメラ表示エリアを表示する
window.dhxShowStillcamWipe(true)
// Webカメラ表示エリアを非表示にする
window.dhxShowStillcamWipe(false)
```
この操作は 表示制御のみを行うものであり、静止画の撮影およびバックエンドへの送信処理には影響しません。
### デバッグ・カスタマイズ・その他
#### timeDetail
**デフォルト**：`false`
```json
timeDetail:true
```
デジタルヒューマンに関する時間の詳細をJavascriptコンソールに出力します。
| 表示 | 指標名 | 説明 |
| -------------------------------------- | ------- | ---------------------------------------------------------------------------------------- |
| `WaitingToStart - SessionLive` | 起動時間 | デジタルヒューマンの起動処理が始まってから、デジタルヒューマンが画面に表示されるまでの時間 |
| `SessionLive - SessionEnded` | セッション時間 | デジタルヒューマンが画面に表示されていた合計時間 |
| `UserStartedSpeaking - PromptRequest` | 音声認識時間 | ユーザーが話し始めてから話し終えるまでの時間。ストリーミングSTT処理により、実質的な音声認識時間を表す |
| `SpeakRequest - AvatarStartedSpeaking` | 応答処理時間 | ユーザー発話の終了から、デジタルヒューマンが応答を開始するまでの時間。
RAG、LLM、音声合成、アニメーション生成と一連のデータ転送処理に要した時間を含む
|
#### useDhxCustomEvent
**デフォルト :** `true`
DHXで提供されるCustomEventを使用するかどうかを示すブール値。SpeakAPIや発話文からに埋め込まれたカメラ制御タグでカメラが可能になります。
```json
useDhxCustomEvent:true
```
#### cameraAnchorDuration
**デフォルト :** `2000`
DHXで提供されるCustomEventによるカメラ制御を行った場合のカメラ移動の所要時間を指定します。1,000ミリ秒が1秒になり、ミリ秒（ms）単位で指定します。
```json
// デフォルト: 2000msかけて移動する
cameraAnchorDuration:2000
// 500msかけて移動する
cameraAnchorDuration:500
```
#### dhxCustomStyles
**デフォルト :** なし
画面全体に適用されるCSSを文字列として記述することで、内部的に`