DEV Community: KTS Studio

How to Add OAuth in iOS in Half an Hour

KTS Studio — Wed, 08 Mar 2023 01:00:42 +0000

Hello! Our iOS Developer Lena wrote an article about adding Oath to iOS in half

In most cases, a mobile application should be able to authorize users for data access, and quite often this is done with third-party services. In these cases, OAuth2.0 is used. It is a protocol that allows to log into another service without the entering your login and password to the application and giving a restricted set of accesses to the service resources.

Mobile applications use Authorization Code Flow with Proof Key for Code Exchange (PKCE).

Today, we’ll consider implementation of the OAuth authorization with AppAuth-iOS. It is one of the most popular and easy-to-use libraries. The code from the article is available at Github.

In this article you will learn about:

Basic configuration
Authorization in the third-party service and saving the access token for further use
Access token update
Logout
Conclusions

Basic configuration

We’ve chosen OAuth Github as a third-party service. The basic configuration is similar to that of the android application from the previous article: first, let’s register the OAuth application in Github.

When registering, set CALLBACK_URL for your application in the service. This is the URL to redirect to after authorization, and to be intercepted by your application.

We’ll use ru.kts.oauth://github.com/callback as CALLBACK_URL. Don’t forget to use the ru.kts.oauth custom scheme, so that only your application could intercept the redirect.

After registering the OAuth application in Github, you should have client_id and client_secret you have to generate. Save them.

Now you need to understand, what URL to go to in order to get authorized in the Github web-page, and what URL is to be used to exchange the code for the token. You can find the answer in the Github OAuth documentation.

URL for authorization: https://github.com/login/oauth/authorize
URL for token exchange: https://github.com/login/oauth/access_token

To get authorized, you have to determine the scopes Github provides access to. Let’s say, in the application we need access to the user information and repositories: user, repo.

After configuring the OAuth Github application, we should have the following data we will add to the project as configuration properties:

struct AuthConfiguration {
    static let baseUrl = "https://github.com/"
    static let authUri = "login/oauth/authorize"
    static let tokenUri = "login/oauth/access_token"
    static let endSessionUri = "logout"
    static let scopes = ["user", "repo"]
    static let clientId = "..."
    static let clientSecret = "..."
    static let callbackUrl = "ru.kts.oauth://github.com/callback"
    static let logoutCallbackUrl = "ru.kts.oauth://github.com/logout_callback"
}

Please note that callbackUrl and logoutCallbackUrl have the ru.kts.oauth custom scheme. For the application to be able to intercept the redirect, it’s necessary to write this scheme in Info.plist (URL Schemes, URLIdentifier):

Connect AppAuth library via the cocoapods. When working with Github OAuth, there is one nuance — Github returns response in the xml format, while OAuth specification requires response in the json format. You can’t add the custom request header to specify the response format in the AppAuth library, so let’s fork it and add the headers to the source code.

Connecting AppAuth library

Now, let’s execute authorization.

📱 Authorization

Our task is:

to create the method, in which we will generate the authorization request and call the AppAuth library method
to implement the redirect intercepting to complete the process

1. Create the authorization session. For a start, in AppDelegate announce the variable of the OIDExternalUserAgentSession type that will hold the current authorization session and will be used when intercepting the redirect to continue the authorization process (implementation is below):

class AppDelegate: UIResponder, UIApplicationDelegate {

    var currentAuthorizationFlow: OIDExternalUserAgentSession?

}
All classes / protocols of the AppAuth library have OID prefix.

2. Create the authorization configuration. The AppAuth library contains the OIDAuthorizationService entity that allows to execute OAuth requests.

Requests are presented by OIDAuthorizationRequest (authorization request), OIDTokenRequest (token update request), OIDEndSessionRequest (logout request) entities. Every request requires the OIDServiceConfiguration configuration — a set of endpoint uris in the initializer. We’ll create the common constant for all requests and put it in a new class of OAuthRepository:

class OAuthRepository {
    private let configuration = OIDServiceConfiguration.init(
        authorizationEndpoint: URL(string: AuthConfiguration.baseUrl + AuthConfiguration.authUri)!,
        tokenEndpoint: URL(string: AuthConfiguration.baseUrl + AuthConfiguration.tokenUri)!,
        issuer: nil,
        registrationEndpoint: nil,
        endSessionEndpoint: URL(string: AuthConfiguration.baseUrl + AuthConfiguration.endSessionUri)!)
}

In our case, issuer (The OpenID Connect issuer) and registrationEndpoint (registration uri) fields are not used.

