Activity embedding

Stay organized with collections Save and categorize content based on your preferences.

Activity embedding optimizes apps on large screen devices by splitting an application's task window between two activities or two instances of the same activity.

Figure 1. Settings app with activities side by side.

Updating legacy codebases to support large screens is labor intensive and time consuming. Converting activity‑based apps to multi-pane layouts using fragments requires significant refactoring.

Activity embedding requires little or no refactoring of your app. You determine how your app displays its activities—side by side or stacked—by creating an XML configuration file or by making Jetpack WindowManager API calls.

Support for small screens is maintained automatically. When your app is on a device with a small screen, activities are stacked one on top of the other. On large screens, activities are displayed side by side. The system determines the presentation based on the configuration you’ve created—no branching logic required.

Activity embedding supports device orientation changes and works seamlessly on foldable devices, stacking and unstacking activities as the device folds and unfolds.

Modern android development uses a single-activity architecture with fragments, navigation components, and versatile layout managers like SlidingPaneLayout.

But if your app consists of multiple activities, activity embedding enables you to easily provide an enhanced user experience on tablets, foldables, and ChromeOS devices.

Activity embedding is supported on Android 12L (API level 32) and higher.

Split task window

Activity embedding splits the app task window into two containers: primary and secondary. The containers hold activities launched from the main activity or from other activities already in the containers.

Activities are stacked in the secondary container as they’re launched, and the secondary container is stacked on top of the primary container on small screens, so activity stacking and back navigation are consistent with the ordering of activities already built into your app.

Activity embedding enables you to display activities in a variety of ways. Your app can split the task window by launching two activities side by side simultaneously:

Figure 2. Two activities side by side.

Or, an activity that’s occupying the entire task window can create a split by launching a new activity alongside:

Figure 3. Activity A starts activity B to the side.

Activities that are already in a split and sharing a task window can launch other activities in the following ways:

  • To the side on top of another activity:

    Figure 4. Activity A starts activity C to the side over activity B.
  • To the side, and shift the split sideways, concealing the previous primary activity:

    Figure 5. Activity B starts activity C to the side and shifts the split sideways.
  • Launch an activity in place on top; that is, in the same activity stack:

    Figure 6. Activity B starts activity C with no extra intent flags.
  • Launch an activity full window in the same task:

    Figure 7. Activity A or activity B starts activity C which fills the task window.

Back navigation

Different types of applications can have different back navigation rules in a split task window state depending on the dependencies between activities or how users trigger the back event, for example:

  • Going together: If activities are related, and one should not be shown without the other, back navigation can be configured to finish both.
  • Going it alone: If activities are fully independent, back navigation on an activity does not affect the state of another activity in the task window.

The back event is sent to the last focused activity when using button navigation. With gesture based navigation, the back event is sent to the activity where the gesture occurred.

Multi-pane layout

Jetpack WindowManager 1.1.0 Alpha04 enables you to build a multi-pane layout with activities on large screen devices with 12L (API level 32) and some devices with earlier platform versions. Existing apps that are based on multiple activities rather than fragments or view-based layouts such as SlidingPaneLayout can provide an improved large screen user experience without significant refactoring.

One common example is a list-detail split. To ensure a quality presentation, the system starts the list activity, and then the application immediately starts the detail activity. The transition system waits until both activities are drawn, then displays them together. To the user, the two activities launch as one.

Figure 8. Two activities started simultaneously in a multi-pane layout.

Split ratio

Your application can specify how the task window is proportioned by the ratio attribute of a split configuration (see Split configuration below).

Figure 9. Two activity splits with different split ratios.

Placeholders

Placeholder activities are empty secondary activities that occupy an area of an activity split. They are ultimately meant to be replaced with another activity that contains content. For example, a placeholder activity could occupy the secondary side of an activity split in a list-detail layout until an item from the list is selected, at which point an activity containing the detail information for the selected list item replaces the placeholder.

By default, the system displays placeholders only when there is enough space for an activity split. Placeholders automatically finish when the display size changes to a width or height too small to display a split. When space permits, the system relaunches the placeholder with a reinitialized state.

