KeyguardManager

public class KeyguardManager
extends Object

java.lang.Object
   ↳ android.app.KeyguardManager


Class to manage and query the state of the lock screen (also known as Keyguard).

Summary

Nested classes

class KeyguardManager.KeyguardDismissCallback

Callback passed to KeyguardManager#requestDismissKeyguard(Activity, KeyguardDismissCallback) to notify caller of result. 

class KeyguardManager.KeyguardLock

This class was deprecated in API level 15. Use R.attr.showWhenLocked or Activity.setShowWhenLocked(boolean) instead. This allows you to seamlessly occlude and unocclude the keyguard as your application moves in and out of the foreground and does not require that any special permissions be requested. 

interface KeyguardManager.KeyguardLockedStateListener

Listener for keyguard locked state changes. 

interface KeyguardManager.OnKeyguardExitResult

This interface was deprecated in API level 26. Use KeyguardDismissCallback 

Public methods

void addKeyguardLockedStateListener(Executor executor, KeyguardManager.KeyguardLockedStateListener listener)

Registers a listener to execute when the keyguard locked state changes.

Intent createConfirmDeviceCredentialIntent(CharSequence title, CharSequence description)

This method was deprecated in API level 29. see BiometricPrompt.Builder.setAllowedAuthenticators(int)

void exitKeyguardSecurely(KeyguardManager.OnKeyguardExitResult callback)

This method was deprecated in API level 15. Use R.attr.showWhenLocked or Activity.setShowWhenLocked(boolean) to seamlessly occlude and unocclude the keyguard as your application moves in and out of the foreground, without requiring any special permissions. Use requestDismissKeyguard(android.app.Activity, android.app.KeyguardManager.KeyguardDismissCallback) to request dismissal of the keyguard.

boolean inKeyguardRestrictedInputMode()

This method was deprecated in API level 28. Use isKeyguardLocked() instead.

boolean isDeviceLocked()

Returns whether the device is currently locked for the user.

boolean isDeviceSecure()

Returns whether the user has a secure lock screen.

boolean isKeyguardLocked()

Returns whether the lock screen (also known as Keyguard) is showing.

boolean isKeyguardSecure()

Returns whether the user has a secure lock screen or there is a locked SIM card.

KeyguardManager.KeyguardLock newKeyguardLock(String tag)

This method was deprecated in API level 15. Use R.attr.showWhenLocked or Activity.setShowWhenLocked(boolean) instead. This allows you to seamlessly occlude and unocclude the keyguard as your application moves in and out of the foreground and does not require that any special permissions be requested.

void removeKeyguardLockedStateListener(KeyguardManager.KeyguardLockedStateListener listener)

Unregisters a listener that executes when the keyguard locked state changes.

void requestDismissKeyguard(Activity activity, KeyguardManager.KeyguardDismissCallback callback)

Requests that the Keyguard (lock screen) be dismissed if it is currently showing.

Inherited methods

Public methods

addKeyguardLockedStateListener

Added in API level 33
public void addKeyguardLockedStateListener (Executor executor, 
                KeyguardManager.KeyguardLockedStateListener listener)

Registers a listener to execute when the keyguard locked state changes.
Requires Manifest.permission.SUBSCRIBE_TO_KEYGUARD_LOCKED_STATE

Parameters
executor Executor: This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.

listener KeyguardManager.KeyguardLockedStateListener: The listener to add to receive keyguard locked state changes. This value cannot be null.

createConfirmDeviceCredentialIntent

Added in API level 21
Deprecated in API level 29
public Intent createConfirmDeviceCredentialIntent (CharSequence title, 
                CharSequence description)

This method was deprecated in API level 29.
see BiometricPrompt.Builder.setAllowedAuthenticators(int)

Get an intent to prompt the user to confirm credentials (pin, pattern, password or biometrics if enrolled) for the current user of the device. The caller is expected to launch this activity using Activity.startActivityForResult(Intent, int) and check for Activity.RESULT_OK if the user successfully completes the challenge.
Requires the PackageManager#FEATURE_SECURE_LOCK_SCREEN feature which can be detected using PackageManager.hasSystemFeature(String).

