Help and FAQ

Getting started

You need a Find X9 and either Shizuku or a USB cable and computer. No root or paid tools are required. Other devices and ColorOS versions may behave differently.

First, download SnapKeyMap-*.apk from the latest release and open it. Allow your browser or file manager to install apps when Android asks. No GitHub account is needed.

Open SnapKey Map to start the seven-step wizard. It saves your progress and resumes at the first unfinished step; optional skips are saved too.

1. Choose a method

   Choose Shizuku for setup without a computer, or Computer (ADB) for one command over USB.

2. Give log access

   Follow the instructions for your chosen method. Keep Shizuku running and allow SnapKey Map in it for prompt-free reading. Otherwise, choose Allow when Android asks for device logs.

3. Turn on accessibility

   Tap Open accessibility settings and turn on SnapKey Map. Even with ADB or Shizuku, the service runs accessibility actions, opens apps and the device-logs prompt from the background, receives supported key events, and helps keep the app running. It cannot read screen content. If Android blocks the switch, open App info, tap the three-dot menu, choose Allow restricted settings, then retry.

4. Background operation (optional)

   Allow the battery-optimisation exemption to reduce ColorOS interruptions, or tap Skip. This does not guarantee background detection.

5. Notifications (optional)

   Allow alerts when detection pauses, or tap Skip. Actions do not need notification permission.

6. Teach the key

   Set Oppo's own Snap Key action to None in phone Settings. Start teaching, press three times when asked, then hold once.

7. Choose actions

   Tap Press, Double press, or Press & hold and keep at least one action assigned. Tap Finish, test each gesture, and check Last: on the home screen.

Use Help > Run setup again to revisit the wizard without clearing mappings. Existing installations with a taught key and granted log permission go straight to the home screen.

With a computer

This grants log access once. Android can still ask for device-log consent when the reader reconnects.

1. Download Google's free SDK Platform-Tools and unzip them.
2. On the phone, open Settings > About device > Version. Tap the build or version number seven times to enable Developer options.
3. Turn on USB debugging in Developer options.
4. Connect the phone with a USB cable. Accept the debugging prompt on the phone.
5. Open a terminal in the unzipped platform-tools folder and run:

adb shell pm grant com.heykay.snapkeymap android.permission.READ_LOGS

In Windows PowerShell, use .\adb instead of adb if it is not on your PATH. Success normally returns to the command prompt without a message.

Reopen SnapKey Map and allow device logs. The grant survives restarts and app updates. If the command reports GRANT_RUNTIME_PERMISSIONS, use the ColorOS fix below.

Without a computer

1. Install Shizuku and follow its Wireless debugging pairing and start instructions. Wireless debugging requires Android 11 or later.
2. In the wizard, choose Shizuku and continue to log access. Once Shizuku is running, tap Grant with Shizuku and allow the Shizuku permission request. The button is enabled only while Shizuku is running.
3. Keep Shizuku running. While SnapKey Map is allowed in it, the app reads logs through Shizuku without Android's device-logs prompt.

If ColorOS blocks the grant, follow the permission monitoring fix, restart the phone, start Shizuku again, and retry.

Shizuku must be running for prompt-free reading. Otherwise Android asks for one-time device-log access after each app or phone restart and may ask again when the reader reconnects. The accessibility service tries to show the prompt automatically. If ColorOS blocks it, reopen SnapKey Map and allow device logs.

Manual fallback with aShell

If needed, open aShell while Shizuku is running and allow aShell to use Shizuku. Run the same permission grant directly in its shell, without the adb shell prefix:

pm grant com.heykay.snapkeymap android.permission.READ_LOGS

Return to SnapKey Map and allow device logs. aShell cannot bypass ColorOS permission monitoring either.

Teaching the key

First set Settings > Snap Key to None. Otherwise Oppo's action may run as well as yours.

In SnapKey Map, start Teach the app your Snap Key. Follow the hands-off prompt, press the key three times when asked, then hold it once. Keep the app open throughout.

To repeat teaching, choose Teach the Snap Key again on the home screen; to revisit the full wizard, choose Run setup again in Help. Your action assignments stay unchanged. After updating from v1.0.3 or earlier, teach it again before testing. Older calibration can select a message that matches only key-down events and merges double presses. Current learning prefers the known Oppo press-and-release source when present.