Figure 10. Foldable device folding and unfolding. Placeholder activity is finished and recreated as display size changes.

However, the stickyPlaceholder attribute of a SplitPlaceholderRule can override the default behavior. When the attribute is set to true, the system displays the placeholder as the topmost activity in the task window when the display is resized down to a single-pane display from a two-pane display (see Split configuration for an example).

Figure 11. Foldable device folding and unfolding. Placeholder activity is sticky.

Window size changes

When device configuration changes reduce the task window width so that it is not large enough for a multi-pane layout (for example, when a large screen foldable device folds from tablet size to phone size or the app window is resized in multi-window mode), the non-placeholder activities in the secondary pane of the task window are stacked on top of the activities in the primary pane.

Placeholder activities are shown only when there is enough display width for a split. On smaller screens, the placeholder is automatically dismissed. When the display area becomes large enough again, the placeholder is recreated. (See Placeholders above.)

Activity stacking is possible because WindowManager z-orders the activities in the secondary pane above activities in the primary pane.

Multiple activities in secondary pane

Activity B starts activity C in place with no extra intent flags:

Activity split containing activities A, B, and C with C stacked on
          top of B.

resulting in the following z-order of activities in the same task:

Secondary activity stack containing activity C stacked on top of B.
          Secondary stack is stacked on top of prmary activity stack
          containing activity A.

So, in a smaller task window, the application shrinks to a single activity with C at the top of the stack:

Small window showing only activity C.

Navigating back in the smaller window navigates through the activities stacked on top of each other.

If the task window configuration is restored to a larger size that can accommodate multiple panes, the activities are displayed side by side again.

Stacked splits

Activity B starts activity C to the side and shifts the split sideways:

Task window showing activities A and B, then activities B and C.

The result is the following z-order of activities in the same task:

Activities A, B, and C in a single stack. The activities are stacked
          in the following order from top to bottom: C, B, A.

In a smaller task window, the application shrinks to a single activity with C on top:

Small window showing only activity C.

Fixed-portrait orientation

The android:screenOrientation manifest setting enables apps to constrain activities to portrait or landscape orientation. To improve the user experience on large screen devices such as tablets and foldables, device manufacturers (OEMs) can ignore screen orientation requests and letterbox the app in portrait orientation on landscape displays or landscape orientation on portrait displays.

Figure 12. Letterboxed activities: fixed-portrait on landscape device (left), fixed-landscape on portrait device (right).

Similarly, when activity embedding is enabled, OEMs can customize devices to letterbox fixed-portrait activities in landscape orientation on large screens (width ≥ 600dp). When a fixed-portrait activity launches a second activity, the device can display the two activities side by side in a two-pane display.

Figure 13. Fixed-portrait activity A starts activity B to the side.

Always add the android.window.PROPERTY_ACTIVITY_EMBEDDING_SPLITS_ENABLED property to your app manifest file to inform devices that your app supports activity embedding (see Split configuration below). OEM-customized devices can then determine whether to letterbox fixed-portrait activities.

Split configuration

