An Overview of Android Dynamic Feature Modules

Revision as of 19:46, 6 May 2019 by Neil (Talk | contribs)

Revision as of 19:46, 6 May 2019 by Neil (Talk | contribs)

As outlined in the preceding chapter, the introduction of app bundles and dynamic delivery considerably reduced the size of the application package files that need to be downloaded when a user installs an app on an Android device. Although initially intended as a way to automatically generate separate package files for each possible device configuration, another key advantage of dynamic delivery is the ability to split an app into multiple dynamic feature modules that can be installed on-demand.

In this chapter, we will begin to explore the basic concepts of dynamic feature modules in preparation for working through a detailed practical example in the next chapter.

An Overview of Dynamic Feature Modules

The primary goals of dynamic delivery are to reduce the amount of time and bandwidth it takes to install an app from the app store, while also ensuring that only the minimum storage space is occupied by the app once it is installed.

Dynamic feature modules (also referred to as on-demand modules) allow the different features that comprise an Android app to be packaged into separate modules that are only downloaded and installed onto the device when they are required by the user. An app might, for example, include news and discussion features. In this scenario the app might only install the news feature by default and separate the discussion feature into a dynamic feature module. When a user attempts to access the discussion feature, the app will download the feature module from the Google Play store and launch it. If the user never accesses the feature, the module will never be installed, thereby ensuring that only the absolute minimum amount of storage is used by the app.

An app that utilizes dynamic feature modules has full control over how and when modules are installed. In fact, the app could also monitor the frequency with which particular features are accessed by a user and temporarily remove any that are infrequently used.

A dynamic feature may also be designated as being an “instant” module. This replaces the Instant App concept of earlier Android releases and allows a dynamic feature module to be run on a device without having to install the app. This allows the app to appear with a “Try Now” button within the Google Play App Store, or to be instantly launched on a device by clicking on a web URL.

Dynamic Feature Module Architecture

From the outset Android was designed with modularity in mind, particularly in terms of the concepts of Intents and Activities. Dynamic features bring this philosophy to a logical conclusion by allowing an app to install only what the user needs, when the user needs it. Given the flexibility and power of this capability, the implementation of dynamic feature modules is relatively simple.

In basic terms, dynamic feature modules are built using split APK files which allow multiple APK files to be brought together to form a single app.

As we learned in “Creating, Testing and Uploading an Android App Bundle”, dynamic delivery and app bundles work by generating a custom APK file that contains only the bytecode and resources necessary to run the app on a specific device configuration. In this case, the app is still installed via a single APK file, albeit one customized for the user’s device.

In contrast, dynamic feature modules work by splitting an app into multiple APK files referred to as " split APK files.

When an app uses split APK files, only the base module is installed when the app is first downloaded. The base module acts as the entry point into the app via a launchable activity, and contains the bytecode and resources for the base functionality of the app together with configuration and build resources that are required by the rest of the app. The base module manifest file, for example, contains a merger of the manifest files for any dynamic feature modules bundled with the app. Also, the version number for all of the dynamic feature modules are dictated by the version code setting in the build configuration file of the base module.

The base module also includes a list of the dynamic feature modules included in the app bundle and all dynamic feature modules must list the base module as a dependency in their build configurations.

Each dynamic feature takes the from of a module containing the bytecode, manifest, resources and build configuration together with any other assets such as images or data files for that specific feature.

When a user requests the installation of an app from the app store, the store will generate the Dynamic Feature APK file in addition to the corresponding Configuration APK files as illustrated in Figure 1-1 below:


Andorid dynamic feature diagram.png


Figure 1-1


Creating a Dynamic Feature Module

A dynamic feature can be added to a project either by adding an entirely new module, or by migrating an existing module. To add a new module, simply select the Android Studio File -> New -> New Module... menu option. From the resulting dialog, select either the Dynamic Feature Module or Instant Dynamic Feature Module template, depending on the type of dynamic feature you are creating:


As 3.4 add new dynamic feature.png


Figure 1-2

