Page Summary

outlined_flag

• Application roles grant special privileges to managed apps on Android devices, allowing them to function without interruption from power/background restrictions, suspension, hibernation, and user controls.

• To utilize application roles, the device must be managed by an AMAPI based EMM.

• Integrating with the AMAPI SDK allows the app to be notified of assigned roles and bootstrap itself.

• Proper metadata needs to be added to the app's manifest to enable Android Device Policy to discover theNotificationReceiverService.

• Implementing theAppRolesListener in yourNotificationReceiverService is necessary to receive notifications about assigned roles.

The application roles feature allows an IT admin to grant special privileges toa managed application on an Android-powered device. By assigning a specificrole, an app can be exempted from power and background restrictions, suspension,hibernation (on Android 14+) and have user controls (i.e. includes user actionslike force-stopping and clearing app data) disabled (on Android 11+),allowing it to perform its critical function without interruption. Additionally,the app can be notified of its assigned roles, which allows it to bootstrapitself without user intervention.

For a list of available application roles and the special privileges granted toeach role, seeRoleType.

Prerequisites

The device is managed by an AMAPI based EMM (EMMs using a custom DPC are notsupported).

Prepare your app for using the feature

Integrating with the AMAPI SDK is only required if the app wants to be notifiedof its assigned roles which allows it to bootstrap itself (i.e. auto launchwithout user interaction).

Integrate with the AMAPI SDK in your app

You can find more information about AMAPI SDK and how to add it to your app intheAMAPI SDK integration guide.

Add the required metadata to the app's manifest

Android Device Policy (ADP) needs to know theComponentName of your classwhich implementsNotificationReceiverService to notify your app of itsassigned roles. You must tag your service inAndroidManifest.xml suitably sothat it can be automatically discovered by ADP.

• Your app must have exactly one service which isenabled and hasmeta-data withandroid:name equal tocom.google.android.managementapi.notification.NotificationReceiverService.SERVICE_APP_ROLES
• This service must haveandroid:exported set totrue
• Theandroid:value of themeta-data must be set to an empty string

<serviceandroid:name=".MyNotificationReceiverService"android:exported="true"><meta-dataandroid:name="com.google.android.managementapi.notification.NotificationReceiverService.SERVICE_APP_ROLES"android:value=""/></service>

If you are testing theCOMPANION_APP role, you should also add the followingmeta-data to your service so that Android Device Policy can send local command status updates to your app:

<meta-dataandroid:name="com.google.android.managementapi.notification.NotificationReceiverService.SERVICE_COMMAND_STATUS"android:value=""/>

Create a service extending NotificationReceiverService (or update the existing)

Create or update your existingNotificationReceiverService and implement anAppRolesListener to listen for roles assigned to your app. OnlygetAppRolesListener() is required for listening for roles assigned to yourapp. If your app is assigned aCOMPANION_APP role you should also implementgetCommandListener():

importandroid.util.Logimportcom.google.android.managementapi.approles.AppRolesListenerimportcom.google.android.managementapi.approles.model.AppRolesSetRequestimportcom.google.android.managementapi.approles.model.AppRolesSetResponseimportcom.google.android.managementapi.commands.CommandListenerimportcom.google.android.managementapi.commands.model.Commandimportcom.google.android.managementapi.notification.NotificationReceiverServiceclassMyNotificationReceiverService:NotificationReceiverService(){// If your app wants to listen for roles assignedoverridefungetAppRolesListener():AppRolesListener=object:AppRolesListener{overridefunonAppRolesSet(request:AppRolesSetRequest):AppRolesSetResponse{valroleTypes=request.roles.map{role->role.roleType}Log.i(TAG,"onAppRolesSet:$roleTypes")returnAppRolesSetResponse.getDefaultInstance()}}// If your app wants to listen for local command status updates// Only relevant for COMPANION_APP roleoverridefungetCommandListener():CommandListener{returnobject:CommandListener{overridefunonCommandStatusChanged(command:Command){Log.i(TAG,"onCommandStatusChanged")}}}privatecompanionobject{constvalTAG="MyNotificationReceiverService"}}

Your app can be notified multiple times if its roles change multiple times. Ifall roles are removed, your app will still be notified with an empty list ofroles. This notification will get your app out of stopped state and along withthe exemptions granted for your app, your app can bootstrap itself without anyuser interaction. Thanks to the app roles notification and exemptions, your appcan listen forACTION_BOOT_COMPLETED broadcasts. If your app depends onits managed configurations to bootstrap itself, seeSet up managed configurations on how to read and listenfor changes.

Provision the device with app roles policies

App developers can test assigning app roles to their application using and EMMor following theAndroid Management API quickstart. TheAMAPI Colab notebook lets you enroll an enterprise, create a policy,andprovision a device.

Set the policy for your app with app roles

Set up apolicy with the app roles that your app is intended to have using theApplicationPolicy.roles.

The following example shows how to configure the role for MTD apps:

{"applications":[{"packageName":"com.example.mtd","installType":"FORCE_INSTALLED","roles":[{"roleType":"MOBILE_THREAT_DEFENSE_ENDPOINT_DETECTION_RESPONSE"}]}]}

Before assigning the roles as specified in the policy the system will check thatthe app's signing key certificate fingerprint on the device matches the one fromthe Play Store.If the fingerprint is different, the roles are not going to be assigned to theapp andNonComplianceReason.APP_SIGNING_CERT_MISMATCHnon-compliance will be reported to the EMM.

{"applications":[{"packageName":"com.example.mtd","installType":"FORCE_INSTALLED","signingKeyCerts":[{"signingKeyCertFingerprintSha256":"base64-encoded-sha256"}],"roles":[{"roleType":"MOBILE_THREAT_DEFENSE_ENDPOINT_DETECTION_RESPONSE"}]}]}

If your app has managed configuration, the IT admin can set up an initialconfiguration for the relevantrestrictions in the application policy:

{"applications":[{"packageName":"com.example.mtd","installType":"FORCE_INSTALLED","roles":[{"roleType":"MOBILE_THREAT_DEFENSE_ENDPOINT_DETECTION_RESPONSE"}],"managedConfiguration":{"<key>":"<value>"}}]}