diff --git a/packages/SystemUI/docs/keyguard/bouncer.md b/packages/SystemUI/docs/device-entry/bouncer.md similarity index 98% rename from packages/SystemUI/docs/keyguard/bouncer.md rename to packages/SystemUI/docs/device-entry/bouncer.md index 4bfe7340db30f..589cb5d300d34 100644 --- a/packages/SystemUI/docs/keyguard/bouncer.md +++ b/packages/SystemUI/docs/device-entry/bouncer.md @@ -2,6 +2,8 @@ [KeyguardBouncer][1] is the component responsible for displaying the security method set by the user (password, PIN, pattern) as well as SIM-related security methods, allowing the user to unlock the device or SIM. +![ss-bouncer](./imgs/bouncer_pin.png) + ## Supported States 1. Phone, portrait mode - The default and typically only way to view the bouncer. Screen cannot rotate. diff --git a/packages/SystemUI/docs/keyguard/doze.md b/packages/SystemUI/docs/device-entry/doze.md similarity index 99% rename from packages/SystemUI/docs/keyguard/doze.md rename to packages/SystemUI/docs/device-entry/doze.md index a6ccab9698d44..5ff8851b4c696 100644 --- a/packages/SystemUI/docs/keyguard/doze.md +++ b/packages/SystemUI/docs/device-entry/doze.md @@ -2,6 +2,8 @@ Always-on Display (AOD) provides an alternative 'screen-off' experience. Instead, of completely turning the display off, it provides a distraction-free, glanceable experience for the phone in a low-powered mode. In this low-powered mode, the display will have a lower refresh rate and the UI should frequently shift its displayed contents in order to prevent burn-in. The recommended max on-pixel-ratio (OPR) is 5% to reduce battery consumption. +![ss-aod](./imgs/aod.png) + The default doze component controls AOD and is specified by `config_dozeComponent` in the [framework config][1]. SystemUI provides a default Doze Component: [DozeService][2]. [DozeService][2] builds a [DozeMachine][3] with dependencies specified in [DozeModule][4] and configurations in [AmbientDisplayConfiguration][13] and [DozeParameters][14]. Note: The default UI used in AOD shares views with the Lock Screen and does not create its own new views. Once dozing begins, [DozeUI][17] informs SystemUI's [DozeServiceHost][18] that dozing has begun - which sends this signal to relevant SystemUI Lock Screen views to animate accordingly. Within SystemUI, [StatusBarStateController][19] #isDozing and #getDozeAmount can be used to query dozing state. diff --git a/packages/SystemUI/docs/device-entry/glossary.md b/packages/SystemUI/docs/device-entry/glossary.md new file mode 100644 index 0000000000000..f3d12c21a3a5c --- /dev/null +++ b/packages/SystemUI/docs/device-entry/glossary.md @@ -0,0 +1,48 @@ +# Device Entry Glossary + +## Keyguard + +| Term | Description | +| :-----------: | ----------- | +| Keyguard, [keyguard.md][1] | Coordinates the first experience when turning on the display of a device, as long as the user has not specified a security method of NONE. Consists of the lock screen and bouncer.| +| Lock screen

