Skip to contentSkip to navigationSkip to topbar
On this page

Flex on Citrix VDI



Overview

overview page anchor

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(link takes you to an external page) 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.

(information)

Info

Flex on Citrix VDI applies only to voice calls.


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

Citrix server

citrix-server page anchor
  • One of the following operating systems:

    • Windows 10 or later
    • macOS
    • ChromeOS 122.0.6261.137 or later
  • The latest version of one of the following browsers:

    • Google Chrome
    • Microsoft Edge

Set up Flex on Citrix VDI

set-up-flex-on-citrix-vdi page anchor

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

set-up-the-citrix-vdi-environment page anchor

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

(information)

Info

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:

  1. Add the application binary name, chrome.exe, to an allowlist registry in Windows Registry Editor(link takes you to an external page):

    Key PathHKLM\Software\WOW6432Node\Citrix\WebSocketService
    Key NameProcessWhitelist
    Key TypeMULTISZ
    Key Valuechrome.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(link takes you to an external 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(link takes you to an external page).
    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

enable-the-flex-on-citrix-vdi-feature-flag page anchor

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

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

Open the following ports on the Citrix machine:

ProtocolPortReason
TCP,UDP1494Access to applications and virtual desktops by ICA/HDX. EDT protocol requires port 1494 to be open for UDP.
TCP,UDP2598Access to applications and virtual desktops by ICA/HDX with Session Reliability. EDT protocol requires port 2598 to be open for UDP.
TCP,UDP443Access to applications and virtual desktops by ICA/HDX over TLS/DTLS.
UDP16500..16509ICA/HDX audio over UDP Real-time Transport.

Self-hosted Flex only: Upgrade the Flex UI library

self-hosted-flex-only-upgrade-the-flex-ui-library page anchor

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

Upgrade the flex-ui v1 library to the latest version

upgrade-the-flex-ui-v1-library-to-the-latest-version page anchor
  1. Download the latest version from the NPM registry(link takes you to an external page) .
  2. Run the following command in your Flex project:
npm install flex-ui@2.5.0

Upgrade the @twilio/voice-sdk

upgrade-the-twiliovoice-sdk page anchor

If you are using @twilio/voice-sdk(link takes you to an external page), 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

validate-the-citrix-setup page anchor

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.
  4. Open the Chrome developer tools(link takes you to an external page) and switch to the Console tab in the developer tools.
  5. Wait until the log messages slow down in the console.
  6. Paste the following code snippet into the console, then press Enter.
1
const citrixSocket = new WebSocket("wss://127.0.0.1:9002");
2
citrixSocket.onopen = (event) => {
3
citrixSocket.send(
4
JSON.stringify({
5
v: "webrtc",
6
hdr: {
7
version: 1,
8
msg_type: "req",
9
modifier: false,
10
destroy: false,
11
proc: { iid: 0, methodid: 2 }
12
},
13
objref: { oid: 0 },
14
params: [[]]
15
})
16
);
17
};
18
citrixSocket.onmessage = (event) => {
19
const msg = JSON.parse(event.data);
20
if ( msg.command === "feature-support" ) {
21
console.log("Success : We are in Citrix with webrtc support");
22
alert("Success : We are in Citrix with webrtc support");
23
citrixSocket.close();
24
}
25
};
26
citrixSocket.onclose = ()=> console.log("Socket successfully closed")
27
citrixSocket.onerror = ()=> {
28
console.log("Failure : Error opening socket");
29
alert("Failure : Error opening socket");
30
}
31
Citrix VDI step 7.
  1. 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

twilio-voice-javascript-sdk-changes page anchor

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(link takes you to an external page). 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.

    1
    setup(data, {
    2
    ...options,
    3
    ...{
    4
    RTCPeerConnection: window.CitrixWebRTC.CitrixPeerConnection.bind(window.CitrixWebRTC),
    5
    getUserMedia: (...args: any[]) => window.CitrixWebRTC.getUserMedia(...args),
    6
    enumerateDevices: window.CitrixWebRTC.enumerateDevices.bind(window.CitrixWebRTC),
    7
    },
    8
    });
    9
  2. Map the Citrix audio element to the voice connection by specifying the following:

    1
    connection.on("audio", function(remoteAudio) {
    2
    ....
    3
    window.CitrixWebRTC.mapAudioElement(remoteAudio);
    4
    ....
    5
    })
    6

Twilio Voice JS DSCP support

twilio-voice-js-dscp-support page anchor

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(link takes you to an external page) and connectivity requirements documentation(link takes you to an external page) 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.

(information)

Info

  • 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

verify-that-flex-hdx-is-working-correctly page anchor

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:
validate Flex HDX.
  1. Log in to your Citrix account and open Flex inside Chrome from your Citrix instance.
  2. Start a call.
  3. 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.

  • 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(link takes you to an external page) support for the UC SDK.

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


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(link takes you to an external page). If you suspect it's a Citrix HDX issue, open a support ticket with Citrix(link takes you to an external page). 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?

Terms of service

Copyright © 2024 Twilio Inc.