Unified Communications SDK Context

Unified communications SDK is offered to real-time communications application vendors. Vendors integrate UCSDK to get access to Citrix stack, which they can leverage to offload and optimize their applications. 

The optimization of all the vendor applications works very similar to the HDX Teams optimization. For more context on UCSDK and the list of vendors that have integrated the SDK and have optimized solutions, visit Unified Communications SDK optimization documentation

Supported UCSDK versions

UCSDK is not packaged as a part of Citrix Virtual Apps and Desktops or Citrix DaaS. It is a private SDK that Citrix shares with its technology partners, who build it into their applications. Each vendor decides which UCSDK version its application uses and maintains that integration. If you are not sure which UCSDK version your application uses, ask the vendor.

Citrix actively supports two major versions of UCSDK at a time:

• UCSDK 5.x (latest release: 5.0.1). Recommended.
• UCSDK 4.x (latest release: 4.1.3)

Citrix delivers UCSDK fixes in upcoming releases. Released versions, including supported ones, are not updated. To get a fix, the application vendor moves to the release that has the fix (and / or) customers move to the CWA / VDA versions that have the fix.

UCSDK 3.1.0 reaches end of life on December 31, 2026. Citrix has asked application vendors that still use UCSDK 3.1.0 to move to a supported version by this date. Because each vendor maintains its own integration, a vendor can choose to continue supporting its application on UCSDK 3.1.0. After December 31, 2026, if you report an issue on an application that uses UCSDK 3.1.0 to Citrix, Citrix Support will first ask customer and application vendor to test with a supported UCSDK version. If the issue still occurs on a supported version, Citrix Support continues troubleshooting from there.

For more information, see Supported UCSDK versions in the Unified Communications SDK optimization documentation.

Troubleshooting Guidance

Recommended Troubleshooting Order

An optimized application has several layers: the vendor application, UCSDK inside that application, and the Citrix components on the VDA and the endpoint. Troubleshoot from the top down, starting with the application:

1. Contact your application vendor first. The vendor knows its application, its configuration, and its service, and can determine whether the issue involves UCSDK or the Citrix components.
2. If the vendor identifies an issue in UCSDK or the Citrix components, open a case with Citrix Support. Include the information listed in Checklist and Logs to collect in this article.

Try the latest versions first

Many issues are already fixed in later releases. If you are on older versions, test with newer versions before you open a case:

• UCSDK: Ask the vendor whether a version of the application with a newer UCSDK release (5.0.1 or 4.1.3) is available, and test with it.
• Citrix Workspace app: Test with the latest Citrix Workspace app version for the endpoint platform.
• VDA: For applications that use UCSDK 4.1.3 or later, use a VDA that supports Bootstrap: VDA 2407 or later, or VDA 2402 LTSR CU4 or later for LTSR customers. Bootstrap improves how applications, especially browser-based applications, handle session disconnects and reconnects.

Connection to WebSocketServer Fails 

If communication between the UCSDK and the CtxHdxWebSocketService(WebSocketService.exe) cannot be established, please check the following:

• Ensure the application executable name is in the Whitelist as per the instructions provided in UCSDK Tech Brief 
• Follow the guidance of the vendor documentation to ensure the application executable name is proper.
• Ensure Firewalls on the VDA allow communication through Port 9002. 
• Follow vendor guidance to ensure endpoint connectivity to the application servers for call flow

Checklist and Logs to collect (across platforms)

The primary mechanism for debugging issues in the field is analyzing the logs the system generates. When an issue happens, ensure to queue the following logs (wherever applicable), reproduce the issue and share the logs with Citrix support. The server side logs and the client side logs both need to be synchronous i.e., not from different calls / times.

Server side Logs

When you open a case with Citrix Support, include the UCSDK version the application uses and the VDA and Citrix Workspace app versions on the affected endpoint.

JS Console Log

