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.
Technical diagrams of Flex on Citrix VDI architecture
Solution with Flex on Citrix VDI
Voice flow with Citrix VDI and Standard Voice SDK
Flex on Citrix VDI applies only to voice calls.
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:
Set up the Citrix VDI environment
Changes to the Citrix VDI environment require a user with Administrative privileges.
Note: If you are unable to change the registry value or are facing permission issues, contact your Citrix administrator.
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:
- 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
- Restart CtxHdxWebSocketService to enable Citrix HDX support for Chrome. To do this, open Task Manager, right-click CtxHdxWebSocketService, and select Restart.
- (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:
- Navigate to https://flex.twilio.com/admin/features.
- 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:
Protocol |
Port |
Reason |
TCP,UDP |
1494 |
Access to applications and virtual desktops by ICA/HDX. EDT protocol requires port 1494 to be open for UDP. |
TCP,UDP |
2598 |
Access to applications and virtual desktops by ICA/HDX with Session Reliability. EDT protocol requires port 2598 to be open for UDP. |
TCP,UDP |
443 |
Access to applications and virtual desktops by ICA/HDX over TLS/DTLS. |
UDP |
16500..16509 |
ICA/HDX audio over UDP Real-time Transport. |
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.
- This message means Flex is unable to connect to the Citrix HDX package. This problem can be caused by any of the following issues:
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:
- The Twilio Voice JavaScript SDK needs three new arguments for the Twilio Voice JavaScriptJS SDK setup function:
RTCPeerConnection
,getUserMedia
, andenumerateDevices
.setup(data, { ...options, ...{ RTCPeerConnection: window.CitrixWebRTC.CitrixPeerConnection.bind(window.CitrixWebRTC), getUserMedia: (...args: any[]) => window.CitrixWebRTC.getUserMedia(...args), enumerateDevices: window.CitrixWebRTC.enumerateDevices.bind(window.CitrixWebRTC), }, });
- 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.
- Your router or network element must be DSCP-compliant.
- DSCP is only supported by Google Chrome.
- Citrix VDI supports DSCP used by the Voice SDK.
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:
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.
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.