Parameters
title CharSequence

description CharSequence

Returns
Intent the intent for launching the activity or null if no password is required.

exitKeyguardSecurely

Added in API level 1
Deprecated in API level 15
public void exitKeyguardSecurely (KeyguardManager.OnKeyguardExitResult callback)

This method was deprecated in API level 15.
Use R.attr.showWhenLocked or Activity.setShowWhenLocked(boolean) to seamlessly occlude and unocclude the keyguard as your application moves in and out of the foreground, without requiring any special permissions. Use requestDismissKeyguard(android.app.Activity, android.app.KeyguardManager.KeyguardDismissCallback) to request dismissal of the keyguard.

Exit the keyguard securely. The use case for this api is that, after disabling the keyguard, your app, which was granted permission to disable the keyguard and show a limited amount of information deemed safe without the user getting past the keyguard, needs to navigate to something that is not safe to view without getting past the keyguard. This will, if the keyguard is secure, bring up the unlock screen of the keyguard.
Requires Manifest.permission.DISABLE_KEYGUARD

Parameters
callback KeyguardManager.OnKeyguardExitResult: Lets you know whether the operation was successful and it is safe to launch anything that would normally be considered safe once the user has gotten past the keyguard.

inKeyguardRestrictedInputMode

Added in API level 1
Deprecated in API level 28
public boolean inKeyguardRestrictedInputMode ()

This method was deprecated in API level 28.
Use isKeyguardLocked() instead.

Returns whether the lock screen is showing.

This is exactly the same as isKeyguardLocked().

Returns
boolean the value of isKeyguardLocked()

isDeviceLocked

Added in API level 22
public boolean isDeviceLocked ()

Returns whether the device is currently locked for the user.

This returns the device locked state for the Context's user. If this user is the current user, then the device is considered "locked" when the lock screen is showing (i.e. isKeyguardLocked() returns true) and is not trivially dismissible (e.g. with swipe), and the user has a PIN, pattern, or password.

Note: the above definition implies that a user with no PIN, pattern, or password is never considered locked, even if the lock screen is showing and requesting a SIM card PIN. The device PIN and SIM PIN are separate. Also, the user is not considered locked if face authentication has just completed or a trust agent is keeping the device unlocked, since in these cases the lock screen is dismissible with swipe.

For a user that is not the current user but can be switched to (usually this means "another full user"), and that has a PIN, pattern, or password, the device is always considered locked.

For a profile with a unified challenge, the device locked state is the same as that of the parent user.

For a profile with a separate challenge, the device becomes unlocked when the profile's PIN, pattern, password, or biometric is verified. It becomes locked when the parent user becomes locked, the screen turns off, the device reboots, the device policy controller locks the profile, or the timeout set by the device policy controller expires.

Returns
boolean true if the device is currently locked for the user

See also:

isDeviceSecure

Added in API level 23
public boolean isDeviceSecure ()

Returns whether the user has a secure lock screen.

This returns true if the Context's user has a secure lock screen. A full user or a profile that uses a separate challenge has a secure lock screen if its lock screen is set to PIN, pattern, or password, as opposed to swipe or none. A profile that uses a unified challenge is considered to have a secure lock screen if and only if its parent user has a secure lock screen.

This method does not consider whether the lock screen is currently showing or not.

See also isKeyguardSecure() which includes locked SIM cards.

Returns
boolean true if the user has a secure lock screen

See also:

isKeyguardLocked

Added in API level 16
public boolean isKeyguardLocked ()

Returns whether the lock screen (also known as Keyguard) is showing.

Specifically, this returns true in the following cases:

  • The lock screen is showing in the foreground.
  • The lock screen is showing, but it is occluded by an activity that is showing on top of it. A common example is the phone app receiving a call or making an emergency call.
  • The lock screen was showing but is temporarily disabled as a result of lock task mode or an app using the deprecated KeyguardLock API.