Containers and splits are created by the WindowManager library based on split rules. To configure split rules, complete the following steps:

  1. Add the latest WindowManager library dependency to your build.gradle file, for example:

    implementation 'androidx.window:window:1.1.0-alpha04'

  2. Inform the system that your app has implemented activity embedding

    Add the android.window.PROPERTY_ACTIVITY_EMBEDDING_SPLITS_ENABLED property to the <application> element of the app manifest file, and set the value to true, for example:

    <manifest xmlns:android="http://schemas.android.com/apk/res/android">
        <application>
            <property
                android:name="android.window.PROPERTY_ACTIVITY_EMBEDDING_SPLITS_ENABLED"
                android:value="true" />
        </application>
    </manifest>
    
  3. Create a resources file that does the following:

    • Defines activities that share a split
    • Configures the split options
    • Creates a placeholder for the secondary container of a split when content is not available
    • Specifies activities that should never be part of a split

    For example:

    <!-- split_configuration.xml -->
    
    <resources
        xmlns:window="http://schemas.android.com/apk/res-auto">
    
        <!-- Define a split for the named activities. -->
        <SplitPairRule
            window:splitRatio="0.33"
            window:splitMinWidth="840dp"
            window:finishPrimaryWithSecondary="never"
            window:finishSecondaryWithPrimary="always">
            <SplitPairFilter
                window:primaryActivityName=".ListActivity"
                window:secondaryActivityName=".DetailActivity"/>
        </SplitPairRule>
    
        <!-- Specify a placeholder for the secondary container when content is
             not available. -->
        <SplitPlaceholderRule
            window:placeholderActivityName=".PlaceholderActivity"
            window:splitRatio="0.33"
            window:splitMinWidth="840dp"
            window:stickyPlaceholder="false">
            <ActivityFilter
                window:activityName=".ListActivity"/>
        </SplitPlaceholderRule>
    
        <!-- Define activities that should never be part of a split. Note: Takes
             precedence over other split rules. -->
        <ActivityRule
            window:alwaysExpand="true">
            <ActivityFilter window:activityName=".FullscreenActivity"/>
        </ActivityRule>
    
    </resources>
    
  4. Create an initializer

    The WindowManager SplitController component manages activity splits based on the rules in the XML configuration file. A Jetpack Startup library Initializer makes the split rules available to SplitController at app startup so that SplitController can apply the rules if necessary as activities start.

    To create an initializer, do the following:

    1. Add the latest Jetpack Startup library dependency to your build.gradle file, for example:

      implementation 'androidx.startup:startup-runtime:1.1.1'

    2. Create a class that implements the Initializer interface

      The initializer makes the split rules available to SplitController by providing the ID of the XML resource file that contains the definitions (split_configuration.xml) to the component's initialize() method.

      Kotlin

      class SplitInitializer : Initializer<SplitController> {
      
        override fun create(context: Context): SplitController {
            SplitController.initialize(context, R.xml.split_configuration)
            return SplitController.getInstance()
        }
      
        override fun dependencies(): List<Class<out Initializer<*>>> {
            return emptyList()
        }
      }
      

      Java

      class SplitInitializer extends Initializer<SplitController> {
      
        @Override
        SplitController create(Context context) {
            SplitController.initialize(context, R.xml.split_configuration);
            return SplitController.getInstance();
        }
      
        @Override
        List<Class<? extends Initializer<?>>> dependencies() {
            return Collections.emptyList();
        }
      }
      
  5. Create a content provider for the rule definitions

    Add androidx.startup.InitializationProvider to your app manifest file as a <provider>. Include a reference to the implementation of your SplitController initializer, SplitInitializer:

    <!-- AndroidManifest.xml -->
    
    <provider android:name="androidx.startup.InitializationProvider"
        android:authorities="${applicationId}.androidx-startup"
        android:exported="false"
        tools:node="merge">
        <!-- Make SplitInitializer discoverable by InitializationProvider. -->
        <meta-data android:name="${applicationId}.SplitInitializer"
            android:value="androidx.startup" />
    </provider>
    

    InitializationProvider discovers and initializes SplitInitializer before the app's onCreate() method is called. As a result, the split rules are in effect when the app's main app activity starts.

Cross-application embedding

On Android 13 (API level 33) and higher, apps can embed activities from other apps. Cross‑application, or cross‑UID, activity embedding enables visual integration of activities from multiple Android applications. The system displays an activity of the host app and an embedded activity from another app on screen side by side or top and bottom just as in single-app activity embedding.

For example, the Settings app could embed the wallpaper selector activity from the WallpaperPicker app:

Figure 14. Settings app (menu on left) with wallpaper selector as embedded activity (right).

Trust model

Host processes that embed activities from other apps are able to redefine the presentation of the embedded activities, including size, position, cropping, and transparency. Malicious hosts can use this capability to mislead users and create clickjacking or other UI-redressing attacks.

To prevent misuse of cross-app activity embedding, Android requires apps to opt in to allow embedding of their activities. Apps can designate hosts as trusted or untrusted.