3. Create the authorization request. The entire OAuth data logic will be located in OAuthRepository class; let’s place the login method there.

State the request:

 let request = OIDAuthorizationRequest(
            configuration: configuration,
            clientId: AuthConfiguration.clientId,
            clientSecret: AuthConfiguration.clientSecret,
            scopes: AuthConfiguration.scopes,
            redirectURL: URL(string: AuthConfiguration.callbackUrl)!,
            responseType: OIDResponseTypeCode,
            additionalParameters: nil)

The responseType field informs, in what form we want to get the response after authorization. Other possible values are OIDResponseTypeToken, OIDResponseTypeIDToken. Github always returns only the code, that’s why let’s use OIDResponseTypeCode
additionalParameters is a dictionary, whose keys will be added to the request URL as additional query parameters. They can be required for some OAuth services, but we don’t use them in our example

4. Execute the authorization request. The next step is to call the AppAuth library method to execute the request.

If an authorized user doesn’t have to open pages in the application in SafariVC, you can get away with the standard method from the AppAuth library documentation. Under the hood, the method uses OIDExternalUserAgentIOS with a separate ASWebAuthenticationSession session, which then doesn’t share cookies with other SafariViewControllers. That’s not what we want.

To share the session with SavariVC we implement custom OIDExternalUserAgentIOSSafariViewController that implements the OIDExternalUserAgent interface from the library. This allows to open pages in SafariViewController without authorization.

Click here to see the sample implementation and add it to the project, and read more about UserAgent in this article.

5. Create OIDExternalUserAgentIOSSafariViewController:

let agent = OIDExternalUserAgentIOSSafariViewController(presentingViewController: viewController)

Now let’s use the authorization method with the custom externalUserAgent:

appDelegate.currentAuthorizationFlow = OIDAuthState.authState(byPresenting: request, externalUserAgent: agent) { [weak self] authState, error in
    // implementation below
}

Calling this method will open SafariVC with the authorization page, and after successful authorization, the service will redirect you to the url stated in the redirectURL field of the request. In our case, it’s ru.kts.oauth://github.com/callback.

The uri redirect parameters contain the code we need. It’s necessary to intercept this redirect, and then to exchange code for the token.

6. Now, let’s intercept the authorization redirect and get the token. To intercept the redirect, let’s implement scene(, openURLContexts:)_ method in sceneDelegate, for ios versions lower than 13 — application(_:, open url: URL, options:) in AppDelegate:

func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    let appDelegate = UIApplication.shared.delegate as! AppDelegate
    if let authorizationFlow = appDelegate.currentAuthorizationFlow,
       let url = URLContexts.first?.url,
       authorizationFlow.resumeExternalUserAgentFlow(with: url) {
            appDelegate.currentAuthorizationFlow = nil
     }
}

Here we check the current authorization flow in the application and call the resumeExternalUserAgentFlow method that verifies, if this uri coincides with the one stated in the request. If the method returns true, SafariVC hides and the process of exchange the code for the token starts. The code is exchanged for the token under AppAuth hood.

7. Save the tokens. After exchanging the code for the token, we get in the OIDAuthState.authState method handler we used during the previous step. It’s necessary to check that there are no errors and to save the obtained token. For simplicity, let’s save access and refresh tokens in UserDefaults:

appDelegate.currentAuthorizationFlow = OIDAuthState.authState(byPresenting: request, externalUserAgent: agent) { [weak self] authState, error in
    if error == nil {
        let tokenModel = TokenModel(access: authState?.lastTokenResponse?.accessToken,
                                            refresh: authState?.lastTokenResponse?.refreshToken)
        self?.userDefaultsHelper.setToken(value: tokenModel)
    }
}

In a real-life project, that would not be safe, so it’s better to use keychain.

7. Test the authorization

Run the code.

We have already implemented OAuth authorization and token receipt:

To validate the obtained token, we push a new screen, where we try to get data from https://api.github.com/user with the token.

To make sure that the authorization session shares cookies with SafariVC, we open the Github user page in it by clicking:

📱Token Update

Refresh token is not used in Github OAuth, but in many other services the access expires. That’s why I provide the token update example.

1. Generate the token update request. For a start, it’s necessary to generate OIDTokenRequest:

