Keyboard settings for Windows VDA sessions

Last published : Nov 17, 2026
This article describes the recommended keyboard settings when you connect an external hardware keyboard to an iPad and use Citrix Workspace™ app for iOS to access a Windows Virtual Delivery Agent (VDA) session. The article covers Windows-layout keyboards and the Apple Magic Keyboard. It also explains how Citrix Workspace app converts keystrokes into characters in the virtual session.
The recommendations are grouped by the following language categories:
  • US English
  • European and other languages
  • Chinese, Japanese, and Korean (CJK)
The recommended settings depend mainly on the keyboard language. The keyboard type matters only for languages where the Apple and Windows keyboard layouts differ. For all languages, enable the Keyboard Layout Sync option. This option is disabled by default.
The following table lists the recommended External Keyboard Input Mode for each language and keyboard type:
Language Windows keyboard Apple keyboard Dual keyboards
US English Scancode Scancode Scancode
European and other languages, for example, UK English, German, French, Spanish, Italian, Nordic languages, Russian, Greek, Arabic, Hebrew, and Thai Scancode Unicode Scancode
Chinese, Japanese, and Korean Unicode (client IME) Unicode (client IME) Unicode (client IME)
By default, the input mode is set to Automatic, which uses Unicode when you connect to a Windows VDA. So, you must change the input mode only where Scancode is recommended.
For more information, see Settings by language. For the reasons behind these recommendations, see How keyboard input works.
Notes:
  • Keep the iPadOS Modifier Keys settings at their default values for every keyboard.
  • If you use a keyboard that is neither a Windows keyboard nor an Apple keyboard, follow the Windows keyboard recommendations.

Configure keyboard settings

To get the recommended keyboard experience, configure Citrix Workspace app, iPadOS, and the Windows VDA.

Configure Citrix Workspace app

Enable keyboard layout synchronization

To enable keyboard layout synchronization, do the following steps:
  1. Open Citrix Workspace app for iOS and navigate to Settings > Keyboard Options.
  2. Enable the Keyboard Layout Sync option.

Set the input mode for external keyboards

To set the input mode for external keyboards, do the following steps:
  1. Navigate to Settings > Keyboard Options.
  2. Tap External Keyboard Input Mode.
  3. Select one of the following options:
    • Automatic: Selects the input mode based on the session type. Uses Unicode when you connect to a Windows VDA.
    • Scancode: Applies the server-side keyboard layout.
    • Unicode: Applies the client-side keyboard layout.
Notes:
  • By default, Automatic is selected, which is converted to Unicode when you connect to a Windows VDA.
  • The input mode applies to all external keyboards connected to the iPad.
  • Unicode is the preferred mode when you use a touch keyboard, because the keys on a touch keyboard generally don't generate a scancode.

Assign a key for Alt in the session

To assign a key for Alt in the session, do the following steps:
  1. Navigate to Settings > Keyboard Options > Assign Key for Alt in session.
  2. Select one of the following options:
    • Option or Alt (left) (default)
    • Option or Alt (Right)
    • Option or Alt (left and right)
    • Command or Windows (left)
Note:
The Option or Alt (Right) option is available starting with the 24.12.0 version.

Configure iPadOS

To set the hardware keyboard layout on the iPad, do the following steps:
  1. Navigate to iOS Settings > General > Keyboard > Hardware Keyboard.
  2. Tap the language of your keyboard. If the language isn't listed, add it first in Keyboards > Add New Keyboard.
  3. Select the layout that matches the characters printed on the keycaps.
If you switch between languages, you can optionally navigate to iOS Settings > General > Keyboard and set Press 🌐 key to to Change Input Source.
Important:
  • Don't swap the Control and Command keys in Hardware Keyboard > Modifier Keys. If you swap these keys, the Ctrl key doesn't work as Ctrl in the virtual session.
  • If your Magic Keyboard doesn't have an Esc key, you can map Caps Lock to Escape.
  • Modifier key settings apply to each keyboard separately.

Configure the Windows VDA

Prerequisites

  • The VDA must be version 7.16 or later.
  • Enable the Unicode Keyboard Layout Mapping, Client Keyboard Layout Sync, and IME Improvement policies on the Windows VDA.
  • Install the Windows keyboard layouts that your users require on the VDA.
Alternatively, you can enable the policies by setting the following registry values on the Windows VDA:
HKLM\Software\Citrix\ICA\IcaIme\DisableKeyboardSync value = DWORD 0
HKLM\Software\Citrix\CtxKlMap\EnableKlMap value = DWORD 1
HKLM\Software\Citrix\CtxKlMap\DisableWindowHook value = DWORD 1

Settings by language

The External Keyboard Input Mode, Keyboard Layout Sync, and Assign Key for Alt in session settings apply to all connected keyboards. If you use a Windows keyboard and a Magic Keyboard with the same iPad, use the settings recommended for Dual keyboards.

US English

Keyboard External Keyboard Input Mode Keyboard Layout Sync
Windows keyboard Scancode Enabled
Magic Keyboard Scancode Enabled
Dual keyboards Scancode Enabled
The Apple and Windows US keyboard layouts are effectively the same. So, every key produces the character printed on the keycap with both keyboard types. In Scancode mode, Citrix Workspace app sends key positions to the VDA. As a result, keyboard shortcuts and apps that read raw key input work the same way as on a Windows PC.
Note:
Unicode mode also produces the correct characters for US English. Use Unicode if your users also type with the touch keyboard or use iPad dictation.

European and other languages