Trusted hosts

To allow other applications to embed and fully control the presentation of activities from your app, specify the SHA-1 certificate of the host application in the android:knownActivityEmbeddingCerts attribute of the <activity> or <application> elements of your app's manifest file.

Set the value of android:knownActivityEmbeddingCerts either as a string:

<activity
    android:name=".MyEmbeddableActivity"
    android:knownActivityEmbeddingCerts="@string/known_host_certificate_digest>"
    ... />

or, to specify multiple certificates, an array of strings:

<activity
    android:name=".MyEmbeddableActivity"
    android:knownActivityEmbeddingCerts="@array/known_host_certificate_digests"
    ... />

which references a resource like the following:

<resources>
    <string-array name="known_host_certificate_digests">
      <item>cert1</item>
      <item>cert2</item>
      ...
    </string-array>
</resources>

App owners can get a SHA certificate digest by running the Gradle signingReport task. The certificate digest is the SHA-1 fingerprint without the separating colons. For more information, see Run a signing report and Authenticating Your Client.

Untrusted hosts

To allow any app to embed your app's activities and control their presentation, specify the android:allowUntrustedActivityEmbedding attribute in the <activity> or <application> elements in the app manifest, for example:

<activity
    android:name=".MyEmbeddableActivity"
    android:allowUntrustedActivityEmbedding="true"
    ... />

The default value of the attribute is false, which prevents cross-app activity embedding.

Custom authentication

To mitigate the risks of untrusted activity embedding, create a custom authentication mechanism that verifies the host identity. If you know the host certificates, use the androidx.security.app.authenticator library to authenticate. If the host authenticates after embedding your activity, you can display the actual content. If not, you can inform the user that the action was not allowed and block the content.

Use the SplitController#isActivityEmbedded() method from the Jetpack WindowManager library to check whether a host is embedding your activity, for example:

Kotlin

fun isActivityEmbedded(activity: Activity): Boolean {
    return (SplitController.getInstance().isActivityEmbedded(activity))
}

Java

public static boolean isActivityEmbedded(@NonNull Activity activity) {
    return SplitController.getInstance().isActivityEmbedded(activity);
}

Minimum size restriction

The Android system applies the minimum height and width specified in the app manifest <layout> element to embedded activities. If an application does not specify minimum height and width, the system default values apply (sw220dp).

If the host attempts to resize the embedded container to a size smaller than the minimum, the embedded container expands to occupy the entire task bounds.

<activity-alias>

For trusted or untrusted activity embedding to work with the <activity-alias> element, android:knownActivityEmbeddingCerts or android:allowUntrustedActivityEmbedding must be applied to the target activity rather than the alias. The policy that verifies security on the system server is based on the flags set on the target, not the alias.

Host application

Host applications implement cross-app activity embedding the same way they implement single-app activity embedding. SplitPairRule and SplitPairFilter or ActivityRule and ActivityFilter objects specify embedded activities and task window splits. Split rules are defined statically in XML or at runtime using Jetpack WindowManager API calls.

If a host application attempts to embed an activity that has not opted in to cross-app embedding, the activity occupies the entire task bounds. As a result, host applications need to know whether target activities allow cross-app embedding.

If an embedded activity starts a new activity in the same task and the new activity has not opted in to cross-app embedding, the activity occupies the entire task bounds instead of overlaying the activity in the embedded container.

A host application can embed its own activities without restriction as long as the activities launch in the same task.

Split examples

Split from full window

Figure 15. Activity A starts activity B to the side.

No refactoring required. You can define the configuration for the split statically or at runtime and then call Context#startActivity() without any additional parameters.

<SplitPairRule>
    <SplitPairFilter
        window:primaryActivityName=".A"
        window:secondaryActivityName=".B"/>
</SplitPairRule>

Split by default

When the landing page of an application is designed to be split into two containers on large screens, the user experience is best when both activities are created and presented simultaneously. However, content might not be available for the secondary container of the split until the user interacts with the activity in the primary container (for example, the user selects an item from a navigation menu). A placeholder activity can fill the void until content can be displayed in the secondary container of the split (see Placeholders above).