func refreshToken() {
    guard let refreshToken = userDefaultsHelper.getToken()?.refresh else { return }
          let requestRefresh = OIDTokenRequest(
              configuration: configuration,
              grantType: OIDGrantTypeRefreshToken,
              authorizationCode: nil,
              redirectURL: nil,
              clientID: AuthConfiguration.clientId,
              clientSecret: AuthConfiguration.clientSecret,
              scope: nil,
              refreshToken: refreshToken,
              codeVerifier: nil,
              additionalParameters: nil)

In addition to the already known parameters we’ve seen during authorization, in the request it’s necessary to transfer the OIDGrantTypeRefreshToken value and the saved refresh token in the grantType parameter. We transfer nil in the parameters we don’t use.

2. Update the token. Call the OIDAuthorizationService.perform method, if updated successfully, we save new values of access and refresh tokens:

func refreshToken() {
    guard let refreshToken = userDefaultsHelper.getToken()?.refresh else { return }
    let requestRefresh = OIDTokenRequest(
        configuration: configuration,
        grantType: OIDGrantTypeRefreshToken,
        authorizationCode: nil,
        redirectURL: nil,
        clientID: AuthConfiguration.clientId,
        clientSecret: AuthConfiguration.clientSecret,
        scope: nil,
        refreshToken: refreshToken,
        codeVerifier: nil,
        additionalParameters: nil)

    OIDAuthorizationService.perform(requestRefresh) { [weak self] tokenResponse, error in
        if error == nil {
            let tokenModel = TokenModel(access: tokenResponse?.accessToken,
                                        refresh: tokenResponse?.refreshToken)
            self?.userDefaultsHelper.setToken(value: tokenModel)
        }
    }
}

You can check this implementation, if you create the Github Apps application instead of OAuth and replace clientId and clientSecret in AuthConfiguration.

📱Logout
When using OAuth authorization, it’s not enough to just clear the saved token from the storage. SafariVC cookies are not cleared, and when trying to get authorized again, a user will automatically log into the services under the previous account without the opportunity to enter another login / password.

That’s why, to implement logout, it’s also necessary to generate the request in OIDEndSessionRequest…

let request =  OIDEndSessionRequest(configuration: configuration,
                                    idTokenHint: accessToken,
                                    postLogoutRedirectURL: URL(string: AuthConfiguration.logoutCallbackUrl)!,
                                    additionalParameters: nil)

…and include it in the OIDAuthorizationService.present method:

let agent = OIDExternalUserAgentIOSSafariViewController(presentingViewController: viewController)

appDelegate.currentAuthorizationFlow = OIDAuthorizationService.present(request, externalUserAgent: agent) { [weak self] (response, error) in
  if let error = error {
       completion(.failure(CustomError.logoutError))
  } else {
       self?.userDefaultsHelper.clearToken()
    }
}

GitHub OAuth has no redirect after logout, that’s why users will have to close the window by themselves.

This causes an error in the callback, that’s why there is no error check in the final version, and the app just clears off the saves tokens:

let agent = OIDExternalUserAgentIOSSafariViewController(presentingViewController: viewController)

appDelegate.currentAuthorizationFlow = OIDAuthorizationService.present(request, externalUserAgent: agent) { [weak self] (response, error) in
    self?.userDefaultsHelper.clearToken()
}

📲** Conclusions**
The entier project code can be found in github.

We’ve implemented all methods required to support OAuth: authorization, token update and logout. Using the library helps easily integrate OAuth in the application. But some services — such as Github OAuth — have their own usage patterns that require custom solutions.

How do you implement OAuth in your applications? Have you had experience of working with AppAuth? What OAuth issues have you faced?

Cooking Window Inset with Jetpack Compose sauce and a pinch of View — part 2

KTS Studio — Tue, 07 Mar 2023 23:39:50 +0000

Hey! My name is Timur, I am an Android developer at KTS.

This article is a continuation. In the previous part, we figured out what edge-to-edge mode is in mobile apps and how to work with WindowInsets in Android.

Now we’ll cover examples of how to handle insets not only in View, but also in Jetpack Compose. And when you can find the articles about working with Insets in View on the web, the information about working with them in Jetpack Compose can only be found in the official documentation.

All the examples from the article can be viewed in this repository.

Content of this article:

Examples of processing insets:
System Window Insets
Ime Insets (Keyboard Processing)
Stable Insets
Immersive mode (full screen mode without UI elements)
To hide the UI
To show the UI
Display Cutouts (Display cutout support)
System Gesture Insets
Mandatory System Gesture Insets
Tappable element insets
Conclusion

System Window Insets

This type of insets is the main one. They’re needed to handle elements like the Status Bar and Navigation Bar. For example, with full screen rendering, the toolbar will be under the Status Bar.

In this case, we need to set the insets for the toolbar that’s in the AppBarLayout with a magenta background. This will give us the effect of extending the AppBar behind the Status Bar. The example below uses the insetter library.


toolbar.applyInsetter {
   type(navigationBars = true, statusBars = true) {
       padding(horizontal = true)
       margin(top = true)
   }
}

In Jetpack Compose, you can achieve the same effect by setting insets in contentPadding of the TopAppBar function. In this example, we use WindowInsets.systemBars for horizontal and top so that when the screen is rotated, the Navigation Bar doesn’t overlap the beginning of the header or the exit button.


TopAppBar(
    contentPadding = WindowInsets.systemBars
        .only(WindowInsetsSides.Horizontal + WindowInsetsSides.Top)
        .asPaddingValues(),
    backgroundColor = MaterialTheme.colors.primary
) {
    // content...
}

Jetpack Compose also has many extensions for Modifier, such as systemBarsPadding(), navigationBarsPadding(), statusBarsPadding() and others.

After installing insets, the toolbar will look like this:

Ime Insets (Keyboard Processing)

The keyboard is handled with WindowInsetsCompat.Type.ime(). Also for ime insets, it’s possible to additionally handle keyboard animation with the new API ViewCompat.setWindowInsetsAnimationCallback. You can learn more about the animation features of ime insets here.

The setWindowInsetsAnimationCallback call is implemented in the insetter library (activated by the animated flag on padding/margin) and allows you to additionally link the animation not only to the View on which the DSL is called, but also to other View in order to synchronize the animation on several UI elements (syncTranslationTo method).

An example of keypad processing with insetter animation.

private fun setupInsets() = with(binding) {
   messageWrapper.applySystemBarsImeInsetter(syncTranslationView = list) {
       margin(horizontal = true, bottom = true, animated = true)
   }
}

inline fun View.applySystemBarsImeInsetter(
   syncTranslationView: View? = null,
   crossinline insetterApply: InsetterApplyTypeDsl.() -> Unit
) {
   applyInsetter {
       type(ime = true, navigationBars = true, statusBars = true) {
           insetterApply()
       }
       syncTranslationView?.let {
           syncTranslationTo(it)
       }
   }
}

To achieve this effect in Jetpack Compose, you need to use the imePadding() extension for the Modifier (don’t forget to inset the Navigation Bar with navigationBarsPadding()):

@Composable
fun BottomEditText(
    placeholderText: String = "Type text here..."
) {
    val text = rememberSaveable(stateSaver = TextFieldValue.Saver) {
        mutableStateOf(TextFieldValue(""))
    }
    Surface(elevation = 1.dp) {
        OutlinedTextField(
            value = text.value,
            onValueChange = { text.value = it },
            placeholder = { Text(text = placeholderText) },
            modifier = Modifier
                .fillMaxWidth()
                .padding(horizontal = 16.dp, vertical = 8.dp)
                .navigationBarsPadding()
                .imePadding()
        )
    }
}

Jetpack Compose also allows you to open the keyboard with a scroll using imeNestedScroll():

LazyColumn(
    contentPadding = contentPadding,
    reverseLayout = true,
    modifier = Modifier
        .weight(1f)
        .imeNestedScroll()
) {
    items(listItems) { SampleListItem(it) }
}

Stable Insets

Stable Insets are only useful in full-screen applications such as video players, galleries, and games. In player mode, you may have noticed that you have the entire UI system hidden, including the Status Bar, which moves across the edge of the screen. But as soon as you touch the screen, the Status Bar appears at the top. The peculiarity of the insets in the gallery or player is that empty insets come into View when you show/hide the UI system (when the UI system is hidden). For this reason, the Ui elements of the application that work with insets can jump back and forth, as you can see in the following image.

Therefore, there’s a special type of Stable Insets that the system always outputs with values as if the system UI were displayed. The insetter has a method ignoreVisibility which tells the system that there should be Stable Insets for this View.

toolbar.applyInsetter {
    type(navigationBars = true, statusBars = true) {
        padding(horizontal = true)
            margin(top = true)
    }
    ignoreVisibility(true)
}

Surprisingly, there’s no ready-made solution for Stable Insets in Jetpack Compose, but we can implement it as follows:

class StableStatusBarsInsetsHolder {
   private var stableStatusBarsInsets: WindowInsets = WindowInsets(0.dp)

   val stableStatusBars: WindowInsets
       @Composable
       get() {
           val density = LocalDensity.current
           val layoutDirection = LocalLayoutDirection.current
           val statusBars = WindowInsets.statusBars
           return remember {
               derivedStateOf {
                   if (statusBars.exclude(stableStatusBarsInsets).getTop(density) > 0) {
                       stableStatusBarsInsets 
                                   = statusBars.deepCopy(density, layoutDirection)
                   }
                   stableStatusBarsInsets
               }
           }.value
       }

}

private fun WindowInsets.deepCopy(density: Density, layoutDirection: LayoutDirection): WindowInsets {
   return WindowInsets(
       left = getLeft(density, layoutDirection),
       top = getTop(density),
       right = getRight(density, layoutDirection),
       bottom = getBottom(density)
   )
}

Example of use:

val stableInsetsHolder = remember { StableStatusBarsInsetsHolder()}
SampleTopBar(
   titleRes = R.string.insets_sample_fullscreen_stable,
   contentPadding = stableInsetsHolder.stableStatusBars
       .only(WindowInsetsSides.Horizontal + WindowInsetsSides.Top)
       .asPaddingValues(),
)

Now, when we use Stable Insets, the processing insets elements don’t bounce.

Immersive mode (full screen mode without UI elements)

To show or hide the Ui instead of putting certain UI_FLAGS combinations, a new class WindowInsetsController (its compat version WindowInsetsControllerCompat) is used since API 30 which has a convenient API based on the new API 30 classes.

How you can return the system Ui to the screen is set with the WindowInsetsController flags (set via the setSystemBarsBehavior method):

BEHAVIOR_SHOW_BARS_BY_SWIPE — A swipe is required to return SystemUi, remove on your own;
BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE — A swipe is required to return the system Ui, hiding automatically after a while.

There are the following extension functions with the ability to add calls to the WindowInsetsController via extraAction.

To hide the UI

fun Window.hideSystemUi(extraAction:(WindowInsetsControllerCompat.() -> Unit)? = null) {
    WindowInsetsControllerCompat(this, this.decorView).let { controller ->
        controller.hide(WindowInsetsCompat.Type.systemBars())
        extraAction?.invoke(controller)
    }
}

// Usage
hideSystemUi{
    systemBarsBehavior =
    WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE

To show the UI

fun Window.showSystemUi(extraAction: (WindowInsetsControllerCompat.() -> Unit)? = null) {
    WindowInsetsControllerCompat(this, this.decorView).let { controller ->
        controller.show(WindowInsetsCompat.Type.systemBars())
        extraAction?.invoke(controller)
    }
}

// Usage
showSystemUi()

In Jetpack Compose, you can use the rememberSystemUiController() from the accompanist system ui controller library to hide or show the system user interface.

val systemUiController = rememberSystemUiController()

InsetsExamplesTheme {
   FullscreenCutoutSample(
       systemUiController.toggleUi
   )
}

val SystemUiController.toggleUi: () -> Unit
   get() = {
       isSystemBarsVisible = !isSystemBarsVisible
   }

But this library doesn’t allow changing flags of WindowInsetsControllerCompat. So a class based on rememberSystemUiController() from the accompanist systemui controller was written. In this implementation, BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE is set for WindowInsetsControllerCompat.

Example

Example of use:

val systemUiVisibilityController = rememberSystemUiVisibilityController()
InsetsExamplesTheme {
   FullscreenCutoutSample(
       systemUiVisibilityController.toggleUi
   )
}

Display Cutouts (Display cutout support)

Bangs and cutouts are appearing more and more frequently on cell phones. They’re located in different places on the screen and can have different sizes and shapes.

Android 9 (api 28) introduced the DisplayCutout class, which allows you to handle the cutout area. In addition, there’s a set of flags in WindowManager.LayoutParams that allow you to enable different behavior around the cutouts.

To set the flags, layoutInDisplayCutoutMode is used to determine how your content is displayed in the cutout area. There’re the following values:

LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT — in portrait mode the content is displayed below the cutout area, and in landscape mode there will be a black bar.
LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES — Content is displayed in the cutout area in both portrait and landscape modes.
LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER — Content is never displayed in the cutout area.
LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS — In this mode, the window expands beneath the cutouts at all edges of the display in both portrait and landscape orientations, regardless of whether the window hides the system panels ( LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES full analogue, but available with 28 api when LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS appeared only in 30 api).

Example of use:

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
    window.attributes.layoutInDisplayCutoutMode =  WindowManager.LayoutParams.LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES
}

There is a flag for displayCutout in the insetter library, so you can handle padding and margin from the cutout area.

applyInsetter {
   type(displayCutout = true) {
       // specify the sides you need
       // for example padding(top = true)
       padding() 
   } 
}

In Jetpack Compose you also need to use layoutInDisplayCutoutMode to set the mode for DisplayCotout. In compose, you can use WindowInsets.displayCutout or Modifier.displayCutoutPadding() to handle padding.

If you suddenly need to get a cutout area, you can use DisplayCutoutCompat.getBoundingRects() to do that. This method returns a list of rectangles, each of which is a bounding rectangle for a non-functional area on the display.

ViewCompat.setOnApplyWindowInsetsListener(root) { view, insets ->
   val boundingRects = insets.displayCutout?.boundingRects
   insets
}

In Jetpack Compose, you can’t get boundingRects with WindowInsets.displayCutout.

I think that arranging elements relative to the cutout makes no sense for the following reasons:

where there’s no cutout is information from the Status Bar (time, icons)
api returns a list, which means there can be several cutouts
cutouts come in different shapes and sizes

In general, everything says that it’s better not to do so, but if you really need, you can do it.

System Gesture Insets

This kind of insets appeared in Android 10. They return the gesture areas home from below and back to the right and left of the screen.

If there’re scroll elements in these areas, users can, for example, accidentally trigger a backward gesture. Therefore, if you can’t move the interface element away from the edge, but you need to fix the problem with gestures, use this type of inserts

For example: in the gif below, the user wants to scroll but will trigger an exit without excluding gestures. You should also remember that large areas with gesture exclusions can lead to incomprehensible behavior for the user, so it’s worth excluding gestures only in places where it’s necessary. If we look at the example below, a gesture should only be excluded for an element with a horizontal scroll.

While implementing the example for View, I encountered a problem that windowInsets.getInsets(WindowInsetsCompat.Type.systemGestures()) returns an empty value. I agonized over this for a long time, until I decided to run the example on an emulator and saw that everything worked. To make sure, I sent the apk to my colleagues and got the answer: everything works. The problem was that I was testing the example on my device (Realme c21). Vendors are messing around as usual.

Code

To exclude gestures in Jetpack Compose, you can use Modifier.systemGestureExclusion().

LazyRow(
   modifier = Modifier
       .padding(vertical = 16.dp)
       .systemGestureExclusion(),
   contentPadding = PaddingValues(horizontal = 16.dp),
   horizontalArrangement = Arrangement.spacedBy(16.dp)
) {
    //...
}

Mandatory System Gesture Insets

This type of insets appeared in Android 10 and is a subtype of System Gesture Insets. They specify areas of the screen where system gesture behavior will always take priority over in-app gestures. Mandatory gesture areas can never be excluded by apps (with android 10, the mandatory gesture area is the home gesture area). Mandatory insets move content away from mandatory gesture inserts. For example, if you have a seekbar at the bottom of the screen, you need to use Mandatory System Gesture Insets to avoid calling gestures.

In View, mandatory insets can be processed using the insetter library:

seekBar.applyInsetter {
   type(mandatorySystemGestures = true) {
       padding(bottom = true)
   }
}

In Jetpack Compose, mandatory gestures can be obtained with WindowInsets.mandatorySystemGestures:

Surface(
   modifier = Modifier
       .fillMaxWidth()
       .windowInsetsPadding(
           WindowInsets.mandatorySystemGestures
               .only(WindowInsetsSides.Bottom)
               .union(
                   WindowInsets.navigationBars.only(WindowInsetsSides.Horizontal)
               )
       ),
   color = Color.LightGray.copy(alpha = 0.3f)
) {
   // content
}

Tappable element insets

This type of insets appeared in android 10 and is needed to handle different Navigation Bar modes. This type of insets is rarely used, because the differences from the system window insets are minimal. But you should agree that it’s nice to know that your application is written in the coolest way possible.

In the picture below you can see that tappable element insets and system window insets work the same when the device is set to navigate with buttons. The difference can only be noticed in gesture-based navigation mode.

The point is that when navigating with gestures, we don’t click, but swipe from bottom to top. This means that we can use interactive elements in this area (e.g. FloatingActionButton), which means that we don’t need to indent and tappable element insets will return 0.

An example of using the c view (still using the insetter library):

fab.applyInsetter {
   type(tappableElement = true) {
       margin(bottom = true)
   }
}

In Jetpack Compose we use WindowInsets.tappableElement:

Scaffold(
   floatingActionButton = {
      FloatingActionButton(
          modifier = Modifier.padding(
              bottom = WindowInsets.tappableElement
                  .only(WindowInsetsSides.Bottom)
                  .asPaddingValues()
                  .calculateBottomPadding()
          ),
          backgroundColor = backgroundColor,
          onClick = onClick
      ) {
          Icon(
              imageVector = Icons.Filled.Add,
              contentDescription = null
          )
      }
){ // content... }

Conclusion

You can find all the code from the article in this repository.

We looked at the nuances of implementing e2e in Android mobile apps and an example of implementation using the insetter library for View, and used the built-in insets in Jetpack Compose. In this article I wanted to let all android developers know that e2e is in fact very easy to implement and worth the time invested. I hope you found this article useful and more and more developers will adopt e2e in their applications.

Do you implement edge-to-edge in your applications? Do you use libraries to work with insets? What problems have you faced when implementing edge-to-edge?

Thanks to Vadim for his help in preparing this article.

Cooking Window Inset with Jetpack Compose sauce and a pinch of View — part 1

KTS Studio — Tue, 28 Feb 2023 17:24:59 +0000

Hey! My name is Timur, I am an Android developer at KTS.

Unfortunately, there’re still Android applications that don’t support edge-to-edge. I feel that developers either don’t know about this possibility or are afraid to work with WindowInsets. In fact, Edge-to-Edge isn’t difficult to implement, and thanks to this article you’ll understand this topic much faster.

Today I’ll explain what edge-to-edge mode is in mobile apps and how to work with WindowInsets in Android. In the next article, we’ll also cover examples of how to handle insets not only in View, but also in Jetpack Compose.

When you can find the articles about working with Insets in View on the web, the information about working with them in Jetpack Compose can only be found in the official documentation.

All the examples from the article can be viewed in this repository.

The content of the article:

1️⃣ What is edge-to-edge?
2️⃣ Steps for setting up edge-to-edge
3️⃣ Changing the color of the system UI
4️⃣ Request a rendering of the application under the system UI
5️⃣ Eliminate visual conflicts
6️⃣ WindowInsets vs fitSystemWindow?

What is edge-to-edge?
Today, mobile applications are increasingly displayed across the entire visible surface of the display, beyond the system UI. These applications use an edge-to-edge approach, where the application is displayed below the system UI, i.e., the status bar and the navigation bar.

Why, you ask? To create a more attractive and modern user interface. Will you agree that everyone is happier when they use a nicer application?

Now let’s move on to the edge-to-edge implementation.

Steps for setting up edge-to-edge

To implement edge-to-edge mode in your application you’ll need to:

change the color of the system UI
request a rendering of the application under the system UI
eliminate visual conflicts

Changing the color of the system UI

As of Android 5 (API 21), it’s now possible to set the color for the Status Bar and Navigation Bar. Use the following theme attributes for this purpose:

<item name="android:statusBarColor">@color/colorAccent</item>
<item name="android:navigationBarColor">@color/colorAccent</item>

We can also make the color of the system UI transparent or semi-transparent. To achieve semi-transparency, just set android:windowTranslucentStatus and android:windowTranslucentNavigation:

<item name="android:windowTranslucentStatus">true</item>
<item name="android:windowTranslucentNavigation">true</item>

To get a fully transparent system interface you need to set android:navigationBarColor and android:statusBarColor with transparent color and disable contrast with the following attributes android:enforceNavigationBarContrast, android:enforceStatusBarContrast. Disabling contrast is necessary because since version 10 Android provides sufficient contrast to the Navigation Bar.

<item name="android:statusBarColor">@android:color/transparent</item>
<item name="android:navigationBarColor">@android:color/transparent</item>
<item name="android:enforceNavigationBarContrast">false</item>
<item name="android:enforceStatusBarContrast">false</item>

In the screenshot above, you may see that the Navigation Bar buttons are barely visible. The Status Bar would have the same problem if it weren’t for the magenta color. To fix this, use the attributes android:windowLightStatusBar, android:windowLightNavigationBar. Note that windowLightStatusBar is available with 23 api and windowLightNavigationBar with 27 api.

In Jetpack Compose, you can use the System UI Controller library to change the color, which provides simple tools for changing the color of the UI system. You can change the color of the UI system using this library as follows:

private val BlackScrim = Color(0f, 0f, 0f, 0.3f) // 30% opaque black

@Composable
fun TransparentSystemBars() {
   val systemUiController = rememberSystemUiController()
   val useDarkIcons = MaterialTheme.colors.isLight
   SideEffect {
       systemUiController.setSystemBarsColor(
           color = Color.Transparent,
           darkIcons = useDarkIcons,
           isNavigationBarContrastEnforced = false,
           transformColorForLightContent = { original ->
               BlackScrim.compositeOver(original)
           }
       )
   }
}

Example of using the TransparentSystemBars function:

override fun onCreate(savedInstanceState: Bundle?) { 
   super.onCreate(savedInstanceState)
   WindowCompat.setDecorFitsSystemWindows(window, false)
   setContent {
       TransparentSystemBars()
       Sample()
   }
}

The setSystemBarsColor method allows you to:

set the color for the system UI
specify when to use light or dark icons
you can disable contrast with isNavigationBarContrastEnforced
you can use the transformColorForLightContent lambda, which will be called to convert colors if dark icons are requested but not available. The default behavior in transformColorForLightContent is black, so you don’t need to write that).

Request a rendering of the application under the system UI

In addition to changing the color of the system interface, you need to tell the system to draw the application in full-screen mode. Android has special View SYSTEM_UI_FLAGS for this purpose (hereafter UI _FLAGS). They’ve been deprecated since API 30, and you should now use the new WindowCompat class, which contains the required flags on earlier versions of the API.

The full screen mode request via WindowCompat looks like this:

WindowCompat.setDecorFitsSystemWindows(window, false)

If you apply this in the activity, the framework won’t replace inserts for the content of your application and we’ll have to do it manually.

It makes sense to request rendering mode for the entire application (in onCreate() of your Activity, if you use the single-activity approach).

In Jetpack Compose, this step is no different.

Eliminate visual conflicts

If you follow the previous steps and run the application, you can see that the system no longer accounts for the space for the system UI. Now we have to do it ourselves:

Android applications use WindowInsets to manage the system UI. Insets is an object that represents an area of a window that conflicts with the application. Conflicts can be different, and there’re different types of insets for that (gesture handling areas, system panels, bangs, etc.).

The WindowInsetsCompat class with backward compatibility and convenient separation into insets types is used for insets processing.

The processing itself consists of attaching a listener to the View, to which the system passes an insets object. After you get the object, you can apply the desired padding or margin to the View:


ViewCompat.setOnApplyWindowInsetsListener(navBar) { view, insets ->
    val systemBarInsets = insets.getInsets(WindowInsetsCompat.Type.systemBars())
    view.updatePadding(
        bottom = systemBarInsets.bottom,
        left = systemBarInsets.left,
        right = systemBarInsets.right
    )
    insets
}

In KTS, we use the insetter library, which works on the basis of this approach. The library implements a handy Kotlin DSL applyInsetter to handle insets.

toolbar.applyInsetter {
    type(navigationBars = true, statusBars = true) {
        padding(horizontal = true, top = true)
    }
}

Jetpack Compose used to use the library from the accompanist repository to install instes, but it’s obsolete now that official support for insets is available in Compose 1.2.0. If you were already using accompanist, there’s a detailed migration guide on the website.

TopAppBar( 
  contentPadding = WindowInsets.systemBars
        .only(WindowInsetsSides.Horizontal + WindowInsetsSides.Top) 
        .asPaddingValues(), 
  backgroundColor = MaterialTheme.colors.primary 
) { 
  // content… 
}

WindowInsets vs fitSystemWindow?

Android has the fitSystemWindow flag. If you set it to “true”, this flag adds padding to the container for which you specified the flag.

FitsSystemWindows confuses many developers.

For example, this flag works with CoordinatorLayout and doesn’t work for FrameLayout. FitsSystemWindows = true doesn’t move your content under the status bar, but it works for layouts like CoordinatorLayout and DrawerLayout because they override the default behavior. Under the hood, they set the flags setSystemUiVisibility(View.SYSTEM_UI_FLAG_LAYOUT_STABLE | View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN) if fitsSystemWindows is true.

SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN moves the content under the status bar.
SYSTEM_UI_FLAG_LAYOUT_STABLE ensures that the maximum possible system insets are applied, even if the current ones are less than this.

If we set these flags to our rootLayout, everything should work even on FrameLayout.

Also, hierarchy is important when using fitSystemWindow: if any parent has set this flag to “true”, its propagation won’t be taken into account further, because the container has already applied the indents.

This is actually not all the nuances why using the fitSystemWindow flag isn’t recommended, so better use WindowInsets to avoid different problems and non-obvious behavior.

What’s next?

That’s all for now, but stay tuned ✌️
In the next part we will look at examples of processing different types of inserts:

System Window Insets
Ime Insets (Keyboard Processing)
Stable Insets
Immersive mode (full screen mode without UI elements)
To hide the UI
To show the UI
Display Cutouts (Display cutout support)
System Gesture Insets
Mandatory System Gesture Insets
Tappable element insets

See you later!