RoleManager

public final class RoleManager
extends Object

java.lang.Object
   ↳ android.app.role.RoleManager


This class provides information about and manages roles.

A role is a unique name within the system associated with certain privileges. The list of available roles might change with a system app update, so apps should not make assumption about the availability of roles. Instead, they should always query if the role is available using isRoleAvailable(java.lang.String) before trying to do anything with it. Some predefined role names are available as constants in this class, and a list of possibly available roles can be found in the AndroidX Role library.

There can be multiple applications qualifying for a role, but only a subset of them can become role holders. To qualify for a role, an application must meet certain requirements, including defining certain components in its manifest. These requirements can be found in the AndroidX Libraries. Then the application will need user consent to become a role holder, which can be requested using Activity.startActivityForResult(Intent, int) with the Intent obtained from createRequestRoleIntent(java.lang.String).

Upon becoming a role holder, the application may be granted certain privileges that are role specific. When the application loses its role, these privileges will also be revoked.

Summary

Constants

String ROLE_ASSISTANT

The name of the assistant app role.

String ROLE_BROWSER

The name of the browser role.

String ROLE_CALL_REDIRECTION

The name of the call redirection role.

String ROLE_CALL_SCREENING

The name of the call screening and caller id role.

String ROLE_DIALER

The name of the dialer role.

String ROLE_EMERGENCY

The name of the emergency role

String ROLE_HOME

The name of the home role.

String ROLE_NOTES

The name of the notes role.

String ROLE_SMS

The name of the SMS role.

Public methods

Intent createRequestRoleIntent(String roleName)

Returns an Intent suitable for passing to Activity.startActivityForResult(Intent, int) which prompts the user to grant a role to this application.

boolean isRoleAvailable(String roleName)

Check whether a role is available in the system.

boolean isRoleHeld(String roleName)

Check whether the calling application is holding a particular role.

Inherited methods

Constants

ROLE_ASSISTANT

Added in API level 29
public static final String ROLE_ASSISTANT

The name of the assistant app role.

Constant Value: "android.app.role.ASSISTANT"

ROLE_BROWSER

Added in API level 29
public static final String ROLE_BROWSER

The name of the browser role.

Constant Value: "android.app.role.BROWSER"

ROLE_CALL_REDIRECTION

Added in API level 29
public static final String ROLE_CALL_REDIRECTION

The name of the call redirection role.

A call redirection app provides a means to re-write the phone number for an outgoing call to place the call through a call redirection service.

Constant Value: "android.app.role.CALL_REDIRECTION"

ROLE_CALL_SCREENING

Added in API level 29
public static final String ROLE_CALL_SCREENING

The name of the call screening and caller id role.

Constant Value: "android.app.role.CALL_SCREENING"

ROLE_DIALER

Added in API level 29
public static final String ROLE_DIALER

The name of the dialer role.

Constant Value: "android.app.role.DIALER"

ROLE_EMERGENCY

Added in API level 29
public static final String ROLE_EMERGENCY

The name of the emergency role

Constant Value: "android.app.role.EMERGENCY"

ROLE_HOME

Added in API level 29
public static final String ROLE_HOME

The name of the home role.

Constant Value: "android.app.role.HOME"

ROLE_NOTES

Added in API level 34
public static final String ROLE_NOTES

The name of the notes role.

Constant Value: "android.app.role.NOTES"

ROLE_SMS

Added in API level 29
public static final String ROLE_SMS

The name of the SMS role.

Constant Value: "android.app.role.SMS"

Public methods

createRequestRoleIntent

Added in API level 29
public Intent createRequestRoleIntent (String roleName)

Returns an Intent suitable for passing to Activity.startActivityForResult(Intent, int) which prompts the user to grant a role to this application.

If the role is granted, the resultCode will be Activity.RESULT_OK, otherwise it will be Activity.RESULT_CANCELED.

Parameters
roleName String: the name of requested role This value cannot be null.

Returns
Intent the Intent to prompt user to grant the role This value cannot be null.

isRoleAvailable

Added in API level 29
public boolean isRoleAvailable (String roleName)

Check whether a role is available in the system.

Parameters
roleName String: the name of role to checking for This value cannot be null.

Returns
boolean whether the role is available in the system

isRoleHeld

Added in API level 29
public boolean isRoleHeld (String roleName)

Check whether the calling application is holding a particular role.

Parameters
roleName String: the name of the role to check for This value cannot be null.

Returns
boolean whether the calling application is holding the role