Bringing Safe Args to Navigation Compose

As of Navigation 2.8.0-alpha08, the Navigation Component has a full type safe system based on Kotlin Serialization for defining your navigation graph when using our Kotlin DSL, designed to work best with integrations like Navigation Compose.

Kotlin DSL? What’s that for?

The Navigation Component has three main components:

• Host — the UI element in your layout that displays the current ‘destination’
• Graph — the data structure that defines all of the possible destinations in your app
• Controller — the central coordinator that manages navigating between destinations and saving the back stack of destinations

The Kotlin DSL is just one of the ways to build that navigation graph. Since the very first alpha of Navigation back in 2018, Navigation has always offered three ways to build the graph:

• Manually constructing instances of NavGraph and adding destinations like Fragment Destinations to construct the graph (this is still the underlying base for everything else, but not something you should actively be doing yourself)
• Inflating your graph from a navigation XML file, editing it by hand or via the Navigation Editor
• Using the Kotlin DSL to construct your navigation graph directly in your Kotlin code

Navigation Compose was the first integration to really embrace the Kotlin DSL as the way to build your graph, purposefully moving to a more flexible system and away from static XML files.

Kotlin code, but at what cost?

However, the move from build time static XML files to generating your graph at runtime meant that the tools available to developers also changed significantly. The Navigation Component’s Safe Args Gradle Plugin, which generated type safe “Directions” classes you could use in your code to navigate between destinations, relied on reading the destinations and their arguments from those navigation XML files. That means without navigation XML files, there was no generated Safe Args code.

And while Navigation requires the correct types and arguments at runtime (telling you loudly (crashing) if you tried to pass a String to something expecting an Int or if you forgot a required argument), compile time safety was left as an exercise to the developer.

Compile time type safety then

Without the Safe Args Gradle plugin, what would you have left? The Kotlin DSL with Navigation Compose was based on the idea that each destination had a unique “route” — a RESTful path that uniquely identifies that destination.

For example, just like a website, you might have a "home" destination, a "products" destination, as well as pages that take arguments — the route for a particular product might be "products/{productId}" — it would include a placeholder for the unique ID of that product.

That meant:

• Keeping track of these string routes
• Managing their arguments and their types
• Worst of all, doing string interpolation

Our own documentation and video content explored how to minimize this bookkeeping — isolating the strings alongside type safe extensions on top of our base Kotlin DSL. While this provided a strong barrier between the base Kotlin DSL and the API you expose across the rest of your code base and across different modules, it clearly wasn’t enough.

I’d like to personally thank the larger Android community for providing some fantastic solutions built on top of Navigation Compose designed to minimize or completely eliminate this manually written code including:

Rafael Costa’s Compose Destinations uses KSP to process annotations attached to composable functions to generate the entire navigation graph.

Kiwi.com’s navigation-compose-typed uses Kotlin Serialization to generate routes directly from @Serializable objects or data classes.

So many ways to generate code

When looking at what ‘Safe Args’ would look like in our Kotlin DSL, we explored a number of approaches, essentially looking at many of the technologies available to us to generate type safe code.

One approach we explored was a transliteration of what we did with the Safe Args Gradle Plugin — rather than a Gradle plugin that would read the source of truth (your navigation XML file), we’d use your existing Kotlin code as the source of truth.

That meant if you wrote a piece of your Kotlin DSL that looked like:

