本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 最佳化 Omnissa 雲端桌面的 Amazon Connect 音訊
<a name="using-ccp-vdi-omnissa-step-by-step"></a>

當您的客服使用 Omnissa 虛擬桌面基礎結構 (VDI) 環境時，Amazon Connect 可讓您更輕鬆提供高品質的語音體驗。您的客服可以利用 Omnissa Horizon Client 等 Omnissa 遠端桌面應用程式，將音訊處理卸載到客服的本機裝置，並自動將音訊重新導向到 Amazon Connect，進而在具有挑戰性的網路上提高音訊品質。

若要開始使用，您可以使用 [Amazon Connect 開放原始碼程式庫](https://github.com/amazon-connect/amazon-connect-streams)以建立新的或更新現有的客服人員使用者介面，例如自訂聯絡人控制面板 (CCP)。

## 系統要求
<a name="using-ccp-vdi-omnissa-step-by-step-requirements"></a>

本節描述使用 Omnissa Horizon SDK 搭配 Amazon Connect 的系統要求。
+ **Omnissa Horizon Client 版本**
  + 最低必要版本：8.15.0 (Horizon 2503)，適用於客服和用戶端
  + Omnissa 目前僅支援執行 Windows 的客服工作站使用此功能。
  + 下載最新的 Omnissa 用戶端
**重要**  
2503 版本將是支援 ICE 重新啟動功能的第一個版本。舊版不支援此功能。
Omnissa Horizon Client 版本 2503 將可透過 [Omnissa Customer Connect](https://customerconnect.omnissa.com/downloads/info/slug/desktop_end_user_computing/omnissa_horizon_clients/8) 取得。檢查 Customer Connect 以取得最新版本。
+ **Omnissa 延伸模組和 SDK 要求**
  + Horizon WebRTC Web 應用程式同時支援延伸模組和 SDK 8.15.0 或更新版本。
  + 此瀏覽器延伸模組啟用了 Horizon Agent 內 WebRTC SDK 的 Web 應用程式支援，而且可從[這裡](https://chromewebstore.google.com/detail/horizon-webrtc-web-app-su/emildoafpcgihdmhphelfhghioccllfi?pli=1)的 Chrome Store 下載。
+ **瀏覽器支援 (最近 3 個版本)**
  + Google Chrome
  + Microsoft Edge (Chromium)
+ **Omnissa 伺服器設定**：預設不會啟用 Omnissa Horizon SDK。系統管理員需要在 Omnissa Horizon Agent 虛擬機器內設定下列登錄設定 (最好透過登錄編輯程式 (regedit))：
  + **開啟登錄編輯器**
    + 針對 Windows：
      + 按下 **Windows \$1 R**
      + 輸入 **regedit**，然後按下 **Enter** 鍵。
  + 建立/導覽至以下登錄檔路徑：

    ```
    Key Path: Computer\HKLM\SOFTWARE\Policies\Omnissa\Horizon\WebRTCRedirSDKWebApp
    Key Names and Values:
    chrome_enabled (REG_DWORD) = 1
    edge_chrome_enabled (REG_DWORD) = 1
    enabled (REG_DWORD) = 1
    ```

    ```
    Key Path: Computer\HKLM\SOFTWARE\Policies\Omnissa\Horizon\WebRTCRedirSDKWebApp\UrlAllowList
    Key Name: https://*.connect.aws/*
    Key Name: https://*.connect.aws.a2z.com/* 
    Key Type: REG_SZ
    ```

  在安裝 Omnissa 代理程式之後，無論 SDK 啟用狀態為何，html5server.exe 和 wsnm.exe 程序一律會在任務管理員中執行。下圖顯示在任務管理員中執行的 html5server.exe 程序。  
![\[任務管理員，html5server.exe 程序執行中。\]](http://docs.aws.amazon.com/zh_tw/connect/latest/adminguide/images/omnissa-1.png)

  下圖顯示在任務管理員中執行的 wsnm.exe 程序。  
![\[任務管理員，wsnm.exe 程序執行中。\]](http://docs.aws.amazon.com/zh_tw/connect/latest/adminguide/images/omnissa-2.png)
+ **疑難排解**
  + Omnissa 日誌檔案可在下列位置找到：

    ` %tmp%\omnissa-{username}\horizon-html5Client-{pid}.log`
**注意**  
`{pid}` 是指 Horizon Client "horizon-protocol.exe" 程序 ID，可在任務管理員中找到。
  + 增強型記錄的登錄設定

    若要啟用詳細記錄以進行疑難排解，請新增下列登錄項目：

    ```
    HKEY_LOCAL_MACHINE\SOFTWARE\Omnissa\Horizon\Html5mmr: - "html5mmr.log.noThrottle" = dword:00000001
    ```

    ```
    HKEY_LOCAL_MACHINE\SOFTWARE\Omnissa\Horizon\Html5mmr\WebrtcRedir:
     - "html5mmr.log.webrtc.allowFullText" = dword:00000001
     - "html5mmr.log.webrtc.allowThrottle" = dword:00000000
     - "html5mmr.log.webrtc.sharedlib.internal" = dword:00000001
     - "html5mmr.log.webrtc.sharedlib.network" = dword:00000001
     - "html5mmr.log.webrtc.sharedlib.media" = dword:00000001
     - "html5mmr.log.webrtc.shim.logToConsole" = dword:00000001
     - "html5mmr.log.webrtc.sharedlib.signal" = dword:00000001
     - "html5mmr.log.noThrottle" = dword:00000001
     - "html5mmr.log.webrtc.tracelevel" = dword:00000001
    ```

    這些登錄設定會啟用詳細的記錄，可協助診斷 Omnissa VDI 整合的問題。
+ **網路/防火牆組態**
  + **Omnissa VDI 組態**

    管理員需要允許 Omnissa 伺服器存取流向下圖所提網域的 Amazon Connect TCP/443 流量。請參閱[設定您的網路](ccp-networking.md)主題以進行此設定。
  + **客服工作站組態**

    此解決方案需要在客服精簡型客戶端與 Amazon Connect 之間建立媒體連線。遵循[設定您的網路](ccp-networking.md)主題，允許客服機器與 Amazon Connect 軟體電話媒體 UDP 連接埠 3478 之間的流量。

     下圖說明 UDP 連接埠 3478 的使用方式。  
![\[說明 UDP 連接埠 3478 使用方式的圖表。\]](http://docs.aws.amazon.com/zh_tw/connect/latest/adminguide/images/omnissa-3.png)

## 自訂 CCP 上的必要程式碼變更
<a name="omnissa-required-initccp-changes"></a>

若要在 Omnissa VDI 環境中啟用音訊最佳化，您必須使用下列變更來設定自訂 CCP。

1. 在 CCP 初始化之前新增下列程式碼片段。它有助於管理 CCP 的視窗識別，這在客服開啟多個視窗時尤其重要。它會新增時間戳記和「作用中軟體電話標籤」標記，以協助識別作用中的 CCP 視窗。

   ```
   const ACTIVE_SOFTPHONE_TAB = "Active Softphone Tab";
   
       window.addEventListener('message', (event) => {
   
           if (event.data.type === 'get_horizon_window_title') {
               let title = document.title;
              const currentTime = new Date();
               if (!title.endsWith(ACTIVE_SOFTPHONE_TAB)) {
                   title += ` ${currentTime.getHours()}${currentTime.getMinutes()}${currentTime.getSeconds()} ` + ACTIVE_SOFTPHONE_TAB;
                   document.title += ` ${currentTime.getHours()}${currentTime.getMinutes()}${currentTime.getSeconds()} ` + ACTIVE_SOFTPHONE_TAB;
               }
   
               event.source.postMessage(
                   { type: 'horizon_window_title_response', title: title, source: 'parent' },
                   event.origin
               );
           }
       });
   ```

1. 在 initCCP 組態中新增 VDI 平台參數。這是為了啟用音訊重新導向。

   ```
   softphone: {
       allowFramedSoftphone: true,  
       VDIPlatform: "OMNISSA"
   }
   ```
**重要**  
設定 `VDIPlatform: "OMNISSA"` 時，如果 Omnissa 音訊最佳化失敗，CCP 將不會回復到標準 Web 瀏覽器音訊。這表示：  
如果客服在 Omnissa VM 外部存取 CCP，通話將會失敗。
CCP 開發人員必須先判斷 CCP 是否正在 Omnissa VM 內執行，然後再設定此參數。
**實作選項**：  
使用個別的 URL 路徑進行 Omnissa 和非 Omnissa 存取。
使用 URL 參數來判斷環境。
實作 API，根據使用者內容判斷正確的組態。

## 如何在通話期間驗證精簡型客戶端與 Amazon Connect 之間的媒體流程
<a name="verify-omnissa"></a>

1. 確保 Omnissa Horizon WebRTC 瀏覽器延伸模組已啟用且處於備妥狀態。

1. 檢查瀏覽器工具列中的延伸模組圖示：

   1. 藍色圖示表示備妥狀態和適當的功能。

   1. 灰色圖示表示未備妥狀態和潛在問題。

   下圖顯示 Omnissa Horizon WebRTC 瀏覽器延伸模組在已啟用且處於備妥狀態時看起來像什麼。  
![\[Omnissa Horizon WebRTC 瀏覽器延伸模組 (啟用時)。\]](http://docs.aws.amazon.com/zh_tw/connect/latest/adminguide/images/omnissa-4.png)

1. 檢查程序狀態：

   1. 開啟任務管理員。

   1. 驗證 html5server.exe 和 wsnm.exe 程序是否正在執行。

   1. 確保這些程序在通話期間持續執行。如果任一程序當機，VDI 功能將會失敗。

1. 測試音訊流程：

   1. 進行測試通話

   1. 在 VM 的瀏覽器中停用麥克風存取來驗證音訊最佳化 - 通話應在本機處理音訊時繼續運作

   1. 檢查是否有任何音訊延遲或品質問題。

1. 使用 Wireshark 來驗證：

   Wireshark 是免費的開放原始碼網路封包分析器。如需詳細資訊，請參閱 Wireshark [網站](https://www.wireshark.org/)。

   1. 從[這裡](https://www.wireshark.org/download.html)下載 Wireshark。

   1. 在安裝了 Wireshark 之後，請在精簡型客戶端上開啟 wireshark，然後開始監控您的本機網路。

   1. 接通電話，然後在頂端的篩選條件列中輸入下列篩選條件：

      ```
      (udp.srcport == 3478 or udp.dstport == 3478) and ((ip.dst_host = "15.193.6.0/24"))
      ```

   1. 驗證您是否可以看到客服機器與 Amazon Connect 之間的媒體封包流程。

   1. 如果看不到任何封包：
      + 檢查網路連線能力和防火牆規則。
      + 驗證音訊最佳化設定。
**注意**  
上面顯示的 IP 範圍適用於美國東部 (維吉尼亞北部) AWS 區域。如需其他區域的 IP 範圍，請參閱[設定您的網路](ccp-networking.md)。  
下圖顯示 IP 範圍：  

![\[Omnissa Horizon WebRTC 瀏覽器延伸模組 (啟用時)。\]](http://docs.aws.amazon.com/zh_tw/connect/latest/adminguide/images/omnissa-5.png)


1. 主控台記錄

   1. 對於 Windows：開啟瀏覽器開發人員工具 (F12)。

   1. 尋找確認 Omnissa 初始化的下列 WebRTC 相關訊息：R`TC.js is using OmnissaVDIStrategy`

      以下為確認訊息具體形式的範例：

      ```
      {
              "component": "softphone",
              "level": "LOG",
              "text": " RTC.js is using OmnissaVDIStrategy",
              "time": "2025-04-03T20:47:40.460Z",
              "exception": null,
              "objects": [],
              "line": 64,
              "agentResourceId": "20c6b5a3-259e-4e18-a8a7-b962d54a6344",
              "loggerId": "1743713238678-pz6yp1q4n9s",
              "contextLayer": "CRM"
          },
      ```

## 限制
<a name="omnissa-limitations"></a>

不支援以下 CCP 組態：
+ 原生 CCP：不支援原生 CCP 的音訊最佳化。針對使用相同方式處理的通話，媒體將繼續流經 VM 內的瀏覽器。
+ Salesforce CTI Adapter：不支援 VDI 平台偵測，導致媒體透過 VM 的瀏覽器路由，而不是最佳化的用戶端音訊處理。