Flex on Citrix VDI

Overview

Flex on Citrix VDI gives customers using Virtual Desktop Infrastructure (VDI) environments the ability to run Flex.

Flex UI 2.5.0 and later improves audio quality by supporting Citrix HDX WebRTC devices. When a voice call initiates, signaling occurs between the agent's browser/Citrix Workspace App and the Twilio Voice JS SDK. The call connects directly from the agent's machine to Twilio Programmable Voice.

System requirements

The following are system requirements for the Citrix server and remote device.

Citrix server

• Citrix VDI version that supports Citrix HDX 2.0.3 and above
• Flex UI version 2.5.0 or later (Flex-hosted or self-hosted)
• The system that VDI is running on must support Citrix HDX
• Server operating system:
  • Windows 10 or later
• Up-to-date version of Google Chrome Enterprise browser or Microsoft Edge with the ability to enforce policies

Remote device

• One of the following operating systems:
  • Windows 10 or later
  • macOS
• The latest version of one of the following browsers:
  • Google Chrome
  • Microsoft Edge

Supported browsers

The latest versions of these browsers are supported:

• Google Chrome
• Microsoft Edge

Set up Flex on Citrix VDI

To set up Flex on Citrix VDI, complete the following steps:

1. Set up the Citrix VDI environment
2. Enable the Flex on Citrix VDI feature flag
3. Open ports on the Citrix machine
4. Self-hosted Flex only: Upgrade the Flex-UI library
5. Validate the Citrix setup

Set up the Citrix VDI environment

Changes to the Citrix VDI environment require a user with Administrative privileges.

By default, Citrix HDX is not enabled for Chrome. Complete the following steps to enable the Chrome browser to access the underlying Citrix HDX framework:

1. Add the application binary name, chrome.exe, to an allowlist registry in Windows Registry Editor:

   Key Path	HKLM\Software\WOW6432Node\Citrix\WebSocketService
   Key Name	ProcessWhitelist
   Key Type	MULTISZ
   Key Value	chrome.exe

2. Restart CtxHdxWebSocketService to enable Citrix HDX support for Chrome. To do this, open Task Manager, right-click CtxHdxWebSocketService, and select Restart.
3. (Optional) Some versions of Citrix have issues with HDX content redirection with Chrome browser 105 and later. As a workaround, disable the Chrome Browser Chrome Root Store certificate verifier on VDI using one of the methods specified on the Citrix support page.
   
   You can verify that you’ve disabled the Chrome Browser Chrome Root Store certificate by following the steps in the Chrome Root Store and Certificate Verifier.
   
   The issue is fixed on the following Citrix versions:
   
   • Versions after CVAD 2212
   • CVAD 1912 CU7
   • CVAD 2203 CU2

Enable the Flex on Citrix VDI feature flag

To use Flex on Citrix VDI, you must enable it:

1. Navigate to https://flex.twilio.com/admin/features.
2. In the General Availability (GA) tab of the Feature Settings page, enable Enable Voice on Citrix VDI.

Firewall rules

Open the following ports on the Citrix machine:

Self-hosted Flex only: Upgrade the Flex UI library

Upgrade the Flex library to a version that supports Citrix VDI:

Upgrade the flex-ui v1 library to the latest version.

1. Download the latest version from the NPM registry.
2. Run the following command in your Flex project:

npm install flex-ui@2.5.0

Upgrade the @twilio/voice-sdk

If you are using @twilio/voice-sdk, upgrade to version 2.5 or later for support with the Citrix HDX-compatible webRTC APIs.

npm install @twilio/voice-sdk@2.5

Validate the Citrix setup

Follow these steps to validate your setup and ensure that Flex will automatically detect if you’re running in a VDI environment:

1. Log in to your VDI environment.

2. Open the Chrome browser within the VDI environment.

3. Open Flex and log in to your Flex instance.

5. Open the Chrome developer tools and switch to the Console tab in the developer tools.

6. Wait until the log messages slow down in the console.

7. Paste the following code snippet into the console, then press Enter.

const citrixSocket = new WebSocket("wss://127.0.0.1:9002");
citrixSocket.onopen = (event) => {
  citrixSocket.send(
    JSON.stringify({
      v: "webrtc",
      hdr: {
        version: 1,
        msg_type: "req",
        modifier: false,
        destroy: false,
        proc: { iid: 0, methodid: 2 }
      },
      objref: { oid: 0 },
      params: [[]]
    })
  );
};
citrixSocket.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if ( msg.command === "feature-support" ) {
    console.log("Success : We are in Citrix with webrtc support");
    alert("Success : We are in Citrix with webrtc support");
    citrixSocket.close();
  }
};
citrixSocket.onclose = ()=> console.log("Socket successfully closed")
citrixSocket.onerror = ()=> {
    console.log("Failure : Error opening socket");
    alert("Failure : Error opening socket");
}

