34,333
edits
Changes
Created page with "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 downl..."
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:
[[File: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:
[[File: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:
[[File: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:
[[File: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:
<pre>
apply plugin: ‘com.android.dynamic-feature’
.
.
dependencies {
implementation fileTree(dir: ‘libs’, include: [‘*.jar’])
implementation project(‘:app’)
}
</pre>
Next, edit the A''ndroidManifest.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):
<pre>
<?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"
.
.
</pre>
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:
<pre>
apply plugin: 'com.android.application'
android {
compileSdkVersion 28
.
.
}
dynamicFeatures = [":secondfeature"]
}
dependencies {
.
.
api 'com.google.android.play:core:1.5.0'
.
.
}
</pre>
Finally, edit the ''AndroidManifest.xml'' file for the base module to declare the module as sub-classing SplitCompatApplication:
<pre>
<?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”
.
.
</pre>
=== 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:
<pre>
private SplitInstallManager manager;
manager = SplitInstallManagerFactory.create(this);
</pre>
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:
<pre>
if (manager.getInstalledModules().contains("my_dynamic_feature")) {
// Module is installed
}
</pre>
One or more modules may be installed by building a SplitInstallRequest object and passing it through to the ''startInstall()'' method of the SplitInstallManager instance:
<pre>
.
.
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) {
}
});
</pre>
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:
<pre>
manager.deferredInstall(Arrays.asList(“my_dynamic_feature”,
“my_dynamic_feature2”));
</pre>
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:
<pre>
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
}
}
}
};
</pre>
.</span>
<pre>
manager.registerListener(listener);
.
.
manager.unregisterListener(listener);
</pre>
=== 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.
<pre>
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;
.
.
</pre>
The above code launches an intent which, in turn, displays the built-in confirmation dialog. This intent will return a result code to the on''ActivityResult() ''method which may be implemented as follows:
<pre>
@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
}
}
}
</pre>
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.
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:
[[File: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:
[[File: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:
[[File: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:
[[File: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:
<pre>
apply plugin: ‘com.android.dynamic-feature’
.
.
dependencies {
implementation fileTree(dir: ‘libs’, include: [‘*.jar’])
implementation project(‘:app’)
}
</pre>
Next, edit the A''ndroidManifest.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):
<pre>
<?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"
.
.
</pre>
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:
<pre>
apply plugin: 'com.android.application'
android {
compileSdkVersion 28
.
.
}
dynamicFeatures = [":secondfeature"]
}
dependencies {
.
.
api 'com.google.android.play:core:1.5.0'
.
.
}
</pre>
Finally, edit the ''AndroidManifest.xml'' file for the base module to declare the module as sub-classing SplitCompatApplication:
<pre>
<?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”
.
.
</pre>
=== 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:
<pre>
private SplitInstallManager manager;
manager = SplitInstallManagerFactory.create(this);
</pre>
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:
<pre>
if (manager.getInstalledModules().contains("my_dynamic_feature")) {
// Module is installed
}
</pre>
One or more modules may be installed by building a SplitInstallRequest object and passing it through to the ''startInstall()'' method of the SplitInstallManager instance:
<pre>
.
.
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) {
}
});
</pre>
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:
<pre>
manager.deferredInstall(Arrays.asList(“my_dynamic_feature”,
“my_dynamic_feature2”));
</pre>
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:
<pre>
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
}
}
}
};
</pre>
.</span>
<pre>
manager.registerListener(listener);
.
.
manager.unregisterListener(listener);
</pre>
=== 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.
<pre>
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;
.
.
</pre>
The above code launches an intent which, in turn, displays the built-in confirmation dialog. This intent will return a result code to the on''ActivityResult() ''method which may be implemented as follows:
<pre>
@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
}
}
}
</pre>
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.