With the appropriate dynamic feature option selected, click on the Next button and, in the configuration screen, name the module and change the minimum API setting so that it matches the API level chosen for the base module (the project will fail to build if these versions do not match).

Click the Next button once more to configure the On-Demand options:


As 3.4 dynamic feature on demand options.png


Figure 1-3

The Enable on-demand option ensures that the app can download the dynamic feature from the Play Store when it is needed. If this is not enabled, the module will be downloaded when the app is first installed. When the Fusing option is enabled, the module will be downloaded with the base APK on devices running older versions of Android (Android 4.4 API 20 or older) that predate the introduction of dynamic delivery.

The Module Title string can be up to 50 characters in length and will be used by Google Play when describing the feature to users in messages and notifications.

Converting an Existing Module for Dynamic Delivery

If an app contains an existing feature that is a good candidate for dynamic delivery it can be converted to a dynamic feature with a few basic steps. Consider, for example, the following project structure:


Andorid dynamic feature convert tree.png


Figure 1-4

In this project, the app module will serve as the base module while the secondfeature module is an ideal candidate for conversion to a dynamic feature module.

To convert an existing module within your app to a dynamic feature module, begin by editing the module level build.gradle file (Gradle Scripts -> build.gradle (Module: secondfeature) in the above example) and modifying it to use the com.android.application plugin, and changing the dependencies so that the module only depends on the base (app) module. For example:

apply plugin: ‘com.android.dynamic-feature’
.
.
dependencies {
    implementation fileTree(dir: ‘libs’, include: [‘*.jar’])
    implementation project(‘:app’)
}

Next, edit the AndroidManifest.xml file for the module and modify it as follows (note in this example, that this is an on-demand module as opposed to an instant module):

<?xml version=”1.0” encoding=”utf-8”?>
<manifest xmlns:android=”http://schemas.android.com/apk/res/android”
    xmlns:dist=”http://schemas.android.com/apk/distribution”
    package=”com.ebookfrenzy.mymodule”>
    <dist:module
        dist:instant=”false”
        dist:onDemand=”true”
        dist:title=”@string/title_my_dynamic_feature”>
        <dist:fusing dist:include=”true” />
    </dist:module>
    <application
        android:allowBackup=”true"
.
.

Note the title property references a string resource which will also need to be declared in the strings.xml file. The use of a string resource as opposed to a hard coded string is mandatory for this property

Next, the build.gradle file for the base module (build.gradle (Module: app)) needs to be modified to reference the dynamic feature module and to add the Play Core Library as a dependency:

apply plugin: 'com.android.application'
android {
    compileSdkVersion 28
.
.
    }
    dynamicFeatures = [":secondfeature"]
}
dependencies {
.
.
    api 'com.google.android.play:core:1.5.0'
.
.
}

Finally, edit the AndroidManifest.xml file for the base module to declare the module as sub-classing SplitCompatApplication:

<?xml version=”1.0” encoding=”utf-8”?>
<manifest xmlns:android=”http://schemas.android.com/apk/res/android”
    package=”com.ebookfrenzy.mydemoapp”>
    <application
        android:name=
            “com.google.android.play.core.splitcompat.SplitCompatApplication”
        android:allowBackup=”true”
.
.

Working with Dynamic Feature Modules

Once an app project has one or more dynamic feature modules added, code will need to be written to install and manage those modules. This will involve performing tasks such as checking whether a module is already installed, installing the module, tracking installation progress and deleting an installed module that is no longer required. All of these tasks are performed using the API provided by the SplitInstallManager instance which can be created as follows:

private SplitInstallManager manager;
manager = SplitInstallManagerFactory.create(this);

Usually, the first step before allowing the user to launch a dynamic feature is to check that the corresponding module has already been installed. The following code, for example, obtains a list of installed modules and checks if a specific module is installed:

if (manager.getInstalledModules().contains("my_dynamic_feature")) {
    // Module is installed
}

One or more modules may be installed by building a SplitInstallRequest object and passing it through to the startInstall() method of the SplitInstallManager instance:

.
.
private int mySessionID = 0;
.
.
SplitInstallRequest request =
        SplitInstallRequest
                .newBuilder()
                .addModule(“my_dynamic_feature”)
                .addModule(“my_dynamic_feature2”)
                .build();