"Showing" refers to a logical state of the UI, regardless of whether the screen happens to be on. When the power button is pressed on an unlocked device, the lock screen starts "showing" immediately when the screen turns off.

This method does not distinguish a lock screen that is requiring authentication (e.g. with PIN, pattern, password, or biometric) from a lock screen that is trivially dismissible (e.g. with swipe). It also does not distinguish a lock screen requesting a SIM card PIN from a normal device lock screen. Finally, it always returns the global lock screen state and does not consider the Context's user specifically.

Note that isKeyguardLocked() is confusingly named and probably should be called isKeyguardShowing(). On many devices, the lock screen displays an unlocked padlock icon when it is trivially dismissible. As mentioned above, isKeyguardLocked() actually returns true in this case, not false as might be expected. isDeviceLocked() is an alternative API that has slightly different semantics.

Returns
boolean true if the lock screen is showing

See also:

isKeyguardSecure

Added in API level 16
public boolean isKeyguardSecure ()

Returns whether the user has a secure lock screen or there is a locked SIM card.

Specifically, this returns true if at least one of the following is true:

  • The Context's user has a secure lock screen. A full user or a profile that uses a separate challenge has a secure lock screen if its lock screen is set to PIN, pattern, or password, as opposed to swipe or none. A profile that uses a unified challenge is considered to have a secure lock screen if and only if its parent user has a secure lock screen.
  • At least one SIM card is currently locked and requires a PIN.

This method does not consider whether the lock screen is currently showing or not.

See also isDeviceSecure() which excludes locked SIM cards.

Returns
boolean true if the user has a secure lock screen or there is a locked SIM card

See also:

newKeyguardLock

Added in API level 1
Deprecated in API level 15
public KeyguardManager.KeyguardLock newKeyguardLock (String tag)

This method was deprecated in API level 15.
Use R.attr.showWhenLocked or Activity.setShowWhenLocked(boolean) instead. This allows you to seamlessly occlude and unocclude the keyguard as your application moves in and out of the foreground and does not require that any special permissions be requested.

Enables you to temporarily disable / reenable the keyguard (lock screen).

Parameters
tag String: A tag that informally identifies who you are (for debugging who is disabling the keyguard).

Returns
KeyguardManager.KeyguardLock A KeyguardLock handle to use to disable and reenable the keyguard.

removeKeyguardLockedStateListener

Added in API level 33
public void removeKeyguardLockedStateListener (KeyguardManager.KeyguardLockedStateListener listener)

Unregisters a listener that executes when the keyguard locked state changes.
Requires Manifest.permission.SUBSCRIBE_TO_KEYGUARD_LOCKED_STATE

Parameters
listener KeyguardManager.KeyguardLockedStateListener: The listener to remove. This value cannot be null.

requestDismissKeyguard

Added in API level 26
public void requestDismissKeyguard (Activity activity, 
                KeyguardManager.KeyguardDismissCallback callback)

Requests that the Keyguard (lock screen) be dismissed if it is currently showing.

If the Keyguard is not secure or the device is currently in a trusted state, calling this method will immediately dismiss the Keyguard without any user interaction.

If the Keyguard is secure and the device is not in a trusted state, this will bring up the UI so the user can enter their credentials.

If the value set for the Activity attr R.attr.turnScreenOn is true, the screen will turn on when the keyguard is dismissed.

Parameters
activity Activity: The activity requesting the dismissal. The activity must either be visible by using R.attr.showWhenLocked or Activity.setShowWhenLocked(boolean), or must be in a state in which it would be visible if Keyguard would not be hiding it. If that's not the case, the request will fail immediately and KeyguardDismissCallback#onDismissError will be invoked. This value cannot be null.

callback KeyguardManager.KeyguardDismissCallback: The callback to be called if the request to dismiss Keyguard was successful or null if the caller isn't interested in knowing the result. The callback will not be invoked if the activity was destroyed before the callback was received.