Menu

Flex Citrix VDI

Overview

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

Flex UI 2.3.2 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 directly connects from the agent's machine to Twilio Programmable Voice.

Technical diagrams of Flex Citrix VDI architecture


Solution with HDX on Citrix VDI

Image of architecure for HDX on Citrix VDI.

Voice flow with Citrix VDI and Standard Voice SDK

Image demonstrating Voice flow with Citrix VDI and Standard Voice SDK.

Flex Citrix VDI only applies to voice calls.

System requirements

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

Citrix server


Remote device

  • Operating System
    • Windows 10 or above
    • Mac OS
  • Browser (latest version)
    • Google Chrome, or
    • Microsoft Edge

Supported browsers

Latest version:

  • Google Chrome
  • Microsoft Edge

Set up Flex on Citrix VDI

To get Flex working on Citrix VDI, complete the following steps:

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

Note: If you are unable to change the registry value or are facing permission issues, contact your Citrix administrator.

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): Citrix has issues with HDX content redirection with Chrome browser 105 and higher. 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.
    The issue is fixed on the following Citrix versions:
    • Versions after CVAD 2212
    • CVAD 1912 CU7
    • CVAD 2203 CU2
  4. Verify that you’ve disabled the Chrome Browser Chrome Root Store certificate by following the steps in the Chrome Root Store and Certificate Verifier

Enable the VDI support feature flag

This feature is currently in public beta. You can enable this feature as follows:

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

Flex feature settings

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.3.2

Upgrade the @twilio/voice-sdk

Upgrade @twilio/voice-sdk to version 2.5 or above for support with the Citrix HDX compatible webRTC APIs.

npm install @twilio/voice-sdk@2.5

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

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.

4. 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");
}

citrix-vdi-step-7-reso

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:
      • Step 3.1 in this document is followed properly.
      • 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. See below for examples of 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
  • Hardware (microphone and speaker)

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 needs to be DSCP compliant.
  • DSCP is only supported by Google Chrome.
  • Citrix VDI supports DSCP used by the Voice SDK.

Verify Flex HDX

Follow these steps to verify Flex 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 the screenshot below.

validate Flex HDX image

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

4. Start a call.

5. Once you start a call, the tab opened in Step 1 refreshes representing the call started in Step 4.

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

For more information on how to capture Citrix instance logs, check out the following resources:

Rate this page:

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.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

thanks-feedback-gif