This is the application side log that will be generated by the vendor application. As the vendor application integrates the UCSDK, the vendor application log will usually contain the UCSDK logs as well. Refer the appropriate vendor documentation to find out how to collect the application console logs that includes the UCSDK logs. Citrix support requires UCSDK logs to troubleshoot and triage the issue. For example, Amazon Connect integrates UCSDK. As Amazon Connect is a web app, the UCSDK logs are generated in the browser console logs. Make sure to select verbose in the browser console for full logging. For other vendors, there might be different ways in which this log is generated.

On VDA 2507 and later, you can also collect the UCSDK log directly from the VDA, without using the vendor's log tools. The log is in the following location in the user session:

%temp%\Citrix\CitrixWebRTCSDK\<vendor_name>\<process_name>\<timestamp>\shim.log

The folder names depend on the vendor and on the application process. Use the folder whose timestamp matches the time of the issue.

Citrix VDA CDF Logs 

CDFControl is common tool that is used for most Citrix component log capturing. The following trace provider modules need to be enabled to capture Webrtc redirection related logs on VDA.

• HDX_Multimedia_TeamsService
• HDX_Multimedia_WebSocketAgent
• HDX_Multimedia_WebSocketPipe
• HDX_Multimedia_WebSocketService 

Client side Logs

Client Endpoint CDF Logs

 The following trace provider modules need to be enabled to capture Webrtc redirection related logs on client endpoint.

• IcaClient_DriverVd_TeamsRedir
• IcaClient_Multimedia_HdxTeams 

Windows Client Endpoint webrpc and webrtc Logs

Citrix Webrtc redirection engine HdxRtcEngine.exe that runs on the client endpoint also provides additional logs in a text format. It is located under the following path. Whenever HdxRtcEngine.exe process is launched, if configured properly, a new webrpc.log and webrtc_# log files are created under relevant time stamp directory: %Temp%\HdxRtcEngine.

The log levels can be adjusted via a registry key on the client endpoint. Default log level is 2, however, more verbose debug/trace level logs can be captured by setting this value to 1(debug) or 0(trace). 

• Key Path: HKCU\Software\Citrix\HDXMediaStream
•  Key Name: WebrpcLogLevel
•  Key Type: DWORD
•  Key Value:
  • 0 indicates all logs up to trace level
  • 1 indicates all logs up to debug
  • level 2 indicates all logs up to error level.

Note: Make sure to enable the trace level logging so that Citrix support has detailed log information. Revert the log level to 2 once logs are collected

Linux Client Endpoint webrpc and webrtc Logs

On Linux endpoint, log levels can be adjusted via a config file. Whenever HdxRtcEngine.exe process is launched, if configured properly, a new webrpc.log and webrtc_# log files are created under relevant time stamp directory: /tmp/hdxrtcengine.

Create /var/.config/citrix/hdx_rtc_engine/config.json file and add configuration keys in JSON format, eg:

{
“WebrtcLogLevel” : 0,
“WebrpcLogLevel” : 0
}

Note: As Thin Clients come in many flavors and might be locked down, ensure to ask your Thin client vendor how to pull the logs out of the system.

MacOS Endpoint webrpc and webrtc Logs

On Mac endpoint, log levels can be adjusted via a command. Whenever HdxRtcEngine.exe process is launched, if configured properly, a new webrpc.log and webrtc_# log files are created under relevant time stamp directory: .~/Library/Logs/HdxRtcEngine/

Execute defaults write command with configuration keys, eg: 

defaults write com.citrix.HdxRtcEngine WebrpcLogLevel -int 0
defaults write com.citrix.HdxRtcEngine WebrtcLogLevel -int 0

ChromeOS Endpoint Logs

1. For CWA Chrome App, instructions to collect client log is here
2. For CWA HTML5, instructions to collect client log is here 
3. Here is how to collect WebRTC dump files
   • 1 - Open chrome://webrtc-internals in a tab inside the Chrome browser to start the dump files collection.
   • 2 - Re-produce your issue, but DON’T end the call or meeting
   • 3 - Click the "Create a WebRTC-Internals dump" in the chrome://webrtc-internals/ tab
   • 4 - Click on the ‘Download the "webrtc-internals dump"’ button to collect dump files
   • 5 - Close the call or meeting