Figure 16. Split created by opening two activities simultaneously. One activity is a placeholder.

To create a split with a placeholder, create a placeholder and associate it with the primary activity:

<SplitPlaceholderRule
    window:placeholderIntentName=".Placeholder">
    <ActivityFilter
        window:activityName=".Main"/>
</SplitPlaceholderRule>

When an app receives an intent, the target activity can be shown as the secondary part of an activity split; for example, a request to show a detail screen with information about an item from a list. On small displays, the detail is shown in the full task window; on larger devices, beside the list.

Figure 17. Deep link detail activity shown alone on a small screen, but together with a list activity on a large screen.

The launch request should be routed to the main activity, and the target detail activity should be launched in a split. SplitController automatically chooses the correct presentation—stacked or side by side—based on the available display width.

Kotlin

override fun onCreate(savedInstanceState Bundle?) {
    …
    splitController.registerRule(SplitPairRule(newFilters))
    startActivity(Intent(this, DetailActivity::class.java))
}

Java

@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    …
    splitController.registerRule(new SplitPairRule(newFilters));
    startActivity(new Intent(this, DetailActivity.class));
}

The deep link destination might be the only activity that should be available to the user in the back navigation stack, and you might want to avoid dismissing the detail activity and leaving only the main activity:

Large display with list activity and detail activity side by side.
          Back navigation unable to dismiss detail activity and leave list
          activity on screen.

Small display with detail activity only. Back navigation unable to
          dismiss detail activity and reveal list activity.

Instead, you can finish both activities at the same time by using the finishPrimaryWithSecondary attribute:

<SplitPairRule
    window:finishPrimaryWithSecondary="always">
    <SplitPairFilter
        window:primaryActivityName=".List"
        window:secondaryActivityName=".Detail"/>
</SplitPairRule>

See Configuration attributes below.

Multiple activities in split containers

Stacking multiple activities in a split container enables users to access deep content. For example, with a list-detail split, the user might need to go into a sub-detail section but keep the primary activity in place:

Figure 18. Activity opened in place in the secondary pane of the task window.

Kotlin

class DetailActivity {
    …
    fun onOpenSubDetail() {
      startActivity(Intent(this, SubDetailActivity::class.java))
    }
}

Java

public class DetailActivity {
    …
    void onOpenSubDetail() {
        startActivity(new Intent(this, SubDetailActivity.class));
    }
}

The sub-detail activity is placed on top of the detail activity, concealing it:

The user can then go back to the previous detail level by navigating back through the stack:

Figure 19. Activity removed from the top of the stack.

Stacking activities on top of each other is the default behavior when activities are launched from an activity in the same secondary container. Activities launched from the primary container within an active split also end up in the secondary container on the top of the activity stack.

Activities in a new task

When activities in a split task window start activities in a new task, the new task is separate from the task that includes the split and is displayed full window. The Recents screen shows two tasks: the task in the split and the new task.

Figure 20. Start activity C in a new task from activity B.

Activity replacement

Activities can be replaced in the secondary container stack; for example, when the primary activity is used for top-level navigation and the secondary activity is a selected destination. Each selection from the top-level navigation should start a new activity in the secondary container and remove the activity or activities that were previously there.

Figure 21. Top-level navigation activity in the primary pane replaces destination activities in the secondary pane.

If the app doesn't finish the activity in the secondary container when the navigation selection changes, back navigation might be confusing when the split is collapsed (when the device is folded). For example, if you have a menu in the primary pane and screens A and B stacked in the secondary pane, when the user folds the phone, B is on top of A, and A is on top of the menu. When the user navigates back from B, A appears instead of the menu.

Screen A must be removed from the back stack in such cases.

The default behavior when launching to the side in a new container over an existing split is to put the new secondary containers on top and retain the old ones in the back stack. You can configure the splits to clear the previous secondary containers with clearTop and launch new activities normally.

