Before you start
Keep the first test small and repeatable.
- A physical device with a documented target key and an approved deployment policy.
- A recovery path that does not depend on the remapped key.
- An explicit decision about whether the change is app-level or device-level.
Step by step
Build it in 4 deliberate passes.
Each pass produces a checkable result. Keep device-specific calls in the adapter and keep the workflow portable.
- 01
Decide the smallest control surface
Use application-level key handling when the workflow can stay inside the app. Use device-level mapping only when the deployment policy and model support it.
- 02
Snapshot before changing
Read and store the original key code, action and interception state in a controlled deployment record. Never assume the factory mapping is identical across variants.
- 03
Map one key at a time
Apply one reversible change, verify it in the target workflow and keep navigation, emergency, payment and system keys outside the demo.
- 04
Restore and reboot
Verify restore, reboot persistence, factory reset behavior and a physical recovery procedure. A successful remap without recovery is not deployment-ready.
Copyable pattern / Kotlin
Start with the boundary, then bind the device.
The public example models safe state transitions; actual device-level mapping remains model- and policy-specific.
data class KeySnapshot(
val keyCode: Int,
val action: String?,
val intercepted: Boolean,
)
interface KeyPort {
fun snapshot(keyCode: Int): KeySnapshot
fun apply(keyCode: Int, action: String)
fun restore(snapshot: KeySnapshot)
}
fun applyTemporaryMapping(port: KeyPort, keyCode: Int, action: String) {
val original = port.snapshot(keyCode)
try {
port.apply(keyCode, action)
// Verify the workflow here before the device leaves the lab.
} catch (error: Throwable) {
port.restore(original)
throw error
}
}When the happy path breaks
Make recovery part of the first implementation.
Operators experience the failure state, not the API call. Translate device signals into a useful next action.
Stop and record the model-specific limitation; do not write a guessed mapping.
Use the physical recovery path, restore the snapshot and remove the mapping from deployment.
Mark it session-only and move persistence into the deployment configuration if approved.
Before you ship
Use this checklist on the target configuration.
- 01
Record the original mapping and test a restore before applying the change.
- 02
Verify the action in foreground, background, reboot and reset scenarios.
- 03
Confirm system navigation and emergency behavior remain available.
- 04
Keep a recovery instruction beside the device during the test.
Further reading
Use platform guidance for the parts the device SDK does not own.
These references cover Android lifecycle, broadcast, testing and architecture patterns. Device-specific compatibility still needs a model-level validation record.