manager.startInstall(request)
        .addOnSuccessListener(new OnSuccessListener<Integer>() {
            @Override
            public void onSuccess(Integer sessionId) {
                mySessionID = sessionId
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(Exception exception) {
            }
        });

When the above code is executed, the module installation will begin immediately. Alternatively, deferred installations may be performed by passing an array of feature module names to the deferredInstall() method as follows:

manager.deferredInstall(Arrays.asList(“my_dynamic_feature”, 
                                          “my_dynamic_feature2”));

Deferred downloads are performed in the background at the discretion of the operating system.

While it is not possible to track the status of deferred installations, non-deferred installations can be tracked by adding a listener to the manager:

SplitInstallStateUpdatedListener listener = 
                   new SplitInstallStateUpdatedListener() {
    @Override
    public void onStateUpdate(SplitInstallSessionState state) {
        if (state.sessionId() == mySessionID) {
            switch (state.status()) {
                case SplitInstallSessionStatus.REQUIRES_USER_CONFIRMATION:
			// Large module requires user permission
                    break;
                case SplitInstallSessionStatus.DOWNLOADING: 
			// The module is being downloaded
                    break;
                case SplitInstallSessionStatus.INSTALLING:
			// The downloaded module is being installed
                    break;
                case SplitInstallSessionStatus.DOWNLOADED:
                    // The module download is complete
                    break;
                case SplitInstallSessionStatus.INSTALLED:
                    // The module has been installed successfully
                    break;
                case SplitInstallSessionStatus.CANCELED:
			// The user cancelled the download
                    break;
                case SplitInstallSessionStatus.PENDING:
			// The installation is deferred
                    break;
                case SplitInstallSessionStatus.FAILED:
                    // The installation failed
            }
        }
    }
};

Once the listener has been implemented, it will need to be registered with the SplitInstallManager instance and then unregistered when no longer required.

manager.registerListener(listener);
.
.
manager.unregisterListener(listener);

Handling Large Dynamic Feature Modules

The Android dynamic delivery system will not permit the download of a dynamic feature module greater than 10MB in size without first requesting permission from the user. When a request is made to download a large feature module, the listener will be called and passed a REQUIRES_USER_CONFIRMATION status. It is then the responsibility of the app to display the confirmation dialog and, optionally, implement an onActivityResult() handler method to identify whether the user approved or declined the download.

private static final int REQUEST_CODE = 101;
.
.
SplitInstallStateUpdatedListener listener = 
                        new SplitInstallStateUpdatedListener() {
    @Override
    public void onStateUpdate(SplitInstallSessionState state) {
        if (state.sessionId() == mySessionID) {
            switch (state.status()) {
                case SplitInstallSessionStatus.REQUIRES_USER_CONFIRMATION:
                    try {
                        manager.startConfirmationDialogForResult(state, 		
					MainActivity.this, REQUEST_CODE);
                    } catch (IntentSender.SendIntentException ex) {
                        // Request failed
                    }
                    break;
.
.

The above code launches an intent which, in turn, displays the built-in confirmation dialog. This intent will return a result code to the onActivityResult() method which may be implemented as follows:

@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_CODE) {
        if (resultCode == RESULT_OK) {
            // User approved installation
        } else {
            // User declined installation
        }
    }
}

If the user approves the request, the dynamic feature module will be downloaded and installed automatically.

Summary

Dynamic feature modules allow an Android app to be divided into separate features which are downloaded on-demand when the feature is needed by the user. Dynamic feature modules can also be configured to be instant features. Instant features can be run without installing the app on the device and can be accessed by users either via a Try Now button on the app store page, or via a web URL.

Dynamic feature implementation involves splitting an app into a base module and one or more dynamic feature modules. New dynamic feature modules can be created within Android Studio, and existing modules converted to dynamic feature modules by making a few project configuration changes.

Once dynamic feature modules have been added to an app, the download and management of those modules is handled by the app via the SplitInstall classes of the Play Core Library.