<SplitPairRule
    window:clearTop="true">
    <SplitPairFilter
        window:primaryActivityName=".Menu"
        window:secondaryActivityName=".ScreenA"/>
    <SplitPairFilter
        window:primaryActivityName=".Menu"
        window:secondaryActivityName=".ScreenB"/>
</SplitPairRule>

Kotlin

class MenuActivity {
    …
    fun onMenuItemSelected(selectedMenuItem: Int) {
        startActivity(Intent(this, classForItem(selectedMenuItem)))
    }
}

Java

public class MenuActivity {
    …
    void onMenuItemSelected(int selectedMenuItem) {
        startActivity(new Intent(this, classForItem(selectedMenuItem)));
    }
}

Alternatively, use the same secondary activity, and from the primary (menu) activity send new intents that resolve to the same instance but trigger a state or UI update in the secondary container.

Multiple splits

Apps can provide multi-level deep navigation by launching additional activities to the side.

When an activity in a secondary container launches a new activity to the side, a new split is created over top of the existing split.

Figure 22. Activity B starts activity C to the side.

The back stack contains all activities that were previously opened, so users can navigate to the A/B split after finishing C.

Activities A, B, and C in a stack. The activities are stacked in
          the following order from top to bottom: C, B, A.

To create a new split, launch the new activity to the side from the existing secondary container. Declare the configurations for both the A/B and B/C splits and launch activity C normally from B:

<SplitPairRule>
    <SplitPairFilter
        window:primaryActivityName=".A"
        window:secondaryActivityName=".B"/>
    <SplitPairFilter
        window:primaryActivityName=".B"
        window:secondaryActivityName=".C"/>
</SplitPairRule>

Kotlin

class B {
    fun onOpenC() {
        startActivity(Intent(this, C::class.java))
    }
}

Java

public class B {
    …
    void onOpenC() {
        startActivity(new Intent(this, C.class));
    }
}

React to split state changes

Different activities in an app can have UI elements that perform the same function; for example, a control that opens a window containing account settings.

Figure 23. Different activities with functionally identical UI elements.

If two activities that have a UI element in common are in a split, it’s redundant and perhaps confusing to show the element in both activities.

Figure 24. Duplicate UI elements in activity split.

To know when activities are in a split, register a listener with SplitController for changes in the split state. Then, adjust the UI accordingly:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    splitController
        .addSplitListener(this, mainThreadExecutor, SplitInfoChangeCallback())
}

inner class SplitInfoChangeCallback : Consumer<List<SplitInfo>> {
    override fun accept(splitInfoList: List<SplitInfo>) {
        findViewById<View>(R.id.infoButton).visibility =
            if (!splitInfoList.isEmpty()) View.GONE else View.VISIBLE
    }
}

Java

@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    splitController
        .addSplitListener(this, mainThreadExecutor, SplitInfoChangeCallback());
}

class SplitInfoChangeCallback extends Consumer<List<SplitInfo>> {
    public void accept(List<SplitInfo> splitInfoList) {
        findViewById<View>(R.id.infoButton).visibility =
            !splitInfoList.isEmpty()) ? View.GONE : View.VISIBLE;
    }
}

Callbacks can be made in any lifecycle state, including when an activity is stopped. Listeners should usually be registered in onStart() and unregistered in onStop().

Full-window modal

Some activities block users from interacting with the application until a specified action is performed; for example, a login screen activity, policy acknowledgement screen, or error message. Modal activities should be prevented from appearing in a split.

An activity can be forced to always fill the task window by using the expand configuration:

<ActivityRule
    window:alwaysExpand="true">
    <ActivityFilter
        window:activityName=".FullWidthActivity"/>
</ActivityRule>

Finish activities

Users can finish activities on either side of the split by swiping from the edge of the display:

Figure 25. Swipe gesture finishing activity B.
Figure 26. Swipe gesture finishing activity A.

If the device is set up to use the back button instead of gesture navigation, the input is sent to the focused activity—the activity that was touched or launched last.

The result of finishing one of the activities in the split depends on the split configuration.

Configuration attributes