8. A pop-up message appears in the browser with one of the following messages:

• Success: We are in Citrix with webrtc support
  • This message means that Flex can detect your Citrix environment.

• Failure: Error opening socket
  • This message means Flex is unable to connect to the Citrix HDX package. This problem can be caused by any of the following issues:
    • The steps in the "Set up the Citrix VDI environment" section above were not completed successfully.
    • The Citrix HDX package is not present on your system.
    • The Citrix HDX version on your system is not compatible.

Check your configurations and ensure that your environment meets the system requirements, then try again. If you still run into issues, contact Twilio support.

Twilio Voice JavaScript SDK changes

If you have additional plugins or business logic that use the Twilio Voice JavaScript SDK, you must upgrade them to use the latest Citrix HDX-compatible APIs. To use Citrix HDX, you must update the voice setup function. On the audio event of Twilio Voice JavaScript SDK, you need to map the Citrix devices to connection. The following examples demonstrate how to update these calls:

1. The Twilio Voice JavaScript SDK needs three new arguments for the Twilio Voice JavaScriptJS SDK setup function: RTCPeerConnection, getUserMedia, and enumerateDevices.

   setup(data, {
       ...options,
       ...{
           RTCPeerConnection: window.CitrixWebRTC.CitrixPeerConnection.bind(window.CitrixWebRTC),
           getUserMedia: (...args: any[]) => window.CitrixWebRTC.getUserMedia(...args),
           enumerateDevices: window.CitrixWebRTC.enumerateDevices.bind(window.CitrixWebRTC),
       },
   });
   

2. Map the Citrix audio element to the voice connection by specifying the following:

   connection.on("audio", function(remoteAudio) {
       ....
       window.CitrixWebRTC.mapAudioElement(remoteAudio);
       ....
   })
   

Twilio Voice JS DSCP support

Voice Over Internet Protocol (VoIP) call quality is influenced by environmental factors, such as:

• Firewall configuration
• Network conditions
• Available bandwidth
• Browser version (for webRTC)
• Operating system
• Microphone and speaker hardware

It's important you review our deployment best practices and connectivity requirements documentation before taking your app to production. Browsers that support DSCP are able to tag call media packets sent by the voice client. Your router or network element can then use these tags to prioritize call media packets over other traffic on the network.

Verify that Flex HDX is working correctly

Follow these steps to verify that Flex HDX is working correctly in Chrome:

1. Open a new tab on the machine connected to the Citrix environment.

2. Navigate to chrome://webrtc-internals/. The page should look similar to this:

3. Log in to your Citrix account and open Flex inside Chrome from your Citrix instance.

4. Start a call.

5. The Chrome WebRTC-internals page that you opened in step 1 refreshes with a new tab on the page, representing the call that you started.

Known issues

• Unable to accept new calls after switching to a different microphone or speaker when running on Citrix environment:
  • Sometimes, there’s no audio on calls in a Citrix environment after switching from the microphone or speaker to a different device. This is rare problem and only occurs when there are multiple audio devices. We are working with Citrix to resolve this issue.
• Unable to read volume levels from the front end (Citrix issue):
  • Citrix doesn't support the native APIs that allow the Voice SDK to read volume levels programmatically. This does not impact the end user experience, but causes debugging issues. Twilio always sees logs with the volume level as zero. It isn’t possible to tell if there is a "silent" audio issue or not. The Citrix team is actively working on AudioContext support for the UC SDK.

Log Capturing

Capture your Citrix instance logs using one of the following methods:

• How to collect logs in Receiver for Chrome and Receiver for HTML5
• How to collect logs for Citrix Workspace App for Windows

Getting support

Citrix and Twilio jointly support the delivery of Flex on Citrix HDX VDI.

If you experience an issue with Flex on Citrix VDI, open a support ticket with the vendor whose product you suspect to be causing the issue. In other words, if the problem seems like a Flex issue, open a support ticket with Twilio. If you suspect it's a Citrix HDX issue, open a support ticket with Citrix. You must have an active Citrix license to receive support from Citrix.

When Citrix or Twilio receives the ticket, they will triage the issue and escalate it as appropriate. If they determine that the problem is caused by the other company’s product, they will advise you to create a support ticket with the other company.