Background (headless) app not auto-starting after reboot in Kiosk mode: set app as launchable-hidden to ensure BOOT_COMPLETED handling

Android

If your background (headless) app isn't auto-starting after a device reboot in kiosk mode, you may need to configure the app as launchable in your Blueprint. This ensures the app can receive the BOOT_COMPLETED broadcast on startup.

Before you begin

Verify that your app's AndroidManifest.xml includes both the RECEIVE_BOOT_COMPLETED permission and a broadcast receiver with the BOOT_COMPLETED intent filter. Without these declarations, no configuration change will allow the app to auto-start.

If your app targets Android 8.0 (API level 26) or higher, note that background execution limits may prevent services from running after boot. Consider using JobScheduler or WorkManager instead of a background Service.

Why your background app isn't starting

When you install an app on an Esper-managed device without explicitly setting it as launchable, Android places the app in a stopped state. Android does not deliver BOOT_COMPLETED broadcasts to stopped apps—this is standard Android behavior since API level 3.1.

Manually launching the app via ADB temporarily moves it out of stopped state, which is why it runs when you start it manually. However, the next device reboot returns it to stopped state.

How to fix this

1. Open the Esper Console and navigate to the Blueprint assigned to your device or device group.
2. Go to the Apps section.
3. Locate your headless background application in the installed apps list.
4. Set the app's launch mode to "Show in app list but do not launch automatically" (also called launchable-hidden). This keeps the app out of the kiosk launcher while marking it as launchable to Android. For detailed instructions, see Add or Hide Preloaded Apps on Devices.
5. Save and publish the Blueprint.
6. Apply the updated Blueprint to your target device or group.
7. Reboot the device via Devices & Groups → [Device Name] → Actions → Reboot.
8. After reboot, verify the app is running by checking active processes on the device.

How to verify the app is running

After the device reboots, confirm that your headless app started successfully:

• Check for any observable behavior the app produces (network calls, log entries, or side effects).
• Alternatively, pull a bug report from the device and review the ActivityManager and PackageManager sections of the logcat output to confirm the app process is active. See Logs and Bug Reports for instructions.

If the app still isn't starting

Collect a bug report immediately after reboot (before any manual intervention) and review it for evidence of the app being in stopped state or the broadcast being suppressed in the logcat output.

If you've confirmed your manifest includes the correct permissions and intent filters, and the app still does not start after applying the launchable-hidden configuration, contact Esper Support and attach your bug report. Include the device model and Android version you're using.

Still need help?

If this article didn't resolve your issue, submit a support ticket and include the device serial number, your Blueprint configuration, and a bug report from the device.