![ss_aod](imgs/lockscreen.png)| The first screen available when turning on the display of a device, as long as the user has not specified a security method of NONE. On the lock screen, users can access:The lock screen is one state of the notification shade. See [StatusBarState#KEYGUARD][10] and [StatusBarState#SHADE_LOCKED][10].| +| Bouncer, [bouncer.md][2]

![ss_aod](imgs/bouncer_pin.png)| The component responsible for displaying the primary security method set by the user (password, PIN, pattern). The bouncer can also show SIM-related security methods, allowing the user to unlock the device or SIM.| +| Split shade | State of the shade (which keyguard is a part of) in which notifications are on the right side and Quick Settings on the left. For keyguard that means notifications being on the right side and clock with media being on the left.

Split shade is automatically activated - using resources - for big screens in landscape, see [sw600dp-land/config.xml][3] `config_use_split_notification_shade`.

In that state we can see the big clock more often - every time when media is not visible on the lock screen. When there is no media and no notifications - or we enter AOD - big clock is always positioned in the center of the screen.

The magic of positioning views happens by changing constraints of [NotificationsQuickSettingsContainer][4] and positioning elements vertically in [KeyguardClockPositionAlgorithm][5]| +| Ambient display (AOD), [doze.md][6]

![ss_aod](imgs/aod.png)| UI shown when the device is in a low-powered display state. This is controlled by the doze component. The same lock screen views (ie: clock, notification shade) are used on AOD. The AOSP image on the left shows the usage of a clock that does not support variable weights which is why the clock is thicker in that image than what users see on Pixel devices.| + +## General Authentication Terms +| Term | Description | +| ----------- | ----------- | +| Primary Authentication | The strongest form of authentication. Includes: Pin, pattern and password input.| +| Biometric Authentication | Face or fingerprint input. Biometric authentication is categorized into different classes of security. See [Measuring Biometric Security][7].| + +## Face Authentication Terms +| Term | Description | +| ----------- | ----------- | +| Passive Authentication | When a user hasn't explicitly requested an authentication method; however, it may still put the device in an unlocked state.

For example, face authentication is triggered immediately when waking the device; however, users may not have the intent of unlocking their device. Instead, they could have wanted to just check the lock screen. Because of this, SystemUI provides the option for a bypass OR non-bypass face authentication experience which have different user flows.

In contrast, fingerprint authentication is considered an active authentication method since users need to actively put their finger on the fingerprint sensor to authenticate. Therefore, it's an explicit request for authentication and SystemUI knows the user has the intent for device-entry.| +| Bypass | Used to refer to the face authentication bypass device entry experience. We have this distinction because face auth is a passive authentication method (see above).| +| Bypass User Journey

![ss_bypass](imgs/bypass.png)| Once the user successfully authenticates with face, the keyguard immediately dismisses and the user is brought to the home screen/last app. This CUJ prioritizes speed of device entry. SystemUI hides interactive views (notifications) on the lock screen to avoid putting users in a state where the lock screen could immediately disappear while they're interacting with affordances on the lock screen.| +| Non-bypass User Journey | Once the user successfully authenticates with face, the device remains on keyguard until the user performs an action to indicate they'd like to enter the device (ie: swipe up on the lock screen or long press on the unlocked icon). This CUJ prioritizes notification visibility.| + +## Fingerprint Authentication Terms +| Term | Description | +| ----------- | ----------- | +| Under-display fingerprint sensor (UDFPS) | References the HW affordance for a fingerprint sensor that is under the display, which requires a software visual affordance. System UI supports showing the UDFPS affordance on the lock screen and on AOD. Users cannot authenticate from the screen-off state.

Supported SystemUI CUJs include:| +| UDFPS Bouncer | UI that highlights the UDFPS sensor. Users can get into this state after tapping on a notification from the lock screen or locked expanded shade.| + +## Other Authentication Terms +| Term | Description | +| ---------- | ----------- | +| Trust Agents | Provides signals to the keyguard to allow it to lock less frequently.| + + +[1]: /frameworks/base/packages/SystemUI/docs/device-entry/keyguard.md +[2]: /frameworks/base/packages/SystemUI/docs/device-entry/bouncer.md +[3]: /frameworks/base/packages/SystemUI/res/values-sw600dp-land/config.xml +[4]: /frameworks/base/packages/SystemUI/src/com/android/systemui/statusbar/phone/NotificationsQuickSettingsContainer.java +[5]: /frameworks/base/packages/SystemUI/src/com/android/systemui/statusbar/phone/KeyguardClockPositionAlgorithm.java +[6]: /frameworks/base/packages/SystemUI/docs/device-entry/doze.md +[7]: https://source.android.com/security/biometric/measure +[8]: /frameworks/base/packages/SystemUI/res-keyguard/font/clock.xml +[9]: /frameworks/base/packages/SystemUI/src/com/android/systemui/statusbar/phone/KeyguardStatusBarViewController.java +[10]: /frameworks/base/packages/SystemUI/src/com/android/systemui/statusbar/StatusBarState.java diff --git a/packages/SystemUI/docs/device-entry/imgs/aod.png b/packages/SystemUI/docs/device-entry/imgs/aod.png new file mode 100644 index 0000000000000..abd554a8936f2 Binary files /dev/null and b/packages/SystemUI/docs/device-entry/imgs/aod.png differ diff --git a/packages/SystemUI/docs/device-entry/imgs/bouncer_pin.png b/packages/SystemUI/docs/device-entry/imgs/bouncer_pin.png new file mode 100644 index 0000000000000..da15e4115ab97 Binary files /dev/null and b/packages/SystemUI/docs/device-entry/imgs/bouncer_pin.png differ diff --git a/packages/SystemUI/docs/device-entry/imgs/bypass.png b/packages/SystemUI/docs/device-entry/imgs/bypass.png new file mode 100644 index 0000000000000..f4cbd3efb6fca Binary files /dev/null and b/packages/SystemUI/docs/device-entry/imgs/bypass.png differ diff --git a/packages/SystemUI/docs/device-entry/imgs/lockscreen.png b/packages/SystemUI/docs/device-entry/imgs/lockscreen.png new file mode 100644 index 0000000000000..d1fe0853f5789 Binary files /dev/null and b/packages/SystemUI/docs/device-entry/imgs/lockscreen.png differ diff --git a/packages/SystemUI/docs/keyguard.md b/packages/SystemUI/docs/device-entry/keyguard.md similarity index 74% rename from packages/SystemUI/docs/keyguard.md rename to packages/SystemUI/docs/device-entry/keyguard.md index 8914042ee3cdb..337f73b79260f 100644 --- a/packages/SystemUI/docs/keyguard.md +++ b/packages/SystemUI/docs/device-entry/keyguard.md @@ -30,6 +30,12 @@ An indication to power off the device most likely comes from one of two signals: ### How the device locks +## Debugging Tips +Enable verbose keyguard logs that will print to logcat. Should only be used temporarily for debugging. See [KeyguardConstants][5]. +``` +adb shell setprop log.tag.Keyguard DEBUG && adb shell am crash com.android.systemui +``` + More coming * Screen timeout * Smart lock @@ -38,9 +44,8 @@ More coming * Lock timeout after screen timeout setting -[1]: /frameworks/base/packages/SystemUI/docs/keyguard/bouncer.md -[2]: /frameworks/base/services/core/java/com/android/server/power/PowerManagerService.java -[3]: /frameworks/base/packages/SystemUI/docs/keyguard/doze.md -[4]: /frameworks/base/services/core/java/com/android/server/policy/PhoneWindowManager.java - - +[1]: /frameworks/base/packages/SystemUI/docs/device-entry/bouncer.md +[2]: /com/android/server/power/PowerManagerService.java +[3]: /frameworks/base/packages/SystemUI/docs/device-entry/doze.md +[4]: /com/android/server/policy/PhoneWindowManager.java +[5]: /frameworks/base/packages/SystemUI/src/com/android/keyguard/KeyguardConstants.java diff --git a/packages/SystemUI/docs/user-switching.md b/packages/SystemUI/docs/user-switching.md index dcf66b943f1dc..b9509eb41c3c4 100644 --- a/packages/SystemUI/docs/user-switching.md +++ b/packages/SystemUI/docs/user-switching.md @@ -37,7 +37,7 @@ A fullscreen user switching activity, supporting add guest/user actions if confi Renders user switching as a dialog over the current surface, and supports add guest user/actions if configured. -[1]: /frameworks/base/packages/SystemUI/docs/keyguard/bouncer.md +[1]: /frameworks/base/packages/SystemUI/docs/device-entry/bouncer.md [2]: /frameworks/base/packages/SystemUI/src/com/android/systemui/statusbar/phone/MultiUserController.java [3]: /frameworks/base/packages/SystemUI/src/com/android/systemui/statusbar/policy/UserSwitcherController.java [4]: /frameworks/base/packages/SystemUI/src/com/android/systemui/statusbar/policy/KeyguardQsUserSwitchController.java