composable(
    route = "profile/{userId}/{name}",
    arguments = listOf(
        navArgument("userId") {
            type = NavType.Int,
            nullable = false
        },
        navArgument("name") {
            type = NavType.String,
            nullable = true
        }
    )
) {

We would generate the ProfileDestination and ProfileArgs classes you’d need to navigate to the "profile" destination and extract those arguments out. After looking into this….this was way easier said than done. Information like the string "profile/{userId}/{name}" was technically possible to extract, but only as a Kotlin Compiler Plugin. And even then, while we could find the route String passed to the Kotlin DSL, it was difficult to resolve the String if it was anything other than a constant String. Given that we have a number of Kotlin Compiler Plugin experts on our larger team who know exactly how much maintenance is involved in a compiler plugin (hi Compose folks!) and that we’re currently transitioning between the K1 and K2 compilers, we chose not to develop this solution any further.

So if the Kotlin DSL code wasn’t a viable source of truth, what could be a viable source of truth? And what tools were available to read that information? It turns out the other two big options (KSP and Kotlin Serialization) are also Kotlin Compiler Plugins. But importantly: they’re ones that ship alongside every version of Kotlin, which is critical for getting out of the way of developers eager to use new versions of Kotlin as they come out.

Why Kotlin Serialization

One of the guiding principles we’ve followed in developing the Navigation Component is in trying to minimize how ‘infectious’ Navigation code is: e.g., how easy is it to swap out our library for another (no judgment!). If you have Navigation code and classes spread throughout your entire code base in every file, you’re never going to get rid of it.

That’s why our testing guide specifically recommends avoiding having any references to your NavController in your screen level composable methods and specifically why there isn’t a NavController composition local: a button deep in your hierarchy, as convenient as it may be, should not be tied to your particular choice of navigation library.

So when looking for a ‘source of truth’ for how to define each destination in our graph, having each of those definitions totally independent of Navigation’s classes was exactly the type of approach we were looking for.

This meant that if you wanted to define a new destination in your navigation graph, you could write the simplest code possible:

// Define a home destination that doesn't take any arguments
@Serializable
object Home

// Define a profile destination that takes an ID
@Serializable
data class Profile(val id: String)

You’ll note that these purposefully don’t need to implement any Navigation provided interface or even be defined in a module that has a Navigation dependency. Yet, they are enough to encapsulate a meaningful name of the destination (I think you might get some looks if you named it object Object1) and any parameters that are core to the identity of that destination. That looks like it could be a viable source of truth.

With Kotlin Serialization as a viable source for compile time safety, we proceeded to take every API that took a String route and add Kotlin Serialization based overloads.

Show me the code

So having defined your Home and Profile Serializable classes, your graph now looks like:

NavHost(navController, startDestination = Home) {
    composable<Home> {
        HomeScreen(onNavigateToProfile = { id ->
            navController.navigate(Profile(id))
        })
     }
     composable<Profile> { backStackEntry ->
         val profile: Profile = backStackEntry.toRoute()
         ProfileScreen(profile)
     }
}

You should note one thing immediately: no strings! Specifically:

• No route string when defining a composable destination — specifying the type is enough to generate the route for you as well as the arguments (no more navArgument either)
• No route string when navigating to a new destination. You pass NavController the Serializable object associated with the destination you want to navigate to.
• No route string when defining the start destination of a navigation graph.

For the Profile screen, we use the toRoute() extension method to recreate the Profile object from the NavBackStackEntry and its arguments. There’s a similar extension method on SavedStateHandle, making it just as easy to get the type safe arguments in your ViewModel as well without needing to reference specific argument keys.

This new approach applies to individual destinations, so you can incrementally migrate from your current approach to this new approach, one destination or one module at a time.

Route vs Route Patterns

One of my personal favorite features of this type safe approach is in making it very clear which APIs support a route pattern (e.g., "profile/{id}") and which support a filled in route (e.g., "profile/42"). For instance, the popBackStack() API actually supports both, but that wasn’t clear when its parameter was just a String. With the type safe APIs, it is much clearer:

// Pop up to the topmost instance of the Profile screen, inclusive
navController.popBackStack<Profile>(inclusive = true)

// Pop up to the exact instance of the Profile screen with ID 42
// also popping any other instances that are on top of it in the back stack
navController.popBackStack(Profile(42), inclusive = true)

So when you see an API that takes a reified class, you’ll know that it denotes any destination of that type, irrespective of its arguments. While one that takes an actual instance of that class is used to find a specific destination with exactly those matching arguments.

APIs like getBackStackEntry() or even the startDestination of your graph are examples where technically they’ve supported both for some time and you might not have even known it!

Custom types

If you’re really doing something custom beyond the primitive types (or their Array and now List equivalents), complicated types like Parcelable types can even be used as fields on your Serializable classes by writing your own custom NavType and passing it through when building your graph:

// The Search screen requires more complicated parameters
@Parcelize
data class SearchParameters(
   val searchQuery: String,
   val filters: List<String>
)

@Serializable
data class Search(
   val parameters: SearchParameters
)

val SearchParametersType = object : NavType<SearchParameters>(
    isNullableAllowed = false
) {
    // See the custom NavType docs linked above for an
    //example of how to implement this
}

// Now use this in your destination
composable<Search>(
 typeMap = mapOf(typeOf<SearchParameters>() to SearchParametersType)
) { backStackEntry ->
    val searchParameters = backStackEntry.toRoute<Search>().parameters
}

Note: this is supposed to be a speed bump: think long and hard whether an immutable, snapshot-in-time argument is really the source of truth for this data, or if this should really be an object you retrieve from a reactive source, such as a Flow exposed from a repository that would automatically refresh if your data changes.

Go forth with safety

The complete type safe API is available starting in Navigation 2.8.0-alpha08. Besides support for all of the Kotlin DSL builders we support (including both Navigation Compose that we talked about here and Navigation with Fragments), it also includes other APIs you might find interesting like the navDeepLink API that takes a Serializable class and a prefix that allows you to easily connect external links to the same type safe APIs.

If you find any issues or have feature requests for APIs we missed, please file an issue — while these APIs are still in alpha is the best time to request changes.

The code snippets in this blog have the following license:

// Copyright 2024 Google LLC. SPDX-License-Identifier: Apache-2.0

Navigation Compose meet Type Safety was originally published in Android Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Jetpack Compose moves the bar on animations from ‘polish, if we have the time’ to ‘so easy there’s no reason to not do it’ and a big part of that are screen level transitions. That’s why Navigation Compose has been working towards a set of solutions that solve three specific cases:

• Using only the stable Animation APIs in Compose 1.0.0
• Enabling support for Experimental Animation APIs present in Compose 1.0.0
• Building towards the future Animation APIs (shared element transitions!!!) in Compose 1.1.0 and beyond

Each of these requires a slightly different approach, which we’ll cover here.

Compose 💚 Animations

Jetpack Compose has come a long, long way since the first 0.1.0-dev01 release through to the new Compose 1.0.1 release. One of the areas that has been a huge improvement over the View world has been that of animations and transitions. In the quest for the perfect animation APIs, a lot of changes were made as Compose marched towards 1.0.0.

While a number of lower level Animation APIs like the incredibly powerful animateTo() and animate*AsState() are stable, foundational parts of Compose at this point, there’s a whole class of APIs on top of those building blocks marked with @ExperimentalAnimationApi.

Experimental APIs and Semantic Versioning

An Experimental API (any API using @RequiresOptIn API in Kotlin land) means that these APIs are subject to change at any point. This means that those APIs might be changed, improved, or replaced in any future release — maybe it is Compose 1.1.0-alpha04 or 1.2.0-alpha08. As such, any library that is built on those Experimental APIs would immediately crash and fail if you were to update the version of Compose you were using and not also update that library at the same time. (If you were along for the ride for early Compose releases, you know this pain.)

All AndroidX libraries, Navigation and Compose included, follow strict semantic versioning as explained on the AndroidX releases page. This means that any API that isn’t experimental is set in stone once a library goes to its Release Candidate (RC) phase. It would take a major version bump (i.e., a ‘2.0’) to make breaking API changes to these stable APIs.

This is great when it comes to forward and backward compatibility — for instance, you can upgrade your Fragment version to try out a new alpha while keeping your other dependencies on their stable releases and everything just works.

However, it also means that experimental APIs, being APIs that can shift out from underneath you, are strictly forbidden across different artifact groups — again, upgrading your version of androidx.fragment shouldn’t break androidx.appcompat. This also applies to androidx.navigation and androidx.compose.animation.

Getting Navigation 2.4 to stable

Navigation 2.4 is a big release as both the first release of Navigation Compose as well as the first release with multiple back stack support for both Navigation Compose and Navigation with Fragments. This means we’re wrapping up the remaining related API requests in preparation for moving through beta, RC, and to stable.

For Navigation Compose, this means that we’re building on top of Compose 1.0.1 with the goal of being forward compatible for those of you who want to (or have already!) moved to start depending on Compose 1.1.0-alpha01 and beyond.

That forward compatibility requirement means that any code in Navigation Compose 2.4.0 can only rely on stable Compose Animation APIs. This is how we were able to add crossfade support in Navigation 2.4.0-alpha05 — in the world of Compose, jump cuts should be the first thing on your list to banish completely.

This limitation on only using stable Compose Animation APIs means that APIs such as AnimatedContent aren’t something Navigation 2.4 can use directly to offer the kind of rich animation control you’d want directly as part of Navigation 2.4. However, the extensible nature of Navigation means that the underlying framework is already built and available.

Introducing: Accompanist Navigation Animation!

That underlying support for animating between destinations is why we’re able to release Accompanist Navigation Animation, built off of today’s release of Navigation 2.4.0-alpha06. The Navigation Animation artifact provides its own set of animation enabled versions of the Navigation Compose APIs you’ve been using:

• Replace rememberNavController() with rememberAnimatedNavController()
• Replace NavHost with AnimatedNavHost
• Replace import androidx.navigation.compose.navigation with import com.google.accompanist.navigation.animation.navigation
• Replace import androidx.navigation.compose.composable with import com.google.accompanist.navigation.animation.composable

At first glance, the appearance of your app hasn’t changed: the default animations are still the same type of fadeIn and fadeOut that the crossfade found in Navigation 2.4 does for you. However, you’ll gain one crucial new feature: the ability to configure those animations and substitute in your own transitions between screens.

This control comes in the form of four new parameters found on every composable destination:

• enterTransition: specifies the animation that runs when you navigate() to this destination.
• exitTransition: specifies the animation that runs when you leave this destination by navigating to another destination.
• popEnterTransition: specifies the animation that runs when this destination re-enters the screen after going through a popBackStack(). This defaults to the enterTransition.
• popExitTransition: specifies the animation that runs when this destination leaves the screen after you pop it off the back stack. This defaults to the exitTransition.

In each case, these parameters have the same format:

enterTransition: (
  AnimatedContentScope<NavBackStackEntry>.() -> EnterTransition?
)? = null,

Each takes a lambda. That lambda uses the AnimatedContentScope to provide you with the NavBackStackEntry of where you are coming from (the initialState) and where you are going to (the targetState). For example, for the enterTransition, the entering destination is the targetState — the one you are applying the enterTransition to. The opposite applies to the exitTransition: the initialState screen is the one you are applying the exit transition to.

This allows you to write your destination such as:

Or, control your animation based on where you’re coming from / going to:

Here, the friends list screen controls its exit transition to the profile screen and the profile screen controls its enter transition from the friends list, allowing for a custom slide over animation between these two destinations. We also see the usage of null to mean “use the defaults”. Those defaults come from the parent navigation graph and then the parent’s parent’s navigation graph, all the way up the hierarchy to the root AnimatedNavHost. This means that setting default animations (say, the timing on crossfades) is possible just by changing the global enterTransition and exitTransition on your AnimatedNavHost.

If you instead want to change the default for only one subgraph (say, your login flow always uses a horizontal slide in animation), you can set that animation on the nested graph level as well:

Note how we use the hierarchy extension method to determine if the destination is actually part of the login graph — that way our transition to the login graph and from the login graph just use the default transition (or whatever transition you’ve set at the higher level).

Whenever you have a directional transition such as sliding in horizontally, this is where the difference between enterTransition and popEnterTransition becomes incredibly handy — you’ll be able to avoid cases where one screen is sliding to the right while the other slides to the left.

Accompanist serves as the booster rockets for Jetpack libraries and let us deliver experimental features right now as the work on Compose 1.1 progresses.

Add Accompanist Navigation Animation via:

implementation
    "com.google.accompanist:accompanist-navigation-animation:0.16.1"

The future of Navigation Compose and Animations

With Navigation 2.4 based on Compose 1.0.1 and Accompanist Navigation Animation stretching the limits of Compose 1.0 via experimental APIs, there’s something else on the horizon: Compose 1.1. Looking at the Compose Roadmap, there’s one really important upcoming feature to get excited about:

Support shared element transitions

Our goal for Navigation 2.5 is to bring all the goodness of Compose 1.1 to Navigation Compose. That means as animation APIs lose their experimental status, we can fold them directly into Navigation Compose. It also means that we can build the API that we know will support shared element transitions as they become available.

It also means that Accompanist Navigation Animation should be considered as a temporary measure: once Navigation Compose itself offers the same level of animation APIs (tailored based on your feedback!), you’ll be able to depend on it directly and remove Accompanist Navigation Animation entirely.

Go forth and animate

Balancing stability and the forward and backward compatibility requirements we put on ourselves as a Jetpack library with the ability to ship features quickly means this isn’t as straightforward as we’d like. Accompanist has been a huge boon as Jetpack Compose gains momentum and accelerates beyond the need for those booster rockets. I’d like to thank Chris Banes and all the developers who put time into Accompanist, the entire team behind Compose, and all of you for helping shape the future of Android development.

PS: if you’re looking for even more Navigation+Accompanist goodies, check out the also brand new Accompanist Navigation Material!

Introducing Navigation-Material 🧭🎨️

Animations in Navigation Compose was originally published in Android Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

A deep dive into what actually went into this feature

If a ‘back stack’ is a set of screens that you can navigate back through via the system back button, ‘multiple back stacks’ is just a bunch of those, right? Well, that’s exactly what we’ve done with the multiple back stack support added in Navigation 2.4.0-alpha01 and Fragment 1.4.0-alpha01!

The joys of the system back button

Whether you’re using Android’s new gesture navigation system or the traditional navigation bar, the ability for users to go ‘back’ is a key part to the user experience on Android and doing that right is an important part to making your app feel like a natural part of the ecosystem.

In the simplest cases, the system back button just finishes your activity. While in the past you might have been tempted to override the onBackPressed() method of your activity to customize this behavior, it is 2021 and that is totally unnecessary. Instead, there are APIs for custom back navigation in the OnBackPressedDispatcher. This is actually the same API that FragmentManager and NavController already plug into.

That means when you use either Fragments or Navigation, they use the OnBackPressedDispatcher to ensure that if you’re using their back stack APIs, the system back button works to reverse each of the screens that you’ve pushed onto the back stack.

Multiple back stacks doesn’t change these fundamentals. The system back button is still a one directional command — ‘go back’. This has a profound effect on how the multiple back stack APIs work.

Multiple back stacks in Fragments

At the surface level, the support for multiple back stacks is deceptively straightforward, but requires a bit of an explanation of what actually is the ‘fragment back stack’. The FragmentManager’s back stack isn’t made up of fragments, but instead is made up of fragment transactions. Specifically, the ones that have used the addToBackStack(String name) API.

This means when you commit() a fragment transaction with addToBackStack(), the FragmentManager is going to execute the transaction by going through and executing each of the operations (the replace, etc.) that you specified on the transaction, thus moving each fragment through to its expected state. FragmentManager then holds onto that transaction as part of its back stack.

When you call popBackStack() (either directly or via FragmentManager’s integration with the system back button), the topmost transaction on the fragment back stack is reversed — an added fragment is removed, a hidden fragment is shown, etc. This puts the FragmentManager back into the same state that it was before the fragment transaction was initially committed.

Note: I cannot stress this enough, but you absolutely should never interleave transactions with addToBackStack() and transactions without in the same FragmentManager: transactions on your back stack are blissfully unaware of non-back stack changing fragment transactions — swapping things out from underneath those transactions makes that reversal when you pop a much more dicey proposition.

This means that popBackStack() is a destructive operation: any added fragment will have its state destroyed when that transaction is popped. This means you lose your view state, any saved instance state, and any ViewModel instances you’ve attached to that fragment are cleared. This is the main difference between that API and the new saveBackStack(). saveBackStack() does the same reversal that popping the transaction does, but it ensures that the view state, saved instance state, and ViewModel instances are all saved from destruction. This is how the restoreBackStack() API can later recreate those transactions and their fragments from the saved state and effectively ‘redo’ everything that was saved. Magic!

This didn’t come without paying down a lot of technical debt though.

Paying down our technical debts in Fragments

While fragments have always saved the Fragment’s view state, the only time that a fragment’s onSaveInstanceState() would be called would be when the Activity’s onSaveInstanceState() was called. To ensure that the saved instance state is saved when calling saveBackStack(), we need to also inject a call to onSaveInstanceState() at the right point in the fragment lifecycle transitions. We can’t call it too soon (your fragment should never have its state saved while it is still STARTED), but not too late (you want to save the state before the fragment is destroyed).

This requirement kicked off a process to fix how FragmentManager moves to state to make sure there’s one place that manages moving a fragment to its expected state and handles re-entrant behavior and all the state transitions that go into fragments.

35 changes and 6 months into that restructuring of fragments, it turned out that postponed fragments were seriously broken, leading to a world where postponed transactions were left floating in limbo — not actually committed and not actually not committed. Over 65 changes and another 5 months later, and we had completely rewritten most of the internals of how FragmentManager manages state, postponed transitions, and animations. That effort is covered in more detail in my previous blog post:

Fragments: Rebuilding the Internals

What to expect in Fragments

With the technical debt paid down (and a much more reliable and understandable FragmentManager), the tip of the iceberg APIs of saveBackStack() and restoreBackStack() were added.

If you don’t use these new APIs, nothing changes: the single FragmentManager back stack works as before. The existing addToBackStack() API remains unchanged — you can use a null name or any name you want. However, that name takes on a new importance when you start looking at multiple back stacks: it is that name that is the unique key for that fragment transaction that you’d use with saveBackStack() and later with restoreBackStack().

This might be easier to see in an example. Let’s say that you have added an initial fragment to your activity, then done two transactions, each with a single replace operation:

// This is the initial fragment the user sees
fragmentManager.commit {
  setReorderingAllowed(true)
  replace<HomeFragment>(R.id.fragment_container)
}

// Later, in response to user actions, we’ve added two more
// transactions to the back stack
fragmentManager.commit {
  setReorderingAllowed(true)
  replace<ProfileFragment>(R.id.fragment_container)
  addToBackStack(“profile”)
}

fragmentManager.commit {
  setReorderingAllowed(true)
  replace<EditProfileFragment>(R.id.fragment_container)
  addToBackStack(“edit_profile”)
}

This means that our FragmentManager looks like:

Let’s say that we want to swap out our profile back stack and swap to the notifications fragment. We’d call saveBackStack() followed by a new transaction:

fragmentManager.saveBackStack("profile")

fragmentManager.commit {
  setReorderingAllowed(true)
  replace<NotificationsFragment>(R.id.fragment_container)
  addToBackStack("notifications")
}

Now our transaction that added the ProfileFragment and the transaction that added the EditProfileFragment has been saved under the "profile"
key. Those fragments have had their state saved completely and FragmentManager is holding onto their state alongside the transaction state. Importantly: those fragment instances no longer exist in memory or in the FragmentManager — it is just the state (and any non config state in the form of ViewModel instances):

Swapping back is simple enough: we can do the same saveBackStack() operation on our "notifications" transaction and then restoreBackStack():

fragmentManager.saveBackStack(“notifications”)

fragmentManager.restoreBackStack(“profile”)

The two stacks have effectively swapped positions:

This style of maintaining a single active back stack and swapping transactions onto it ensures that the FragmentManager and the rest of the system always has a consistent view of what actually is supposed to happen when the system back button is tapped. In fact, that logic remained entirely unchanged: it still just pops the last transaction off of the fragment back stack like before.

These APIs are purposefully minimal, despite their underlying effects. This makes it possible to build your own structure on top of these building blocks while avoiding any hacks to save Fragment view state, saved instance state, and non config state.

Of course, if you don’t want to build your own structure on top of these APIs, you can also use the one we provide.

Bringing multiple back stacks to any screen type with Navigation

The Navigation Component was built from the beginning as a generic runtime that knows nothing about Views, Fragments, Composables, or any other type of screen or ‘destination’ you might implement within your activity. Instead, it is the responsibility of an implementation of the NavHost interface to add one or more Navigator instances that do know how to interact with a particular type of destination.

This meant that the logic for interacting with fragments was entirely encapsulated in the navigation-fragment artifact and its FragmentNavigator and DialogFragmentNavigator. Similarly the logic for interacting with Composables is in the completely independent navigation-compose artifact and its ComposeNavigator. That abstraction means that if you want to build your app solely with Composables, you are not forced to pull in any dependency on fragments when you use Navigation Compose.

This level of separation means that there are really two layers to multiple back stacks in Navigation:

• Saving the state of the individual NavBackStackEntry instances that make up the NavController back stack. This is the responsibility of the NavController.
• Saving any Navigator specific state associated with each NavBackStackEntry (e.g., the fragment associated with a FragmentNavigator destination). This is the responsibility of the Navigator.

Special attention was given to the cases where the Navigator has not been updated to support saving its state. While the underlying Navigator API was entirely rewritten to support saving state (with new overloads of its navigate() and popBackStack() APIs that you should override instead of the previous versions), NavController will save the NavBackStackEntry state even if the Navigator has not been updated (backward compatibility is a big deal in the Jetpack world!).

PS: this new Navigator API also makes it way easier to test your own custom Navigator in isolation by attaching a TestNavigatorState that acts as a mini-NavController.

If you’re just using Navigation in your app, the Navigator level is more of an implementation detail than something you’ll ever need to interact with directly. Suffice it to say, we’ve already done the work required to get the FragmentNavigator and the ComposeNavigator over to the new Navigator APIs so that they correctly save and restore their state; there’s no work you need to do at that level.

Enabling multiple back stacks in Navigation

If you’re using NavigationUI, our set of opinionated helpers for connecting your NavController to Material view components, you’ll find that multiple back stacks is enabled by default for menu items, BottomNavigationView (and now NavigationRailView!), and NavigationView. This means that the common combination of using navigation-fragment and navigation-ui will just work.

The NavigationUI APIs are purposefully built on top of the other public APIs available in Navigation, ensuring that you can build your own versions for precisely your set of custom components you want. The APIs to enable saving and restoring a back stack are no exception to this, with new APIs on NavOptions, the navOptions Kotlin DSL, in the Navigation XML, and in an overload for popBackStack() that let you specify that you want a pop operation to save state or you want a navigate operation to restore some previously saved state.

For example, in Compose, any global navigation pattern (whether it is a bottom navigation bar, navigation rail, drawer, or anything you can dream up) can all use the same technique as we show for integrating with BottomNavigation and call navigate() with the saveState and restoreState attributes:

onClick = {
  navController.navigate(screen.route) {
    // Pop up to the start destination of the graph to
    // avoid building up a large stack of destinations
    // on the back stack as users select items
    popUpTo(navController.graph.findStartDestination().id) {
      saveState = true
    }

    // Avoid multiple copies of the same destination when
    // reselecting the same item
    launchSingleTop = true

    // Restore state when reselecting a previously selected item
    restoreState = true
  }
}

Save your state, save your users

One of the most frustrating things for a user is losing their state. That’s one of the reasons why fragments have a whole page on saving state and one of the many reasons why I am so glad to get each layer updated to support multiple back stacks:

• Fragments (i.e., without using the Navigation Component at all): this is an opt-in change by using the new FragmentManager APIs of saveBackStack and restoreBackStack.
• The core Navigation Runtime: adds opt-in new NavOptions methods for restoreState and saveState and a new overload of popBackStack() that also accepts a saveState boolean (defaults to false).
• Navigation with Fragments: the FragmentNavigator now utilizes the new Navigator APIs to properly translate the Navigation Runtime APIs into the Fragment APIs by using the Navigation Runtime APIs.
• NavigationUI: The onNavDestinationSelected(), NavigationBarView.setupWithNavController(), and NavigationView.setupWithNavController() now use the new restoreState and saveState NavOptions by default whenever they would pop the back stack. This means that every app using those NavigationUI APIs will get multiple back stacks without any code changes on their part after upgrading the Navigation 2.4.0-alpha01 or higher.

If you’d like to look at some more examples that use this API, take a look at the NavigationAdvancedSample (newly updated without any of the NavigationExtensions code it used to require to support multiple back stacks):

android/architecture-components-samples

And for Navigation Compose, consider looking at Tivi:

GitHub - chrisbanes/tivi: Tivi is a TV show tracking Android app, which connects to trakt.tv

If you do run into any issues, please make sure to use the official issue tracker to file bugs against Fragments or Navigation and we’ll be sure to take a look at them!

Multiple back stacks was originally published in Android Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Fragments: rebuilding the internals

Introducing: the new state manager

Fragments, more than most Android APIs, have evolved very organically over the years. They started as part of the Android platform itself, became a mirrored existence in the Android platform and as part of the Android Support Library, and now exist solely as part of Jetpack as AndroidX Fragments.

Note: you should under no circumstances use the Android framework version of Fragments. Besides being fully deprecated in Android 10, they weren’t receiving fixes for a considerable amount of time before that and, being baked into the framework, no backporting of fixes or consistency across devices and API levels can be expected.

While Architecture Components have taken over many of the roles that traditionally needed a Fragment (such as using a LifecycleObserver for Lifecycle callbacks or a ViewModel for retained state), if you’re using Fragments, you’re adding, removing, and interacting with them through a FragmentManager.

With Fragment 1.3.0-alpha08, some of the most significant restructuring of the internals of FragmentManager have been completed. This release swaps out much of the logic that used to live directly in FragmentManager with smaller, testable, and maintainable (internal) classes, the core of which is FragmentStateManager.

Note: I’m going to be talking a lot about the internals of FragmentManager in this post. TL/DR: please pay extra attention to regression testing with Fragment 1.3.0-alpha08 and file issues as soon as possible if you discover any regressions.

This new state manager is responsible for some pretty key parts of Fragments:

• Moving Fragments through their lifecycle methods
• Running animations and transitions
• Handling postponed transactions

We’ve taken a ground up look at how those systems previously work, found them wanting, and rewrote them from scratch. They’re now better than ever, we were able to close out 10+ long standing related issues, and the internal restructuring has cleared the way to build support for multiple back stacks in a single FragmentManager and simplify the Fragment lifecycle.

FragmentManager’s moveToState()

Each FragmentManager is associated with a host. In the vast majority of cases for fragments, this is a FragmentActivity (there is an entire layer of FragmentController and FragmentHostCallback for building your own custom host, but let’s avoid that discussion here). As the activity moves to CREATED, STARTED, and RESUMED, FragmentManager dispatches those changes down to its fragments. This is the role of moveToState().

Of course, it isn’t quite that straightforward. There is a lot of conditional logic to determine exactly what state the fragment should be in — the activity lifecycle state (or the parent fragment’s state for nested fragments) is only the first part and serves as the maximum state the fragment can be in. This maximum is there to ensure that the lifecycle of the activity, fragments, and their child fragments are all properly nested.

So our first order of business in simplifying moveToState() was to collapse all of that logic into one place. Thus was born FragmentStateManager. Each fragment instance is tied to a FragmentStateManager under the hood. By introducing this class internally, we were able to take much of code that interacts with the fragment (such as calling the fragment’s onCreateView and other lifecycle methods) out of FragmentManager itself.

That split also allowed us to write a single method that would take all of the backward compatible required logic for what state the fragment should actually be in and centralize it in one place: computeExpectedState(). This one method keeps track of all of the current state and determines what state the fragment should be in. 98% of the time, it is the same state as the host / parent fragment, but that 2% makes a big difference to those apps built on fragments.

However, we ran into one case where we didn’t have a way to determine the right state: postponed fragments.

Postponed fragments

Fragments, for better or worse, inherited a lot of the same nomenclature and API surface as activities. Part of this inheritance was around transitions and the ability to postpone your enter transition until you’re ready. This is critical to shared element transitions (where you really want to have an image loaded to know its dimensions and position on the screen before starting the transition over to that location), but also allows you to ensure that more intensive loading calls don’t happen at the same time as your transition, avoiding jank.

A postponed fragment has two important qualities:

1. Its view was created, but is not visible
2. Its lifecycle is capped at STARTED

As soon as you call startPostponedEnterTransition(), the fragment’s transition would run, the view would become visible, and the fragment would be able to move to RESUMED. This is, in fact, exactly what the new state manager does, but it was not how Fragments worked before. To quote the Postponed Fragments leave the Fragments and FragmentManager in an inconsistent state bug:

When a Fragment is postponed using postponeEnterTransition(), the expected behavior is that the container the Fragment is added to does not run any enter animations or previously queued up exit animations (i.e., for a replace() operation) until the Fragment calls startPostponedEnterTransition(). It is also expected that the Fragment does not reach the RESUMED state while its container is postponed.

However, it seems like FragmentManager isn’t just doing that, but instead is moving the Fragment and the whole FragmentManager into a weird, inconsistent state.

Namely, any FragmentTransaction that touches the container of the postponed Fragment is ‘rolled back’ (i.e., done in reverse), but those Fragments aren’t actually moved to their proper state.

This led to a litany of issues:

• The Fragment’s view is created, but the fragment isn’t added (isAdded() returns false)
• findFragmentById() doesn't return the newly added Fragment over the one it replaces, even when using commitNow()
• Fragments stuck in this limbo state don’t get started when the FragmentManager is started (https://issuetracker.google.com/issues/129035555)
• FragmentTransactions can be executed out of order (https://issuetracker.google.com/issues/147297731)
• Other animations on the container (such as previously started pop animations) still run (https://issuetracker.google.com/issues/37140383)
• onCreateView() can be called a second time (https://issuetracker.google.com/issues/143915710)

Actually fixing any of these issues meant replacing the entire roll back process used by postponed fragments with a system that keeps the FragmentManager in a consistent, up to date state, while still maintaining the important qualities of postponed fragments.

Working at the container level

FragmentManager has this nice (read: handy, but not fun as the maintainer) property where it lets you pass in any container ID for where you want to place a Fragment. Even for a single FragmentTransaction, you can add a fragment to one container, remove another from a different container, replace a third container’s topmost fragment, etc. The rub comes in when it comes to animating in/out the fragments — something that happens solely at the container level.

Fragments support a number of animating systems:

• The old and busted framework Animation API
• The framework Animator API
• The framework Transition API (only API 21+, also pretty busted)
• The AndroidX Transition API

As you might know, naming is one of the hardest problems in Computer Science, so when we went to build a class that could control all of these APIs, it took a while to settle on SpecialEffectsController (this class isn’t part of the public API, so names are still subject to change, thankfully). This class exists on the container level and coordinates all of the “special effects” associated with entering and exiting fragments.

The SpecialEffectsController is the single source of truth on what should be happening to that container. This means that if the topmost added fragment is postponed, the entire container is postponed. There’s no more logic needed at the FragmentManager layer, nor any rollback of transactions (which, as we mentioned, can affect multiple containers). Thus, the FragmentManager is in the correct state and we still get all of the special properties of postponed fragments.

This base API then allowed us to centralize all of the crazy special effects APIs that fragment has into a single DefaultSpecialEffectsController that is responsible for running transitions and animations and animators. Again, moving logic that used to be scattered across FragmentManager into a single place.

So what does a ‘new state manager’ mean

Well, it means that instead of this architecture:

It looks more like this:

By splitting up the internals of FragmentManager, the logic has been greatly simplified at each layer:

• The FragmentManager only has state that applies to all fragments
• The FragmentStateManager manages the state at the fragment level
• The SpecialEffectsController manages the state at the container level

This separation of responsibilities has let us expand our test suite by almost 30%, covering many more scenarios that were near impossible to test in isolation.

Should I expect behavior changes?

No. In fact, we run a significant portion of the internal fragment tests against both the old and new state managers specifically to ensure we have a strong set of regression tests in place.

However, if you were relying on the inconsistent state a postponed fragment put the FragmentManager into, then yeah, you’ll find that you now actually get the correct state. You’ll find the list of bug fixes associated with the new state manager as part of the release notes, so take a look through that to make sure that your issues aren’t caused by your own workarounds for the old broken behavior that you can now just remove.

Similar to the changes to onDestroyView timing in Fragment 1.2.0, the new state manager will keep your fragment in the STARTED state until its transitions/animations/animators/special effects all finish, thus bringing consistency across all fragments, whether they are postponed directly or postponed because of other fragments in that same container.

What if I *do* see behavior changes?

After you upgrade to Fragment 1.3.0-alpha08, the new state manager is enabled by default. If you see differences in your app, the first step is to see if it is related to the new state manager by using the new experimental API:

FragmentManager.enableNewStateManager(false)

This API is an escape hatch back into the old world and lets you verify that any changes you’re seeing are tied to the new state manager. This unblocks you from upgrading the Fragment 1.3.0-alpha08 and lets you build a sample project that reproduces the issue that you can attach when you file an issue against Fragments.

Note: the FragmentManager.enableNewStateManager() API is experimental. That means that it is not considered part of the stable API surface of Fragments and can be removed at any point. Removing all of the old code is a significant code reduction, but given the importance of getting this right, we likely won’t remove the API until after the stable release of Fragment 1.3.0 — i.e., consider it on notice for removal in a Fragment 1.3.1 release.

With over 100 individual changes over an 11 month period, this is absolutely the largest internal change to Fragments in a while and sets us up for a much more maintainable, sustainable, and understandable code base. That means more consistent behavior across Fragments and a firm base you can rely on when building your app. We’d appreciate any help you can offer in making sure this new state manager is the best it can be by continuing to file issues and offering feedback.

Fragments: Rebuilding the Internals was originally published in Android Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Commands get an upgrade

Since the first release of Muzei, sources have been able to provide custom commands. Each command would appear in the overflow menu. When the user tapped the command, it would trigger the onCommand() method of your MuzeiArtProvider.

This approach had two big issues:

1. It was hard for users to find a command behind the overflow menu.
2. Due to restrictions on starting activities from the background, any attempts to start an activity from onCommand() would fail on Android 10 and higher devices.

Muzei 3.4 address both of these concerns via a new API based on RemoteActionCompat which you can see as soon as you load up Muzei 3.4.

Yep, the new getCommandActions() API lets you associate an icon with your command and respects the use of setShowAsIcon(true) to show your command as an icon right next to the Next Artwork command (there is a limit to how many icons can be displayed, so your action may still be displayed in the overflow menu if you overuse this functionality).

The new API also uses a PendingIntent to trigger your command. This means that launching an activity from a command just means you use PendingIntent.getActivity and that works exactly the same across all API levels (even on the latest versions of Android) without the need to use Intent.FLAG_NEW_TASK either. Similarly, if you have background work, you’d use PendingIntent.getBroadcast or PendingIntent.getService to do your work.

Examples of custom commands

The UnsplashExampleArtProvider has two commands — one that shows as an icon to go to the author’s Unsplash profile and a second that lets you visit Unsplash to explore more artwork.

Creating the profile command is based on the Artwork passed to getCommandActions() (remember, each Artwork can have separate commands):

private fun createViewProfileAction(
    context: Context,
    artwork: Artwork
): RemoteActionCompat {
    val profileUri = artwork.metadata?.toUri() ?: return null
    val title = context.getString(R.string.action_view_profile,
        artwork.byline)
    val intent = Intent(Intent.ACTION_VIEW, profileUri)
    return RemoteActionCompat(
            IconCompat.createWithResource(context,
                R.drawable.source_ic_profile),
            title,
            title, // content description for the tooltip
            PendingIntent.getActivity(context, 0, intent,
                PendingIntent.FLAG_UPDATE_CURRENT))
}

Here, the Unsplash Example source has used the metadata field to store the profile URI for the user. For the icon, RemoteActionCompat relies on IconCompat, which lets you build an icon from a bitmap, content:// URI, a byte array, or the most common case: a resource ID. Each icon should be 24x24dp. You’ll provide a title (which will appear if the action is in the overflow menu) and a content description (which will be used as the tooltip for the icon) and the PendingIntent that should be triggered when the command is tapped.

Creating the visit Unsplash action for the overflow menu is very similar with constructing the RemoteActionCompat:

private fun createVisitUnsplashAction(
    context: Context
): RemoteActionCompat {
    val title = context.getString(R.string.action_visit_unsplash)
    val unsplashUri = context.getString(R.string.unsplash_link)
    val intent = Intent(Intent.ACTION_VIEW, unsplashUri.toUri())
    return RemoteActionCompat(
            IconCompat.createWithResource(context,
                R.drawable.muzei_launch_command),
            title,
            title,
            PendingIntent.getActivity(context, 0, intent,
                PendingIntent.FLAG_UPDATE_CURRENT)).apply {
        setShouldShowIcon(false)
    }
}

Muzei API 3.4 ships with an R.drawable.muzei_launch_command icon which can be used as a default icon for your command. You’ll note that we need to explicitly call setShowShowIcon(false) — the default for a RemoteActionCompat is true, so you’ll need to set it to false if you always want your command to only appear in the overflow menu.

By extracting these out into their own methods, getCommandActions() can simply return a listOf() including the two RemoteActionCompat instances returned by the methods.

Integration with the File Picker

Android has provided a mechanism for integrating your own app into the default file picker and Files app since API 19 in the form of a custom DocumentsProvider. But actually implementing one is easier said than done.

To make it easy to expose artwork from your MuzeiArtProvider to the default file picker, Muzei API 3.4 now allows you to add a prebuilt MuzeiArtDocumentsProvider to your manifest:

<provider android:name="com.google.android.apps.muzei.api.provider.MuzeiArtDocumentsProvider"
  android:authorities="${yourAuthority}.documents"
  android:exported="true"
  android:grantUriPermissions="true"
  android:permission="android.permission.MANAGE_DOCUMENTS">
  <intent-filter>
      <action android:name="android.content.action.DOCUMENTS_PROVIDER" />
  </intent-filter>
</provider>

You’ll note the android:authorities — this needs to match the android:authorities on your MuzeiArtProvider entry in your manifest plus the .documents suffix. With just that, the two providers will automatically be kept in sync. There’s no extra work you need to do besides opting in to this new API.

Note: this API is most appropriate when your provider provides multiple artwork via addArtwork or setArtwork with multiple artwork. Avoid using this for artwork like the ‘Featured Art’ source that only have one artwork.

Muzei 3.4’s ‘My Photos’ source takes advantage of this out of the box, allowing you to add one of your chosen photos to an email you’re composing in Gmail or allow manually backing up your images by copying them to your local storage or Google Drive.

Improved performance

One of the most critical user experiences is selecting your source for the first time. Each moment the user needs to wait for that first artwork to appear stretches on forever.

Just by upgrading your source to Muzei API 3.4, you’ll find vastly improved performance when you call setArtwork or addArtwork with a large number of artwork. This can result in changes that used to take 16 seconds to now take less than a second and particularly large data sets of 1000s of images (which used to take 1–2 minutes!) now also take just a second.

Better User Onboarding for Sources

When building a custom source, the trickiest part is perhaps getting users from installing your app to actually selecting your source. This has often involved giving users instructions to manually follow.

This is even more critical when running on Android 10 or higher devices, where launchers using the standard LauncherApps.getActivityList() API will show an icon for every app. While it helps raise awareness that your app is installed, the default behavior of just linking to the system Settings screen for you app (with an Uninstall button) is not particularly useful.

Muzei API 3.4 adds two new APIs which greatly improve this critical flow:

• The isProviderSelected() API lets you check whether your source has been selected by the user in Muzei.
• The createChooseProviderIntent() API lets you deep link directly into Muzei’s Sources screen, scrolling directly to your source so that user can immediately select it.

This lets you verify that user has selected your source and, if not, redirect them directly to where they can go to select it.

It is strongly recommended to catch any ActivityNotFoundException raised when starting the Intent returned by createChooseProviderIntent() and falling back to getLaunchIntentForPackage() with Muzei’s package name (to support older versions of Muzei that don’t support deep linking to the Sources screen) and a link to Muzei’s Play Store listing (in cases where the user has not installed Muzei at all).

For a full example, look at Muzei Ghibli’s RedirectActivity.

And so much more…

Muzei 3.4 has plenty of other improvements:

• Muzei 3.4 is the first version translated to other languages! If you’d like to help our crowdsourcing effort in expanding Muzei to support every language, please join our Crowdin project.
• If you’re shipping a version of your source that can be installed directly on Wear OS devices, custom commands you publish will now be displayed (using those nice icons you provide via getCommandActions()).

Muzei API 3.4 also has its own improvements:

• The long deprecated MuzeiArtSource API has been removed entirely.
• The Muzei API has been completely rewritten in Kotlin. You’ll notice a number of reified versions of methods (avoiding that ::class.java mess) and the fact that Artwork is now a immutable class. You can certainly still write your source in the Java programming language, but we’d certainly strongly recommend moving to Kotlin.
• The reference docs at api.muzei.co have been fully updated for Muzei 3.4 with improved examples and cross linking between related documentation.

Muzei has been a huge passion project for me and I can’t thank Roman Nurik for giving me the opportunity to continue to contribute.

If you’re looking for examples for upgrading your source to Muzei API 3.4, take a look at pull requests I’ve filed for:

• Muzei Ghibli
• Muzei Earth View
• Muzplash
• Pixel Art for Muzei
• Muzei Bing Image of the Day
• Muzei Photos Album
• Heroes Comic Covers for Muzei
• Distant Worlds for Muzei

If you’d like to help sponsor future development and provide a token of gratitude (and get into Muzei’s private alpha!), you can sponsor me on Github.

Muzei 3.4 was originally published in muzei on Medium, where people are continuing the conversation by highlighting and responding to this story.

Muzei Live Wallpaper 3.2.0 is now available via the beta channel!

As the first release after the target API 26 requirement, much of the changes here are around ensuring that Muzei and the Muzei API are fully compliant with the latest versions of Android.

Legacy Sources

Let’s talk about Legacy Sources. Namely, Sources that use the Legacy API, which was fully replaced with the Muzei 3.0 API back in July 2018.

As per the Legacy Sources blog post, Legacy Sources require targeting API 25 or lower (they literally don’t work if you target API 26 or higher). This also includes Muzei’s side of the Legacy Source API. With the requirement to target API 26 or higher to be on the Google Play Store, Muzei cannot directly support Legacy Sources anymore.

If you install a Legacy Source, Muzei will now send you a notification informing you as such (so you don’t go into Muzei just to not see your newly installed source).

For a long time, I believed that this restriction meant that users upgrading to Muzei 3.2 would have no recourse at all if they wanted to continue to use a Legacy Source. However, through some significant restructuring, we now provide a separate Muzei Legacy app that allows you to continue to use Legacy Sources even in Muzei 3.2 or higher.

Given the pre-existing issues with Legacy Sources, I cannot recommend ever using a Legacy Source, particularly on API 23 and higher devices. You should still send feedback to the apps using the Legacy API to ask them to upgrade to the Muzei 3.0 API.

Light theme

One of the new features in Android Q is full support for a dark theme. Of course, Muzei had a dark theme since the very beginning so, in an ironic twist, Muzei 3.2 is adding a light theme!

With Muzei’s emphasis on the wallpaper itself, this mostly comes in changing some of the dark UI elements and cards to light, but also affects some more subtle sections (the Auto Advance screen now has a dark background instead of the blue background to avoid large blocks of relatively bright backgrounds, for example).

Muzei API 3.2.0

Alongside Muzei 3.2.0 is also a new version of the Muzei API, 3.2.0. This has one important API change for those apps targeting API 29 or higher (replacing openArtworkInfo() with getArtworkInfo() to avoid starting an activity from the background). It also officially deprecates the Legacy API and switches to AndroidX.

Try out Muzei 3.2.0 now!

Of course, like any new release, we’ve also squashed a ton of bugs, made a lot of reliability improvements, and have tuned a lot small things:

• We’ve updated the Auto Advance icon on the Sources screen to better match its functionality (it now looks like a timer)
• When Muzei is your active wallpaper, going to settings from the Live Wallpaper picker will open the full Muzei experience, allowing you to change your selected Source and other options without finding the app icon in your launcher
• Muzei now supports multi-window mode and has better support for foldable devices

Check out Muzei 3.2 by joining the beta channel and downloading Muzei from the Google Play Store.

Muzei Live Wallpaper 3.2.0 Alpha 1 was originally published in muzei on Medium, where people are continuing the conversation by highlighting and responding to this story.

Muzei Live Wallpaper - Apps on Google Play

In addition to being a live wallpaper for your Android phone and tablet, Muzei was a launch partner for custom watch faces on Wear OS (née Android Wear) and has continued to take advantage of newer patterns such as complication support and standalone Wear OS devices.

Bridging Notifications

One important (and for many, the most important part) of their Wear OS device is in “bridging” phone notifications onto their watch, allowing quick actions without getting your phone out. While normally, this is exactly what you want, Muzei runs into an interesting edge case where we felt it important to take control of the bridging behavior.

Muzei’s Wear OS app supports two different modes:

• Mirroring the current image displayed by Muzei on your phone
• Using another Source, such as the included Featured Art Source, running directly on the watch — no phone app needed at all

While the first case works fine (you see Muzei’s phone side notification of a new wallpaper on your watch), the later ended up being a source of confusion — you’d see a ‘New wallpaper’ notification, but your watch face continues to show a completely separate wallpaper.

Therefore in Muzei 3.1.0, Muzei’s Wear OS specifically disables phone notifications from Muzei only if the following two conditions are true:

1. You’re actively using Muzei on your watch either via Muzei’s watch face or one of Muzei’s complications on another active watch face
2. You’re using a different source on your watch other than the ‘From phone’ Source

As soon as you change either of these conditions, the next notification posted by Muzei’s phone app will appear on your watch (unfortunately, the bridging APIs don’t automatically update the state of all current notifications).

Bug Fixes and Performance Improvements

Like most apps, we’re continuing to improve with each release and this release is no different.

We’ve fixed a bug that prevented you from using rotary input (i.e., rotating the side button) when you open Muzei’s Wear OS app. Should make it just a bit easier to interact with the app, be it to view the current artwork’s details or change your selected Source.

We’ve also done a full pass on reliability, updating to the recent stable version of WorkManager, ensuring that loading images (be it from your phone or otherwise) works consistently every time.

In addition, if you’re a different Source on your watch, such as Muzei Ghibli, you’ll now notice that Muzei shows a link to the Source’s Settings screen — the same will be true for any Source that has a Settings screen.

Wear OS improvements are here, more to come

While this Muzei 3.1.0 is specifically for Wear OS, there’s more improvements for Muzei in the works for both the phone and Wear OS app. Make sure to follow the Muzei publication for updates!

muzei

Muzei 3.1.0 for Wear OS was originally published in muzei on Medium, where people are continuing the conversation by highlighting and responding to this story.

Muzei Live Wallpaper - Apps on Google Play

This is a culmination of over a year and half of work and comes with significant new features, a visual refresh, and a brand new API that greatly improves reliability.

What’s New

A brand new plugin API

With significant changes to Android since Muzei’s release back when Android 4.4 KitKat was the latest version of Android, a complete rewrite was needed for Muzei’s API to ensure that it was compatible with Doze and App Standby as well as Background Execution Limits.

The result is a new, modern API that works great on all versions of Android that is much, much more reliable than the previous API. By preloading the next wallpaper ahead of time, hitting the Next button in Muzei will instantly start the transition to the next wallpaper, even if you’re offline.

The new API is also fully compatible with the Google Play Store requirement to target API 26 or higher.

Auto Advance

When it comes to large, often 4k+ wallpaper images, ensuring that Muzei isn’t burning through data is incredibly important. Muzei 3.0 introduces a new set of centralized settings called Auto Advance. These new settings give users control over how often their wallpaper should change and whether Muzei should delay loading new wallpapers until you are Wi-Fi.

Being built directly into Muzei, Auto Advance applies to all sources built with the new API and removes the need for each source developer from building these same settings themselves.

Improved integration with Tasker

Tasker is still one of the most flexible methods for customizing your phone and was a natural fit for Muzei. While previous versions of Muzei only allowed you to trigger the ‘Next’ action from Tasker, Muzei 3.0 adds the ability to change to any source from Tasker.

Now when you select Muzei from Tasker’s Plugin screen, you’ll be given the option to choose between all of the Sources built with the new API on your device as the action to trigger.

Improved control over effects

Since the beginning, Muzei has focused on making a background that fits perfectly with your home screen by offering blurring, dimming, and reduced saturation effects to apply to the wallpapers available through Muzei.

With Muzei 3.0, users now have complete control over what effects they apply on not only the home screen, but also on the lock screen.

So if you’re after a blurry lock screen background or a crystal clear greyscale home screen background, you’ll be able to customize Muzei exactly how you want it.

Gesture Controls

Being a live wallpaper, Muzei can receive tap events when interacting with your home screen. Expanding on the previous option to double tap to temporarily disable the effects, Muzei now supports three finger tap gestures and customizing the action.

This allows you to customize Muzei and avoid conflicting gestures (such as with devices that use double tap to turn the screen off) while still avoiding accidental triggering of the actions when interacting with the icons or widgets on the home screen.

A standalone Wear OS experience

Muzei was a launch partner for watch faces on Android Wear and has continued to improve the experience since then, including support for watch face complications, allowing you to use your Muzei wallpaper as the background for Muzei’s watch face as well as many other watch faces.

With Muzei 3.0, you can use Muzei on your Wear OS device without using Muzei on your phone. In addition to the existing support for mirroring your Muzei wallpaper from your phone, Muzei on Wear OS can also use the ‘Featured art’ source directly. One additional side effect of this change is that you can now use Muzei for Wear OS even if you have an iOS device.

Third party plugin developers can also publish their sources for Wear OS and they’ll show up alongside the ‘Featured art’ and ‘From phone’ Source.

What’s Next

Muzei 3.0 is out now and can be downloaded from Google Play. You can get early access to future versions of Muzei by joining the open beta program.

The Muzei 3.0 API is final and available to all developers to integrate into their app. I’d strongly recommend joining the Muzei Google+ community as the best place to ask questions about Muzei and about the Muzei API (you’ll also get alpha access to early builds of Muzei if you join that community and then join the testing program at the above link).

Many of the existing sources on the Play Store are still using the previous Muzei 2.x Legacy API. These Legacy Sources are still partially supported in Muzei 3.0, but given their complete incompatibility with the target API 26 requirement, support for Legacy Sources will be removed in a future version of Muzei on API 23+ devices. Please, please send feedback to Legacy Sources asking them to convert to the Muzei 3.0 API. The Muzei 3.0 API blog post goes through the new API in detail and they can always contact us at support@muzei.co with any questions.

I’m extremely excited about this Muzei release, but even more excited about the further improvements planned for future versions. Follow along with all of the announcements on our Medium publication at medium.com/muzei.

muzei

Announcing Muzei Live Wallpaper 3.0 was originally published in muzei on Medium, where people are continuing the conversation by highlighting and responding to this story.

Muzei offers a plugin system that allows any app to provide wallpapers for display in Muzei. Muzei 3.0 introduced a new API that fixes a number of long standing issues, particularly on API 23+ and the battery optimizations changes introduced on those newer versions of Android.

Apps built with the previous Muzei 2.x Legacy API are classified as ‘Legacy Sources’ in Muzei 3.0 and are no longer directly supported in Muzei 3.2 and higher.

What’s different about Legacy Sources?

No support for Auto Advance

Legacy Sources load new wallpapers in two steps:

1. Based on their own internal logic, they ‘publish’ new wallpapers to Muzei with a URL to load the wallpaper from.
2. Muzei then loads the new wallpaper immediately.

This means that the decision on when to load new wallpapers depend entirely on the Legacy Source. This means that Legacy Sources don’t support Auto Advance.

Therefore it is not possible to control how often Legacy Sources load new wallpapers or if they wait until the device is on WiFi unless the Legacy Source has built those specific settings.

It also means that data usage caused by downloading wallpapers is attributed to Muzei itself (since it is Muzei that downloads the wallpaper on the Legacy Source’s request), rather than attributed to the Legacy Source itself. This is in contrast to Muzei 3.0 Sources which have their data usage properly attributed to the Source, not to Muzei.

Requirement to disable Battery Optimizations on API 23+ devices

Due to how to the Legacy API was built and Android’s evolution, you must manually disable Battery Optimizations on Legacy Sources on API 23 (Marshmallow, Android 6.0) and higher devices.

Note: you do not need to disable Battery Optimizations on Muzei itself — only on the third party app providing the Legacy Source you want to use.

This is generally done through the Settings app on your device. However, the location for these settings can differ by manufacturer. Generally, Google searching for ‘YOUR DEVICE NAME battery optimizations’ will bring up relevant results for disabling battery optimizations.

What’s the future for Legacy Sources?

In late 2018, Google Play is enforcing that all new apps and updated apps target API 26 or higher. The Legacy API is totally incompatible with apps that target API 26 or higher, meaning that all new plugins and apps still publishing updates must move to the Muzei 3.0 API.

Note: Muzei has disallowed apps that target API 26+ from using the Legacy API even on Muzei 2.6.0 builds for exactly this reason.

Please send feedback to any apps providing a Legacy Source with a link to the Muzei 3.0 API.

Muzei 3.0 and the new API

You can also tell them that they can email support@muzei.co for help moving to the new API (including help writing their new API support if the app is open source!).

What happens to Legacy Sources that aren’t updated?

To continue to push updates to Muzei after November 2018, Muzei itself must target API 26 or higher, which means that Muzei 3.2 removes direct support for Legacy Sources.

However, to avoid cases where users upgrading lose permanent access to Legacy Sources, we have made Muzei Legacy available as an additional installation (not through the Google Play Store, given that it needs to target API 25) to re-add support for Legacy Sources to Muzei 3.2 or higher.

Given all of the above issues with Legacy Sources, it is still strongly recommended to avoid using Legacy Sources, particularly on API 23 and higher devices. Please send feedback to Sources continuing to use the Legacy API to have them convert to the Muzei 3.0 API.

Muzei 3.0 and Legacy Sources was originally published in muzei on Medium, where people are continuing the conversation by highlighting and responding to this story.

As previously discussed in my The Muzei Plugin API and Android’s Evolution post, a lot has changed in Android since Muzei was first released by Roman Nurik back in the times of Android 4.4.

This has meant a full rewrite of both Muzei and its API has been necessary to ensure that it is compatible with Doze and App Standby as well as Background Execution Limits.

I’m happy to announce that alongside the first alpha of Muzei 3.0, an alpha of the new Muzei API is available that brings the API in alignment with the latest best practices and offers some significant improvements to the overall user experience for Muzei.

Edit: the Muzei 3.0 API is now available in beta and is expected to be forward compatible with Muzei 3.0 as we move towards a full production release.

No more unresponsive Next buttons

Rewriting an entire app and plugin ecosystem is not something to be taken lightly so any new API needed to offer a significantly better user experience, both to end users and to developers.

One of the main complaints of Muzei is that you’d hit the ‘Next’ button in the app and nothing would happen. That’s a bad user experience in all regards that the new API seeks to remove entirely even as a possibility.

Supporting multiple artwork

Unlike the previous MuzeiArtSource based API that had just a single publishArtwork method and a single current artwork, the new API is now based on a MuzeiArtProvider class — a special subclass of ContentProvider.

This new structure allows your MuzeiArtProvider to add multiple artwork at once. For example, if your network call to your backend returns 30 images, you no longer need to randomly pick one and throw the other 29 away. Instead, you can call addArtwork 30 times and Muzei will automatically go through all 30 in the order you add them before asking you to load more artwork. Besides significantly lowering the amount of requests to your backend, this allows Muzei’s UI to only show the Next button if you actually have more artwork ready.

This fundamental change also means the entry point for your MuzeiArtProvider is significantly changed. Rather than a call to onUpdate or onTryUpdate every time the wallpaper changes, you now get a callback to onLoadRequested only when Muzei loads the last new image. This should be your cue to load more artwork!

Note: not every source has an endless backend of new artwork. Don’t worry about it. Even if you don’t load new artwork in response to onLoadRequested, Muzei will loop back through the rest of the artwork you have, loading older artwork randomly (while avoiding selecting recently shown artwork) without you having to do any extra work.

Pre-loading artwork

The time between hitting the Next button and the next wallpaper displaying is the absolutely most nerve racking time for users — it has to be quick and reliable every time.

With this in mind, Muzei will now pre-load the next artwork before it is displayed, ensuring there is already a locally cached copy available before the user can even hit the Next button. This ensures that even if the user is offline, if they can see a Next button, it will go to a new wallpaper. It also means transitions are near instantaneous, even on slow internet connections!

Downloading the artwork itself

Another significant change with the new API is that downloading artwork happens on the plugin side. Instead of Muzei using the call to publishArtwork as a sign to kick off its own download process, the downloading now happens via a call to your MuzeiArtProvider’s openFile method, which returns an InputStream to your image.

The default implementation of openFile handles much of the same cases as the previous API such as content:// or android.resource:// Uris as well as basic, unauthenticated http:// or https:// Uris.

Note: Muzei enforced TLS support on Android platform versions that required it to specifically be enabled. You now need to do this work yourself. An example of this can be found in the SourceArtProvider.

Since openFile is being called within your plugin’s process, there’s no longer any need to use a FileProvider or similar solution for loading local images that you have access to — a regular old file:// URL generated from Uri.fromFile actually works fine.

This flexibility also opens up the possibility to download images from authenticated servers or support custom protocols outside of http and https all completely transparently to Muzei itself.

When Muzei updates

One consistent feature request we’ve gotten for Muzei is better control over when Muzei transitions to the next wallpaper. Different plugins would add different settings on when to publish new artwork or whether to only update when you are on Wi-Fi.

With the new API, the settings controlling when wallpaper is loaded have been centralized within Muzei through a new set of options called Auto Advance.

For sources built on the MuzeiArtProvider API, users will be able to configure at what interval they want to automatically advance to the next artwork and whether that should only happen over Wi-Fi. Individual plugins no longer need to specify or control these settings themselves — as long as you provide artwork when onLoadRequested is called, Muzei will handle everything else.

Implementing onLoadRequested

We’ve talked about how important onLoadRequested is, so it deserves some extra attention to explain exactly how to implement it. We’ll be using the example-unsplash project as our example project. It implements a straightforward plugin that downloads the latest popular photos from Unsplash.

Our UnsplashExampleMuzeiArtProvider's onLoadRequested looks like:

override fun onLoadRequested(initial: Boolean) {
  UnsplashExampleWorker.enqueueLoad()
}

Yep, that’s it. While onLoadRequested is called on a background thread (so it is safe to do database or shared preference calls), it is strongly, strongly recommended to push the actual loading to WorkManager, JobScheduler, or JobIntentService.

Personally, I strongly prefer WorkManager for this kind of work since it will start execution immediately if conditions are met (say, you’re connected to the internet) and offers control over retrying. Muzei has been using it in production for all of the source loading as of Muzei 2.6.0.

The UnsplashExampleWorker is no more complicated. Its core doWork method looks like:

override fun doWork(): Result {
  val photos = try {
    UnsplashService.popularPhotos()
  } catch (e: IOException) {
    Log.w(TAG, "Error reading Unsplash response", e)
    return Result.RETRY
  }
  if (photos.isEmpty()) {
    Log.w(TAG, "No photos returned from API.")
    return Result.FAILURE
  }
  val attributionString =
      applicationContext.getString(R.string.attribution)
  photos.map { photo ->
    Artwork().apply {
      token = photo.id
      title = photo.description ?: attributionString
      byline = photo.user.name
      attribution = 
          if (photo.description != null) attributionString else null
      persistentUri = photo.urls.full.toUri()
      webUri = photo.links.webUri
      metadata = photo.user.links.webUri.toString()
    }
  }.forEach { artwork ->
    ProviderContract.Artwork.addArtwork(applicationContext,
        UnsplashExampleArtProvider::class.java,
        artwork)
  }
  return Result.SUCCESS
}

We load from a Retrofit service, create a new Artwork object for each photo returned from the API, then call ProviderContract.Artwork.addArtwork to add the artwork to the correct MuzeiArtProvider.

Unlike the previous API where all calls to publishArtwork needed to be within the MuzeiArtSource itself (forcing you to start the service, and your own action handling in onStartCommand, etc), the ProviderContract.Artwork class has static methods for common operations, such as getting the last artwork or adding new artwork, that can be called from anywhere in your application.

As a convenience, each of the static methods in ProviderContract.Artwork also has a non-static equivalent in MuzeiArtProvider, so calling addArtwork within the MuzeiArtProvider is as straightforward as it gets.

Note: as a MuzeiArtProvider is a ContentProvider itself, you can also use all of the ContentResolver based APIs such as query and delete using the base content URI returned by ProviderContract.Artwork.getContentUri and the column names in ProviderContract.Artwork .

Adding custom commands

Muzei’s API has always offered the ability to add custom commands to your plugin, giving users additional plugin specific actions they can take.

As the concept of the ‘Next Artwork’ is now controlled entirely by the existence of more valid artwork being added to your MuzeiArtProvider, the commands you return from the getCommands method should now all be custom commands (the default behavior is to return an empty list).

The Unsplash Example returns two custom commands:

override fun getCommands(artwork: Artwork) = listOf(
    UserCommand(COMMAND_ID_VIEW_PROFILE,
        context.getString(R.string.action_view_profile, 
            artwork.byline)),
    UserCommand(COMMAND_ID_VISIT_UNSPLASH,
        context.getString(R.string.action_visit_unsplash)))

You’ll note that we’re given the Artwork object that these commands should be associated with. This allows you to customize what commands are supported on an artwork by artwork basis or, like this example, customize the strings used for your actions with information from your artwork.

Handling commands is then done from the onCommand method, which also gets the Artwork object and the id of the action that was selected.

The Unsplash Example implements this with a simple when statement:

override fun onCommand(artwork: Artwork, id: Int) {
  when (id) {
    COMMAND_ID_VIEW_PROFILE -> {
       val profileUri = artwork.metadata?.toUri() ?: return
       context.startActivity(Intent(Intent.ACTION_VIEW, profileUri))
    }
    COMMAND_ID_VISIT_UNSPLASH -> {
      val unsplashUri = context.getString(R.string.unsplash_link) +
          ATTRIBUTION_QUERY_PARAMETERS
      context.startActivity(Intent(Intent.ACTION_VIEW,
          unsplashUri.toUri()))
    }
  }
}

You’ll note that here we use the metadata property. This String property is not used by Muzei in any way so you can repurpose it for whatever extra information you want to attach to each Artwork. In this case, we attach the URL of the photographer’s profile.

Adding a MuzeiArtProvider to your Manifest

Just like any other ContentProvider or service, you must add your MuzeiArtProvider to your manifest:

<provider
  android:name="com.example.CoolArtworkMuzeiArtProvider"
  android:authorities="com.example.coolartwork"
  android:label="@string/name"
  android:description="@string/description"
  android:exported="true"
  android:permission=
    "com.google.android.apps.muzei.api.ACCESS_PROVIDER">
  <intent-filter>
    <action android:name="com.google.android.apps.muzei.api.MuzeiArtProvider"/>
  </intent-filter>
</provider>

You’ll that it is strongly recommended to add the android:permission to your MuzeiArtProvider. This ensures that only your app and Muzei can read your Artwork. (Of course, you could leave it off if you want any app to be able to read your Artwork — your choice.)

Similar to a MuzeiArtSource, you can use <metadata> tags for a settingsActivity and setupActivity . More information on this can be found in the documentation.

Migrating from MuzeiArtSource

For users using Muzei 3.0, sources using MuzeiArtSource will appear in a separate ‘Legacy Sources’ option within Muzei’s ‘Sources’ screen, clearly delineating them from the modern sources built using MuzeiArtProvider. This is absolutely an intentional change.

If your app targets API 26 or higher

With the Target API level requirement for late 2018 enforcing a targetSdkVersion of 26 or higher for all updates to existing apps starting in November 2018, you might be considering changing your targetSdkVersion now.

If you update your targetSdkVersion now, note that the MuzeiArtSource API will no longer work. At all. Muzei has been enforcing this for quite some time, making your source unselectable.

In this case, you can safely delete your MuzeiArtSource and add a new MuzeiArtProvider .

Supporting both the old and new API simultaneously

To give the best experience for Muzei users in the short term, it is strongly recommended to support both the old and new API simultaneously by keeping your MuzeiArtSource functional while also providing a MuzeiArtProvider implementation for users already on Muzei 3.0.

In order to avoid duplicate sources in Muzei’s UI and to automatically migrate users of your existing MuzeiArtSource to your new MuzeiArtProvider, you should add a replacement metadata element to your MuzeiArtSource :

<service
  android:name="com.example.muzei.unsplash.UnsplashExampleArtSource"
  android:label="@string/name"
  android:description="@string/description"
  android:icon="@drawable/ic_source"
  tools:ignore="ExportedService">
  <intent-filter>
    <action android:name="com.google.android.apps.muzei.api.MuzeiArtSource"/>
   </intent-filter>
   <meta-data
     android:name="color"
     android:value="@color/colorPrimary"/>
   <meta-data
     android:name="replacement"
     android:value="com.example.muzei.exampleunsplash"/>
</service>

Muzei will read that metadata attribute and ensure that only your MuzeiArtProvider is visible in the Muzei UI and any users are automatically migrated over to the MuzeiArtProvider with the given authority.

Timeline for Muzei 3.0 and beyond

Muzei 3.0 is in beta right now and it will have a longer alpha / beta period to give you developers a chance to exercise and give feedback on the new API. It will then to go production and all users will have access to sources built on the new API.

Before the November 2018 requirement to target API 26+, another Muzei release will be made, warning users that still have a legacy source selected that their legacy source will stop working on ~January 2019.

In ~January 2019, Muzei itself will upgrade to target API 26+ and all support for MuzeiArtSource built plugins will be dropped (it literally won’t work at all).

Get started today

Update: Muzei 3.0 is now available in the open beta!

Muzei 3.0 is available in alpha today. To join the alpha:

1. Join the Muzei Google+ Community
2. Opt in to alpha testing (you may need to leave the tester program and rejoin if you previously were beta testing Muzei)
3. After ~15 minutes, you should see an update available via the Google Play Store

If you’d like to get started with the new API, update your dependency:

implementation "com.google.android.apps.muzei:muzei-api:3.0.0-beta02"

You can download the aar, sources.jar, or javadoc.jar from the Github release page.

Note: The Muzei 3.0 API is in beta and subject to minor bug fixes. The API as written now will be forward compatible with Muzei 3.0 releases and is safe to use in production.

Feedback is greatly appreciated. The best way to contact us through the Google+ community or by sending an email to support@muzei.co.

Muzei 3.0 and the new API was originally published in muzei on Medium, where people are continuing the conversation by highlighting and responding to this story.