Android 15+ OS-level allowlist requirements for Esper Supervisor Plugin

Android

When provisioning enterprise Android devices running Android 15 or later with the Esper Supervisor Plugin, the plugin fails to acquire required permissions and does not function correctly, even when the APK is platform-signed.

Why this happens

Android 15 introduced stricter permission controls that affect all platform-signed applications. Apps signed with a device's platform key no longer automatically receive privileged or signature-level permissions — each required permission must be explicitly declared in a firmware-level allowlist before the device is flashed. Because this allowlist is baked into the firmware image, it cannot be configured through the Esper Console after provisioning.

Before you begin

This process applies only when all of the following are true:

• The target device runs Android 15 or later
• You are integrating the Esper Supervisor Plugin into a new firmware build
• You have access to the device's firmware source code and build system

This is an OEM or field application engineer (FAE) responsibility. No step in this process is performed in the Esper Console.

Steps

1. Review the required permissions for your Android version.
   Open the Esper Supervisor Plugin setup guide and locate the Android 15+ permissions section. Note every permission string listed for com.esper.supervisorplugin — the allowlist entry must match these strings exactly, including namespace and capitalisation.
2. Create or update the firmware-level priv-app permissions allowlist.
   Locate your device's privileged permissions allowlist directory, typically /etc/permissions/ or an OEM-specific equivalent. Add an XML entry that declares the Supervisor Plugin package and explicitly lists each required permission. A minimal entry follows this structure:

   <permissions>
       <privapp-permissions package="com.esper.supervisorplugin">
           <permission name="android.permission.EXAMPLE_PERMISSION"/>
           <!-- add all required permissions here -->
       </privapp-permissions>
   </permissions>

   Each permission string must exactly match what is listed in the Esper Supervisor Plugin documentation — a single character difference silently prevents the grant with no visible error at provisioning time.
3. Sign the Supervisor Plugin APK with your device's platform keys.
   The APK must be signed with the same platform signing certificate used for your firmware build. An APK signed with a different key will not receive the declared permissions even if the allowlist entry is correct.
4. Place the signed APK in the correct priv-app directory.
   Copy the signed Supervisor Plugin APK to /system/priv-app/ or the equivalent privileged app directory for your device's filesystem layout. Apps placed in /system/app/ instead of /system/priv-app/ will not be granted privileged permissions.
5. Build a new firmware image incorporating the updated allowlist and APK.
   Run your standard firmware build process. Confirm the output image includes both the updated permissions XML and the correctly placed APK before proceeding.
6. Flash the firmware image to the target device.
   Use your standard flashing procedure. The allowlist takes effect on first boot from the new image — it cannot be applied to a device that has already been flashed with a prior build.

Verify

Verify: After the device boots, open a terminal or adb shell and run:

adb shell dumpsys package com.esper.supervisorplugin | grep "granted=true"

Each required permission should appear with granted=true. The Esper Supervisor Plugin should initialise without errors, and any Esper Agent functionality that depends on the plugin should operate normally. If you see granted=false for any required permission, proceed to the troubleshooting steps below before re-flashing.

If this doesn't resolve it

If permissions remain ungranted or the Supervisor Plugin still does not function after flashing:

• Pull a full bug report from the device:

  adb bugreport

  Search the captured logcat for PackageManager entries referencing com.esper.supervisorplugin — these will identify which permission declarations are missing or malformed.
• Confirm the platform signing certificate on the APK matches the build's platform key:

  apksigner verify --print-certs com.esper.supervisorplugin.apk

• Cross-reference every permission string in your allowlist XML against the current Esper Supervisor Plugin documentation — permission strings may differ between Supervisor Plugin versions.

If the issue persists after completing these checks, contact Esper Support and include: the device manufacturer and model, the Android version, the full bug report, the allowlist XML file, and the output of apksigner verify.

Still need help?

Still need help? When submitting a support ticket, include your Android OS version, the specific allowlist error message you're encountering, and details about your Esper Supervisor Plugin configuration.