Choosing actions

Tap Press, Double press, or Press & hold on the home screen. Choose an app, supported shortcut, link, or device action. Test it and check the Last: text in the Ready card.

• A double-press assignment adds a 350 ms wait after release before the single-press action runs.
• The known Find X9 log reports press and release edges. Other learned log formats need repeated events while held to detect a hold.
• The shortcut picker supports apps that offer ACTION_CREATE_SHORTCUT, not every pinned shortcut. Try a deep link instead. Direct-dial shortcuts are not supported because the app has no calling permission.
• Silent mode and Do Not Disturb need notification policy access. Without it, the ringer action cycles between ring and vibrate.
• Android permissions, device support, and the lock screen still apply. The app cannot bypass the lock screen. Screen-off detection and background reliability depend on ColorOS.

Troubleshooting

Still stuck? Open an issue with the app version, ColorOS version, assignments, and Last: text. Do not share an unfiltered system log. It can contain sensitive information.

Is it safe?

READ_LOGS granted over adb is a powerful permission. Give it only to apps you trust. It grants access to the whole live system log, not just the Snap Key.

What stays on the phone

The app declares no INTERNET permission. It does not send logs or settings off the phone. Apps and websites you open through an action handle their own data and have their own privacy policies.

The reader checks incoming log lines in memory. It does not save a log file. Outside teaching, matching lines drive key detection and other lines are discarded.

If you allow SnapKey Map in Shizuku, the app also uses Shizuku to run logcat as the shell user. Shizuku must be running for this. Lines are still checked in memory and discarded, with the teaching exception below. Shizuku is not used to run mapped actions.

During teaching, it temporarily keeps observations in memory: an arrival time, log tag, normalized message, and writer UID. Runs of message digits are replaced with #, and the message is trimmed and limited to 160 characters. This does not remove all sensitive text. Tags and UIDs are retained. Accessibility key-code observations can also be kept during teaching.

After learning, the app saves one selected log signature, not the collected log: the tag, normalized message, and writer UID, plus hold detection and release timing settings. If Android supplies a usable key event instead, it saves the key and scan codes rather than a log signature. The observation list is not written to storage and is released after learning finishes or is cancelled.

How key lines are checked

A learned key line must match the writer UID recorded during teaching, as well as the tag and normalized message. The known Oppo key line is accepted only from the system UID, 1000. Other apps cannot fake a Snap Key press just by writing the same line under their own UID.

Accessibility and settings

The accessibility service can receive supported key events and perform device actions. Its configuration sets canRetrieveWindowContent="false", so it cannot read window content.

Settings use private app storage. Android backup is disabled with allowBackup="false". Mappings and the learned key are not included in Android backups.

Declared permissions

The app's permission list contains:

• Read device logs (READ_LOGS): detect the Snap Key in the live system log.
• Vibrate (VIBRATE): give feedback when an assigned action runs.
• Show notifications (POST_NOTIFICATIONS): tell you when detection pauses.
• Access notification policy (ACCESS_NOTIFICATION_POLICY): use Do Not Disturb and silent-mode controls.
• Ask to ignore battery optimisation (REQUEST_IGNORE_BATTERY_OPTIMIZATIONS): request background operation.
• Shizuku API access (moe.shizuku.manager.permission.API_V23): lets the app ask Shizuku for the one-time log permission grant and run logcat as the shell user while Shizuku is running. This avoids the device-logs prompt. Without it, Android asks for one-time access after each app or phone restart and may ask again on reconnect. Mapped actions do not use Shizuku.
• Internal receiver permission (com.heykay.snapkeymap.DYNAMIC_RECEIVER_NOT_EXPORTED_PERMISSION): added by the AndroidX library. Only this app holds it, and it keeps other apps from sending broadcasts to the app's private receivers.

The code is open source. You can inspect the implementation and build it yourself.

Provided as is, without warranty.

Updates and removal

Install the new APK over the old app. Do not uninstall first. Updates signed with the same key keep settings and the granted log permission. Android may still ask for device-log consent when the reader reconnects.

Uninstalling removes the app's settings and log permission. If you reinstall, grant log access and teach the key again.