Headless service APK stuck in stopped state after install: use Launch API or Blueprint "Launch on Start" to trigger initial launch

Android

When you install a headless service APK on a kiosk-mode device, Android may keep the app in a stopped state, preventing it from running automatically. This article explains how to trigger the initial launch so your service starts properly.

Before you begin

This issue occurs because Android's package manager marks newly installed apps as "stopped" by default. While in this state, the app cannot receive broadcasts or start background services—even if those are declared in the manifest. On kiosk-mode devices without user access to a launcher, the app needs an explicit launch intent from Esper to clear this stopped state.

Once the app launches successfully for the first time, it will handle subsequent reboots on its own.

How to trigger the initial launch: Launch API (recommended)

Use the Launch API if your device must remain in single-app or kiosk mode. This approach works with any app that exposes an exported activity.

Retrieve your Esper API Key from the Esper Console: Account Settings → API Key Management → Generate Key.
Find the target device's device_id in Devices & Groups → [Device Name] → Device Details.
Identify the exported activity in your APK's AndroidManifest.xml (for example, LauncherActivity).
Call the Launch API endpoint with the package name and activity name. See the Commonly-Used APIs article for the full endpoint documentation.
Execute the API call immediately after the app install completes. You can automate this in your CI/CD pipeline, provisioning script, or via an Esper Esper API.
Verify the service is running by checking Devices & Groups → [Device Name] → Device Details → App State, or via ADB:
```
adb shell ps | grep <package_name>
```

Note: No additional licensing is required. The Launch API is available to all Esper accounts and is managed through the standard API key flow in the Esper Console.

Alternative: Blueprint "Launch on Start" (requires Multi-app Mode)

If you can switch your device to Multi-app Mode, you can configure the app to launch automatically when the device starts.

Open your Blueprint in Blueprints → [Blueprint Name] → Edit.
Navigate to Device Settings → Kiosk / App Mode and change the mode to Multi-app Mode.
In the Apps section, find your APK.
Toggle on Launch on Start.
Save and publish the Blueprint, then apply it to the target device group.
Verify the service is running after the Blueprint converges on the device.

Note: The "Launch on Start" toggle only appears in Multi-app Mode. If you must keep your device in kiosk mode, use the Launch API instead.

Troubleshooting

Launch API returns an error or the app does not start

Ensure the target activity declares android:exported="true" in your AndroidManifest.xml. For apps targeting Android 12 (API level 31) or higher, you must explicitly set android:exported on any activity that should receive external intents. If this attribute is missing, the intent will be silently rejected.

Service stops shortly after first launch

Your app may be subject to Android battery optimization or Doze restrictions. Verify that:

Your app requests the REQUEST_IGNORE_BATTERY_OPTIMIZATIONS permission in the manifest.
Your Blueprint's Managed Configuration / Battery Optimization whitelist includes your package name.

Blueprint "Launch on Start" toggle is not visible

The toggle only appears when your Blueprint is in Multi-app Mode. Check your Device Settings → Kiosk / App Mode configuration.

Issue persists across multiple devices or OEMs

Collect the following information and contact Esper Support:

Output from adb logcat filtered to your package name and the ActivityManager tag.
Device model and OEM information.
The exact error message or behavior you observe.

Still need help?

If you encounter issues beyond these troubleshooting steps, submit a support ticket and include your device model, package name, and relevant logcat output.