You can specify split pair rule attributes to configure how finishing all activities on one side of the split affects the activities on the other side of the split. The attributes are:

  • window:finishPrimaryWithSecondary — How finishing all activities in the secondary container affects the activities in the primary container
  • window:finishSecondaryWithPrimary — How finishing all activities in the primary container affects the activities in the secondary container

Possible values of the attributes include:

  • always — Always finish the activities in the associated container
  • never — Never finish the activities in the associated container
  • adjacent — Finish the activities in the associated container when the two containers are displayed adjacent to each other, but not when the two containers are stacked

For example:

<SplitPairRule
    <!-- Do not finish the primary activity when the secondary activity finishes. -->
    window:finishPrimaryWithSecondary="never"
    <!-- Finish the secondary activity whenever the primary activity finishes. -->
    window:finishSecondaryWithPrimary="always">
    <SplitPairFilter
        window:primaryActivityName=".A"
        window:secondaryActivityName=".B"/>
</SplitPairRule>

Default configuration

When one activity in the split finishes, the remaining activity occupies the entire window:

<SplitPairRule>
    <SplitPairFilter
        window:primaryActivityName=".A"
        window:secondaryActivityName=".B"/>
</SplitPairRule>

Split containing activities A and B. A is finished, leaving B to
          occupy the entire window.

Split containing activities A and B. B is finished, leaving A to
          occupy the entire window.

Finish activities together

Finish the primary activity automatically when the secondary activity is finished:

<SplitPairRule
    window:finishPrimaryWithSecondary="always">
    <SplitPairFilter
        window:primaryActivityName=".A"
        window:secondaryActivityName=".B"/>
</SplitPairRule>

Split containing activities A and B. B is finished, which also
          finishes A, leaving the task window empty.

Split containing activities A and B. A is finished, leaving B alone
          in the task window.

Finish the secondary activity automatically when the primary activity is finished:

<SplitPairRule
    window:finishSecondaryWithPrimary="always">
    <SplitPairFilter
        window:primaryActivityName=".A"
        window:secondaryActivityName=".B"/>
</SplitPairRule>

Split containing activities A and B. A is finished, which also
          finishes B, leaving the task window empty.

Split containing activities A and B. B is finished, leaving A alone
          in the task window.

Finish activities together when either the primary or secondary is finished:

<SplitPairRule
    window:finishPrimaryWithSecondary="always"
    window:finishSecondaryWithPrimary="always">
    <SplitPairFilter
        window:primaryActivityName=".A"
        window:secondaryActivityName=".B"/>
</SplitPairRule>

Split containing activities A and B. A is finished, which also
          finishes B, leaving the task window empty.

Split containing activities A and B. B is finished, which also
          finishes A, leaving the task window empty.

Finish multiple activities in containers

If multiple activities are stacked in a split container, finishing an activity on the bottom of the stack does not automatically finish activities on top.

For example, if two activities are in the secondary container, C on top of B:

Secondary activity stack containing activity C stacked on top of B
          is stacked on top of the prmary activity stack containing activity
          A.

and the configuration of the split is defined by the configuration of activities A and B:

<SplitPairRule>
    <SplitPairFilter
        window:primaryActivityName=".A"
        window:secondaryActivityName=".B"/>
</SplitPairRule>

finishing the top activity retains the split.

Split with activity A in primary container and activities B and C in
          secondary, C stacked on top of B. C finishes, leaving A and B in the
          activity split.

Finishing the bottom (root) activity of the secondary container does not remove the activities on top of it; and so, also retains the split.

Split with activity A in primary container and activities B and C in
          secondary, C stacked on top of B. B finishes, leaving A and C in the
          activity split.

Any additional rules for finishing activities together, such as finishing the secondary activity with the primary, are also executed:

<SplitPairRule
    window:finishSecondaryWithPrimary="always">
    <SplitPairFilter
        window:primaryActivityName=".A"
        window:secondaryActivityName=".B"/>
</SplitPairRule>

Split with activity A in primary container and activities B and C in
          secondary container, C stacked on top of B. A finishes, also
          finishing B and C.

