Kiosk pinned app exits to Android "Display over other apps" settings screen during POS workflow

Android

If your Point of Sale (POS) app unexpectedly exits kiosk mode and displays Android's "Display over other apps" settings screen during a refund or emulated receipt workflow, this article will help you diagnose and resolve the issue.

Understand the issue

When running a POS app in Esper kiosk mode, the app may exit the foreground during specific workflows—such as processing a refund with an emulated receipt—and launch the Android Settings screen for "Display over other apps" (also called Manage Overlay Permission). This prevents your app from remaining pinned as the active foreground app.

This behavior occurs because your POS app is programmatically requesting overlay permissions during that workflow. The app itself initiates the Settings screen, not Esper's kiosk enforcement. Because system Settings screens launch directly from the app, Esper's kiosk pin cannot suppress them.

Before you begin

Confirm the issue reproduces consistently with your POS app version. If the issue only occurs with specific app versions (for example, version 5.3 and above), note the version number—this helps identify when the problem was introduced.

Step 1: Collect device logs

Open the Esper Console and navigate to Devices & Groups → [Your Device Name] → Device Log.
Download the device log file, or use ADB to pull logs directly:
```
adb bugreport
```
Search the logs for evidence of the overlay permission intent. Use this ADB command to filter for overlay-related entries:
```
adb logcat -v threadtime | grep -i "MANAGE_OVERLAY\|SYSTEM_ALERT_WINDOW\|ACTION_MANAGE"
```

Step 2: Verify the source of the issue

In the logs, look for ACTION_MANAGE_OVERLAY_PERMISSION being invoked by your POS app's package name during the refund or emulated receipt workflow.
Confirm that the Settings screen launch originates from the POS app itself, not from Esper's device management agent.
If the logs confirm this, the issue is in your POS app's code, not in Esper's kiosk enforcement.

Step 3: Contact your POS app development team

Share the log evidence with your POS application development team and provide the following information:

The specific workflow that triggers the issue (for example: refund → emulated receipt flow)
The POS app version where the issue occurs (for example, version 5.3 and above)
Log excerpts showing the ACTION_MANAGE_OVERLAY_PERMISSION intent being triggered by the POS app

Ask the development team to:

Audit the POS app code for any newly introduced overlay permission requests in version 5.3 and later, particularly in the refund or receipt processing code path.
Either pre-grant the SYSTEM_ALERT_WINDOW permission at install time or remove the runtime permission request.

Step 4: Verify the fix

Once your POS app development team patches the app or pre-grants the permission:

Update the POS app on your test device.
Re-run the refund and emulated receipt workflow in kiosk mode.
Confirm that the app remains pinned in the foreground and the Settings screen no longer appears.

Try a workaround (optional)

If you need a temporary solution before the POS app is patched, you can try pre-granting the overlay permission through Esper:

In the Esper Console, navigate to your app configuration in Apps & Configuration.
Locate the App Permissions section and look for the SYSTEM_ALERT_WINDOW permission.
Pre-grant this permission if the option is available.
Test whether pre-granting the permission prevents the runtime Settings prompt and keeps your app in the foreground.

Note: This workaround may not resolve the issue if the app is explicitly programmed to launch the Settings screen regardless of permission state.

Still need help?

If the logs do not show the overlay permission intent, or if pre-granting permissions does not resolve the issue, contact Esper Support. include:

The device logs or logcat output showing the Settings screen launch
Your POS app version number
The exact workflow that triggers the issue
Confirmation that you have checked with your POS app development team