This category includes languages such as UK English, German, French, Spanish, Italian, Swedish, Norwegian, Danish, Finnish, Russian, Greek, Arabic, Hebrew, and Thai.
Keyboard External Keyboard Input Mode Keyboard Layout Sync
Windows keyboard Scancode Enabled
Magic Keyboard Unicode Enabled
Dual keyboards Scancode Enabled
For these languages, the Apple and Windows keyboard layouts differ. For example, on many European layouts, letters, numbers, and Shift characters are in the same positions, but some symbols such as @, €, { } [ ], and \ | aren't.
  • Windows keyboard: Scancode mode applies the Windows layout on the VDA. So, the characters match the keycaps, and keyboard shortcuts work the same way as on a Windows PC.
  • Magic Keyboard: Unicode mode applies the Apple layout on the iPad. So, the characters match the keycaps.
  • Dual keyboards: Scancode mode applies the Windows layout to Dual keyboards. The characters match the keycaps on the Windows keyboard. On the Magic Keyboard, some symbols follow the Windows key positions instead of the positions printed on the keycaps.

Chinese, Japanese, and Korean

Keyboard External Keyboard Input Mode Keyboard Layout Sync
Windows keyboard Unicode Enabled (required)
Magic Keyboard Unicode Enabled (required)
Dual keyboards Unicode Enabled (required)
For CJK languages, the keyboard type doesn't affect the recommendation. Citrix recommends that you use Generic Client IME, which uses the Input Method Editor (IME) on the iPad. Generic Client IME:
  • Requires keyboard layout synchronization.
  • Is supported only on Windows VDAs.
  • Supports both soft keyboards and external physical keyboards.
  • Moves the composition window and the candidate window with the input cursor in the session.
For more information, see Generic Client IME for East Asian languages.
To use the Windows IME on the VDA instead, clear the local keyboard layout option in Preferences > Keyboard. In this case, Scancode mode applies the VDA keyboard layout, which can improve the typing experience in East Asian languages.

Switch between languages

If you type in more than one language, do the following:
  1. Add each language in iOS Settings > General > Keyboard > Keyboards.
  2. Set Press 🌐 key to to Change Input Source.
Always switch languages on the iPad, not inside the Windows session. When keyboard layout synchronization is enabled, the session keyboard layout follows the iPad.
Note:
The External Keyboard Input Mode setting doesn't change when you switch languages. If the languages that you use have different recommendations, for example, US English and German on a Magic Keyboard, choose the input mode for the language that you type most often, or use Unicode.

Use case: Press the Globe key

Consider a scenario where you use a German Magic Keyboard in Scancode mode with keyboard layout synchronization enabled. The iPad has German (active) and English (US) input languages.
When you press the Globe key, the following happens:
  1. iPadOS handles the Globe key as a system key. The key isn't sent to Citrix Workspace app.
  2. iPadOS changes the active input language from German to English (US).
  3. Citrix Workspace app detects the change, displays English (US) in the session, and synchronizes the layout to the VDA.
  4. The VDA changes the session keyboard layout from German to US.
No character is produced. The input mode has no effect because the Globe key doesn't reach the session.

Use case: Press a character key after the language change

After you press the Globe key, you press the key labeled Z on the German Magic Keyboard. The following table compares the result before and after the language change:
Step Before the Globe key press (German) After the Globe key press (English US)
Key pressed Key labeled Z Key labeled Z
Sent by Citrix Workspace app Scancode 0x15 Scancode 0x15
VDA keyboard layout German US
Character produced z (matches the keycap) y (doesn't match the keycap)
In Scancode mode, the key position remains the same and the VDA keyboard layout determines the character. Unicode mode also produces y, but iPadOS determines the character instead of the VDA.

How keyboard input works

This section describes how keyboard input works for all languages.

Scancode and Unicode input modes

Starting with the 24.1.0 version, Citrix Workspace app for iOS supports the Scancode input mode for external physical keyboards. The following table compares the Scancode and Unicode input modes:
Attribute Scancode Unicode
Data sent to the VDA Key position Character
Where the character is determined VDA, using the Windows keyboard layout iPad, using the iPadOS keyboard layout
Characters match the keycaps of Windows keyboards Apple keyboards
Keyboard shortcuts and apps that read raw key input Fully supported Most shortcuts work. Apps that read raw keys might not work as expected.
IME Windows IME on the VDA Client IME on the iPad
For example, consider a scenario where you use a US international keyboard:
  • In Scancode mode, Citrix Workspace app sends the scancode 1E, and the VDA displays a according to its keyboard layout.
  • In Unicode mode, Citrix Workspace app sends the character a, regardless of the VDA keyboard layout.
Note:
Keep keyboard layout synchronization enabled in Unicode mode too. Keys that don't produce characters, such as Enter, arrow keys, function keys, and modifier keys, are sent to the VDA as key codes and are interpreted using the VDA keyboard layout. Generic Client IME also requires keyboard layout synchronization.

Keyboard layout synchronization

Keyboard layout synchronization sets the session keyboard layout to match the active input language on the iPad. Citrix Workspace app maps the iOS keyboard layout to the matching Windows keyboard layout. For example, English (US) maps to US keyboard, and Japanese maps to Citrix IME - Japanese. For the complete mapping table, see Keyboard layout synchronization.
  • iPadOS uses one active input language at a time. All connected keyboards, including the touch keyboard, use the same language. The keyboard that you type on doesn't affect the synchronized layout.
  • Starting with the 24.7.0 version, when you change the keyboard language using the Globe key, Citrix Workspace app displays the current keyboard language in the virtual session.
  • Change the input language on the iPad, not inside the Windows session. The session keyboard layout follows the iPad.

Limitations

  • Some Magic Keyboard models don't have the Esc, Insert, Print Screen, or number pad keys. To send these keys, use the extended keyboard toolbar.