And when the split is configured to finish primary and secondary together:

<SplitPairRule
    window:finishPrimaryWithSecondary="always"
    window:finishSecondaryWithPrimary="always">
    <SplitPairFilter
        window:primaryActivityName=".A"
        window:secondaryActivityName=".B"/>
</SplitPairRule>

Split with activity A in primary container and activities B and C in
          secondary, C stacked on top of B. C finishes, leaving A and B in the
          activity split.

Split with activity A in primary container and activities B and C in
          secondary, C stacked on top of B. B finishes, leaving A and C in the
          activity split.

Split with activity A in primary container and activities B and C in
          secondary, C stacked on top of B. A finishes, also finishing B and
          C.

Change split properties at runtime

The properties of a currently active and visible split cannot be changed. Changing the split rules affects additional activity launches and new containers, but not existing and active splits.

To change the properties of active splits, finish the side activity or activities in the split and launch to the side again with a new configuration.

Extract an activity from a split to full window

Create a new configuration that displays the side activity full window, and then relaunch the activity with an intent that resolves to the same instance.

Check for split support at runtime

Activity embedding is an Android 12L (API level 32) feature but is also available on some devices with earlier platform versions. To check at runtime for the availability of the feature, use the SplitController.isSplitSupported() method:

Kotlin

val splitController = SplitController.Companion.getInstance()
if (splitController.isSplitSupported()) {
    // Device supports split activity features.
}

Java

SplitController splitController = SplitController.Companion.getInstance();
if (splitController.isSplitSupported()) {
  // Device supports split activity features.
}

If splits are not supported, activities are launched on top (following the non-activity embedding model).

Prevent system override

The manufacturers of Android devices (original equipment manufacturers, or OEMs), can implement activity embedding as a function of the device system. The system specifies split rules for multi-activity apps, overriding the windowing behavior of the apps. The system override forces multi-activity apps into a system-defined activity embedding mode.

System activity embedding can enhance app presentation through multi-pane layouts, such as list-detail, without any changes to the app. However, the system's activity embedding might also cause incorrect app layouts, bugs, or conflicts with activity embedding implemented by the app.

Your app can prevent or permit system activity embedding by setting a property in the app manifest file, for example:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application>
        <property
            android:name="android.window.PROPERTY_ACTIVITY_EMBEDDING_ALLOW_SYSTEM_OVERRIDE"
            android:value="true|false" />
    </application>
</manifest>

The property name is defined in the Jetpack WindowManager WindowProperties object. Set the value to false if your app implements activity embedding, or if you want to otherwise prevent the system from applying its activity embedding rules to your app. Set the value to true to permit the system to apply system-defined activity embedding to your app.

Limitations, restrictions, and caveats

  • Only the host app of the task, which is identified as the owner of the root activity in the task, can organize and embed other activities in the task. If activities that support embedding and splits run in a task that belongs to a different application, then embedding and splits will not work for those activities.
  • Activities can only be organized within a single task. Launching an activity in a new task always puts it in a new expanded window outside of any existing splits.
  • Only activities in the same process can be organized and put in a split. The SplitInfo callback only reports activities that belong to the same process, since there is no way of knowing about activities in different processes.
  • Each pair or singular activity rule applies only to activity launches that happen after the rule has been registered. There is currently no way to update existing splits or their visual properties.
  • The split pair filter configuration must match the intents used when launching activities completely. The matching occurs at the point when a new activity is started from the application process, so it might not know about component names that are resolved later in the system process when using implicit intents. If a component name is not known at the time of launch, a wildcard can be used instead (“*/*”) and filtering can be performed based on intent action.
  • There is currently no way to move activities between containers or in and out of splits after they were created. Splits are only created by the WindowManager library when new activities with matching rules are launched, and splits are destroyed when the last activity in a split container is finished.
  • Activities can be relaunched when the configuration changes, so when a split is created or removed and activity bounds change, the activity can go through complete destruction of the previous instance and creation of the new one. As a result, app developers should be careful with things like launching new activities from lifecycle callbacks.

Additional resources