Back to top

Unmanaged key mappings

Last updated May 17th, 2024

A device user can associate configurable XCover device keys with business apps registered in Settings > Advanced Settings > XCover / Top key, by toggling the Control XCover / Top key with app option:

xcover-key-mapping.jpg

As an ISV, you can set up your app so that it is listed and can be mapped to a key. To do so, simply:

  1. Ensure your app includes logic to receive and handle XCover and Top key intents.
  2. Include metadata in your AndroidManifest.xml file to activate the Control XCover / Top key with app options in the device Settings.

Handle hardware key intents (Samsung standard intent only)

To handle hardware key intents, your business app simply needs to implement a broadcast receiver for XCover and Top key intents as transmitted by the Knox framework. It is then entirely up to your app to handle hardware key logic and behavior.

Constants

The Knox SDK predefines these constant values, which you use to identify keys and key presses:

Constant Value
Public static final int KEYCODE_PTT 1015 (0x000003f7)
Public static final int KEYCODE_EMERGENCY 1079 (0x00000437)
Public static final int KEY_ACTION_DOWN (key press) 1 (0x00000001)
Public static final int KEY_ACTION_UP (key release) 2 (0x00000002)

XCover key intent

When a user presses or releases the XCover key, the device framework transmits an intent with the following properties:

Action "com.samsung.android.knox.intent.action.HARD_KEY_REPORT"
Extra key strings

"com.samsung.android.knox.intent.extra.KEY_CODE"

"com.samsung.android.knox.intent.extra.KEY_REPORT_TYPE"

Here is some example code that parses the intent for the XCover key and checks whether the key has been pressed or released:

String intentAction = intent.getAction();
if ("com.samsung.android.knox.intent.action.HARD_KEY_REPORT".equals(intentAction)) {
  int keyCode = intent.getExtra(com.samsung.android.knox.intent.extra.KEY_CODE)
  int keyReportType = intent.getExtra(com.samsung.android.knox.intent.extra.KEY_REPORT_TYPE)
  if (keyCode == KEYCODE_PTT && keyReportType == 1) {
    // XCover key pressed
  }
  else if (keyCode == KEYCODE_PTT && keyReportType == 2) {
    // XCover key released 
  }
}

Top key intent

When a user presses or releases the Top key, the device framework transmits an intent with the following properties:

Action "com.samsung.android.knox.intent.action.HARD_KEY_REPORT"
Extra key strings

"com.samsung.android.knox.intent.extra.KEY_CODE"

"com.samsung.android.knox.intent.extra.KEY_REPORT_TYPE"

Below is some example code that parses the intent for the Top key and checks whether the key has been pressed or released:

String intentAction = intent.getAction();
if ("com.samsung.android.knox.intent.action.HARD_KEY_REPORT".equals(intentAction)) {
  int keyCode = intent.getExtra(com.samsung.android.knox.intent.extra.KEY_CODE)
  int keyReportType = intent.getExtra(com.samsung.android.knox.intent.extra.KEY_REPORT_TYPE)
  if (keyCode == KEYCODE_EMERGENCY && keyReportType == 1) {
    // Top key pressed
  }
  else if (keyCode == KEYCODE_EMERGENCY && keyReportType == 2) {
    // Top key released 
  }
}

Register an app in the Settings

To register your business app in the list of Control XCover/Top key with app setting options, include the following metadata in your AndroidManifext.xml file:

<meta-data
  android:name="com.samsung.android.knox.intent.action.HARD_KEY_PRESS"
  android:value="true" />
<receiver android:name=".receiver" android:exported="true">
  <intent-filter>
    <action android:name="com.samsung.android.knox.intent.action.HARD_KEY_REPORT" />
  </intent-filter>
</receiver>

After installing your compiled app on an XCover device, you should see it in the list of apps that can be mapped to an XCover or Top key.

Is this page helpful?