Google Play currently requires that your APK file be no more than 50MB. For most applications, this is plenty of space for all the application's code and assets. However, some apps need more space for high-fidelity graphics, media files, or other large assets. Previously, if your app exceeded 50MB, you had to host and download the additional resources yourself when the user opens the app. Hosting and serving the extra files can be costly, and the user experience is often less than ideal. To make this process easier for you and more pleasant for users, Google Play allows you to attach two large expansion files that supplement your APK.
Google Play hosts the expansion files for your application and serves them to the device at no cost to you. The expansion files are saved to the device's shared storage location (the SD card or USB-mountable partition; also known as the "external" storage) where your app can access them. On most devices, Google Play downloads the expansion file(s) at the same time it downloads the APK, so your application has everything it needs when the user opens it for the first time. In some cases, however, your application must download the files from Google Play when your application starts.
Each time you upload an APK using the Google Play Developer Console, you have the option to add one or two expansion files to the APK. Each file can be up to 2GB and it can be any format you choose, but we recommend you use a compressed file to conserve bandwidth during the download. Conceptually, each expansion file plays a different role:
While you can use the two expansion files any way you wish, we recommend that the main expansion file deliver the primary assets and should rarely if ever updated; the patch expansion file should be smaller and serve as a “patch carrier,” getting updated with each major release or as necessary.
However, even if your application update requires only a new patch expansion file, you still must upload a new APK with an updated {@code versionCode} in the manifest. (The Developer Console does not allow you to upload an expansion file to an existing APK.)
Note: The patch expansion file is semantically the same as the main expansion file—you can use each file any way you want. The system does not use the patch expansion file to perform patching for your app. You must perform patching yourself or be able to distinguish between the two files.
Each expansion file you upload can be any format you choose (ZIP, PDF, MP4, etc.). You can also use the JOBB tool to encapsulate and encrypt a set of resource files and subsequent patches for that set. Regardless of the file type, Google Play considers them opaque binary blobs and renames the files using the following scheme:
[main|patch].<expansion-version>.<package-name>.obb
There are three components to this scheme:
"First" is emphasized because although the Developer Console allows you to re-use an uploaded expansion file with a new APK, the expansion file's name does not change—it retains the version applied to it when you first uploaded the file.
For example, suppose your APK version is 314159 and your package name is com.example.app. If you upload a main expansion file, the file is renamed to:
main.314159.com.example.app.obb
When Google Play downloads your expansion files to a device, it saves them to the system's shared storage location. To ensure proper behavior, you must not delete, move, or rename the expansion files. In the event that your application must perform the download from Google Play itself, you must save the files to the exact same location.
The specific location for your expansion files is:
<shared-storage>/Android/obb/<package-name>/
For each application, there are never more than two expansion files in this directory. One is the main expansion file and the other is the patch expansion file (if necessary). Previous versions are overwritten when you update your application with new expansion files.
If you must unpack the contents of your expansion files, do not delete the {@code .obb} expansion files afterwards and do not save the unpacked data in the same directory. You should save your unpacked files in the directory specified by {@link android.content.Context#getExternalFilesDir getExternalFilesDir()}. However, if possible, it's best if you use an expansion file format that allows you to read directly from the file instead of requiring you to unpack the data. For example, we've provided a library project called the APK Expansion Zip Library that reads your data directly from the ZIP file.
Note: Unlike APK files, any files saved on the shared storage can be read by the user and other applications.
Tip: If you're packaging media files into a ZIP, you can use media
playback calls on the files with offset and length controls (such as {@link
android.media.MediaPlayer#setDataSource(FileDescriptor,long,long) MediaPlayer.setDataSource()} and
{@link android.media.SoundPool#load(FileDescriptor,long,long,int) SoundPool.load()}) without the
need to unpack your ZIP. In order for this to work, you must not perform additional compression on
the media files when creating the ZIP packages. For example, when using the zip tool,
you should use the -n option to specify the file suffixes that should not be
compressed:
zip -n .mp4;.ogg main_expansion media_files
Most of the time, Google Play downloads and saves your expansion files at the same time it downloads the APK to the device. However, in some cases Google Play cannot download the expansion files or the user might have deleted previously downloaded expansion files. To handle these situations, your app must be able to download the files itself when the main activity starts, using a URL provided by Google Play.
The download process from a high level looks like this:
If Google Play is unable to download the expansion files, it downloads the APK only.
Caution: It is critical that you include the necessary code to download the expansion files from Google Play in the event that the files are not already on the device when your application starts. As discussed in the following section about Downloading the Expansion Files, we've made a library available to you that greatly simplifies this process and performs the download from a service with a minimal amount of code from you.
Here's a summary of the tasks you should perform to use expansion files with your application:
Normally, you should only use the second patch expansion file when performing updates to the main expansion file. However, if your resources exceed the 2GB limit for the main expansion file, you can use the patch file for the rest of your assets.
Remember that you must not delete, move, or rename the expansion files.
If your application doesn't demand a specific format, we suggest you create ZIP files for your expansion files, then read them using the APK Expansion Zip Library.
To greatly reduce the amount of code you must write and ensure a good user experience during the download, we recommend you use the Downloader Library to implement your download behavior.
If you build your own download service instead of using the library, be aware that you must not change the name of the expansion files and must save them to the proper storage location.
Once you've finished your application development, follow the guide to Testing Your Expansion Files.
Adding APK expansion files is a feature available when you upload your application using the Developer Console. When uploading your application for the first time or updating an application that uses expansion files, you must be aware of the following rules and limitations:
obb/
directory. If you must unpack some data, save it into the location specified by {@link
android.content.Context#getExternalFilesDir getExternalFilesDir()}.In most cases, Google Play downloads and saves your expansion files to the device at the same time it installs or updates the APK. This way, the expansion files are available when your application launches for the first time. However, in some cases your app must download the expansion files itself by requesting them from a URL provided to you in a response from Google Play's Application Licensing service.
The basic logic you need to download your expansion files is the following:
Android/obb/<package-name>/ directory).
Android/obb/<package-name>/) and use the exact file name provided
by Google Play's response.
Note: The URL that Google Play provides for your expansion files is unique for every download and each one expires shortly after it is given to your application.
If your application is free (not a paid app), then you probably haven't used the Application Licensing service. It's primarily designed for you to enforce licensing policies for your application and ensure that the user has the right to use your app (he or she rightfully paid for it on Google Play). In order to facilitate the expansion file functionality, the licensing service has been enhanced to provide a response to your application that includes the URL of your application's expansion files that are hosted on Google Play. So, even if your application is free for users, you need to include the License Verification Library (LVL) to use APK expansion files. Of course, if your application is free, you don't need to enforce license verification—you simply need the library to perform the request that returns the URL of your expansion files.
Note: Whether your application is free or not, Google Play returns the expansion file URLs only if the user acquired your application from Google Play.
In addition to the LVL, you need a set of code that downloads the expansion files over an HTTP connection and saves them to the proper location on the device's shared storage. As you build this procedure into your application, there are several issues you should take into consideration:
To simplify this work for you, we've built the Downloader Library, which requests the expansion file URLs through the licensing service, downloads the expansion files, performs all of the tasks listed above, and even allows your activity to pause and resume the download. By adding the Downloader Library and a few code hooks to your application, almost all the work to download the expansion files is already coded for you. As such, in order to provide the best user experience with minimal effort on your behalf, we recommend you use the Downloader Library to download your expansion files. The information in the following sections explain how to integrate the library into your application.
If you'd rather develop your own solution to download the expansion files using the Google Play URLs, you must follow the Application Licensing documentation to perform a license request, then retrieve the expansion file names, sizes, and URLs from the response extras. You should use the {@code APKExpansionPolicy} class (included in the License Verification Library) as your licensing policy, which captures the expansion file names, sizes, and URLs from the licensing service..
To use APK expansion files with your application and provide the best user experience with minimal effort on your behalf, we recommend you use the Downloader Library that's included in the Google Play APK Expansion Library package. This library downloads your expansion files in a background service, shows a user notification with the download status, handles network connectivity loss, resumes the download when possible, and more.
To implement expansion file downloads using the Downloader Library, all you need to do is:
The following sections explain how to set up your app using the Downloader Library.
To use the Downloader Library, you need to download two packages from the SDK Manager and add the appropriate libraries to your application.
First, open the Android SDK Manager, expand Extras and download:
If you're using Eclipse, create a project for each library and add it to your app:
Note: The Downloader Library depends on the License Verification Library. Be sure to add the License Verification Library to the Downloader Library's project properties (same process as steps 2 and 3 below).
Or, from a command line, update your project to include the libraries:
<sdk>/tools/ directory.android update project with the {@code --library} option to add both the
LVL and the Downloader Library to your project. For example:
android update project --path ~/Android/MyApp \ --library ~/android_sdk/extras/google/market_licensing \ --library ~/android_sdk/extras/google/market_apk_expansion/downloader_library
With both the License Verification Library and Downloader Library added to your application, you'll be able to quickly integrate the ability to download expansion files from Google Play. The format that you choose for the expansion files and how you read them from the shared storage is a separate implementation that you should consider based on your application needs.
Tip: The Apk Expansion package includes a sample application that shows how to use the Downloader Library in an app. The sample uses a third library available in the Apk Expansion package called the APK Expansion Zip Library. If you plan on using ZIP files for your expansion files, we suggest you also add the APK Expansion Zip Library to your application. For more information, see the section below about Using the APK Expansion Zip Library.
In order to download the expansion files, the Downloader Library requires several permissions that you must declare in your application's manifest file. They are:
<manifest ...>
<!-- Required to access Google Play Licensing -->
<uses-permission android:name="com.android.vending.CHECK_LICENSE" />
<!-- Required to download files from Google Play -->
<uses-permission android:name="android.permission.INTERNET" />
<!-- Required to keep CPU alive while downloading files
(NOT to keep screen awake) -->
<uses-permission android:name="android.permission.WAKE_LOCK" />
<!-- Required to poll the state of the network connection
and respond to changes -->
<uses-permission
android:name="android.permission.ACCESS_NETWORK_STATE" />
<!-- Required to check whether Wi-Fi is enabled -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<!-- Required to read and write the expansion files on shared storage -->
<uses-permission
android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
...
</manifest>
Note: By default, the Downloader Library requires API level 4, but the APK Expansion Zip Library requires API level 5.
In order to perform downloads in the background, the Downloader Library provides its own {@link android.app.Service} subclass called {@code DownloaderService} that you should extend. In addition to downloading the expansion files for you, the {@code DownloaderService} also:
All you need to do is create a class in your application that extends the {@code DownloaderService} class and override three methods to provide specific application details:
For example, here's a complete implementation of {@code DownloaderService}:
public class SampleDownloaderService extends DownloaderService {
// You must use the public key belonging to your publisher account
public static final String BASE64_PUBLIC_KEY = "YourLVLKey";
// You should also modify this salt
public static final byte[] SALT = new byte[] { 1, 42, -12, -1, 54, 98,
-100, -12, 43, 2, -8, -4, 9, 5, -106, -107, -33, 45, -1, 84
};
@Override
public String getPublicKey() {
return BASE64_PUBLIC_KEY;
}
@Override
public byte[] getSALT() {
return SALT;
}
@Override
public String getAlarmReceiverClassName() {
return SampleAlarmReceiver.class.getName();
}
}
Notice: You must update the {@code BASE64_PUBLIC_KEY} value to be the public key belonging to your publisher account. You can find the key in the Developer Console under your profile information. This is necessary even when testing your downloads.
Remember to declare the service in your manifest file:
<application ...>
<service android:name=".SampleDownloaderService" />
...
</application>
In order to monitor the progress of the file downloads and restart the download if necessary, the {@code DownloaderService} schedules an {@link android.app.AlarmManager#RTC_WAKEUP} alarm that delivers an {@link android.content.Intent} to a {@link android.content.BroadcastReceiver} in your application. You must define the {@link android.content.BroadcastReceiver} to call an API from the Downloader Library that checks the status of the download and restarts it if necessary.
You simply need to override the {@link android.content.BroadcastReceiver#onReceive onReceive()} method to call {@code DownloaderClientMarshaller.startDownloadServiceIfRequired()}.
For example:
public class SampleAlarmReceiver extends BroadcastReceiver {
@Override
public void onReceive(Context context, Intent intent) {
try {
DownloaderClientMarshaller.startDownloadServiceIfRequired(context,
intent, SampleDownloaderService.class);
} catch (NameNotFoundException e) {
e.printStackTrace();
}
}
}
Notice that this is the class for which you must return the name in your service's {@code getAlarmReceiverClassName()} method (see the previous section).
Remember to declare the receiver in your manifest file:
<application ...>
<receiver android:name=".SampleAlarmReceiver" />
...
</application>
The main activity in your application (the one started by your launcher icon) is responsible for verifying whether the expansion files are already on the device and initiating the download if they are not.
Starting the download using the Downloader Library requires the following procedures:
The Downloader Library includes some APIs in the {@code Helper} class to help with this process:
For example, the sample app provided in the Apk Expansion package calls the following method in the activity's {@link android.app.Activity#onCreate onCreate()} method to check whether the expansion files already exist on the device:
boolean expansionFilesDelivered() {
for (XAPKFile xf : xAPKS) {
String fileName = Helpers.getExpansionAPKFileName(this, xf.mIsBase,
xf.mFileVersion);
if (!Helpers.doesFileExist(this, fileName, xf.mFileSize, false))
return false;
}
return true;
}
In this case, each {@code XAPKFile} object holds the version number and file size of a known expansion file and a boolean as to whether it's the main expansion file. (See the sample application's {@code SampleDownloaderActivity} class for details.)
If this method returns false, then the application must begin the download.
The method takes the following parameters:
context: Your application's {@link android.content.Context}.notificationClient: A {@link android.app.PendingIntent} to start your main
activity. This is used in the {@link android.app.Notification} that the {@code DownloaderService}
creates to show the download progress. When the user selects the notification, the system
invokes the {@link android.app.PendingIntent} you supply here and should open the activity
that shows the download progress (usually the same activity that started the download).serviceClass: The {@link java.lang.Class} object for your implementation of
{@code DownloaderService}, required to start the service and begin the download if necessary.The method returns an integer that indicates whether or not the download is required. Possible values are:
The behavior for {@code LVL_CHECK_REQUIRED} and {@code DOWNLOAD_REQUIRED} are essentially the same and you normally don't need to be concerned about them. In your main activity that calls {@code startDownloadServiceIfRequired()}, you can simply check whether or not the response is {@code NO_DOWNLOAD_REQUIRED}. If the response is anything other than {@code NO_DOWNLOAD_REQUIRED}, the Downloader Library begins the download and you should update your activity UI to display the download progress (see the next step). If the response is {@code NO_DOWNLOAD_REQUIRED}, then the files are available and your application can start.
For example:
@Override
public void onCreate(Bundle savedInstanceState) {
// Check if expansion files are available before going any further
if (!expansionFilesDelivered()) {
// Build an Intent to start this activity from the Notification
Intent notifierIntent = new Intent(this, MainActivity.getClass());
notifierIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK |
Intent.FLAG_ACTIVITY_CLEAR_TOP);
...
PendingIntent pendingIntent = PendingIntent.getActivity(this, 0,
notifierIntent, PendingIntent.FLAG_UPDATE_CURRENT);
// Start the download service (if required)
int startResult =
DownloaderClientMarshaller.startDownloadServiceIfRequired(this,
pendingIntent, SampleDownloaderService.class);
// If download has started, initialize this activity to show
// download progress
if (startResult != DownloaderClientMarshaller.NO_DOWNLOAD_REQUIRED) {
// This is where you do set up to display the download
// progress (next step)
...
return;
} // If the download wasn't necessary, fall through to start the app
}
startApp(); // Expansion files are available, start the app
}
In order to instantiate your {@code IStub} by calling {@code CreateStub()}, you must pass it an implementation of the {@code IDownloaderClient} interface and your {@code DownloaderService} implementation. The next section about Receiving download progress discusses the {@code IDownloaderClient} interface, which you should usually implement in your {@link android.app.Activity} class so you can update the activity UI when the download state changes.
We recommend that you call {@code CreateStub()} to instantiate your {@code IStub} during your activity's {@link android.app.Activity#onCreate onCreate()} method, after {@code startDownloadServiceIfRequired()} starts the download.
For example, in the previous code sample for {@link android.app.Activity#onCreate onCreate()}, you can respond to the {@code startDownloadServiceIfRequired()} result like this:
// Start the download service (if required)
int startResult =
DownloaderClientMarshaller.startDownloadServiceIfRequired(this,
pendingIntent, SampleDownloaderService.class);
// If download has started, initialize activity to show progress
if (startResult != DownloaderClientMarshaller.NO_DOWNLOAD_REQUIRED) {
// Instantiate a member instance of IStub
mDownloaderClientStub = DownloaderClientMarshaller.CreateStub(this,
SampleDownloaderService.class);
// Inflate layout that shows download progress
setContentView(R.layout.downloader_ui);
return;
}
After the {@link android.app.Activity#onCreate onCreate()} method returns, your activity receives a call to {@link android.app.Activity#onResume onResume()}, which is where you should then call {@code connect()} on the {@code IStub}, passing it your application's {@link android.content.Context}. Conversely, you should call {@code disconnect()} in your activity's {@link android.app.Activity#onStop onStop()} callback.
@Override
protected void onResume() {
if (null != mDownloaderClientStub) {
mDownloaderClientStub.connect(this);
}
super.onResume();
}
@Override
protected void onStop() {
if (null != mDownloaderClientStub) {
mDownloaderClientStub.disconnect(this);
}
super.onStop();
}
Calling {@code connect()} on the {@code IStub} binds your activity to the {@code DownloaderService} such that your activity receives callbacks regarding changes to the download state through the {@code IDownloaderClient} interface.
To receive updates regarding the download progress and to interact with the {@code DownloaderService}, you must implement the Downloader Library's {@code IDownloaderClient} interface. Usually, the activity you use to start the download should implement this interface in order to display the download progress and send requests to the service.
The required interface methods for {@code IDownloaderClient} are:
A recommended implementation looks like this:
private IDownloaderService mRemoteService;
...
@Override
public void onServiceConnected(Messenger m) {
mRemoteService = DownloaderServiceMarshaller.CreateProxy(m);
mRemoteService.onClientUpdated(mDownloaderClientStub.getMessenger());
}
With the {@code IDownloaderService} object initialized, you can send commands to the downloader service, such as to pause and resume the download ({@code requestPauseDownload()} and {@code requestContinueDownload()}).
The newState value will be one of several possible values specified in
by one of the {@code IDownloaderClient} class's {@code STATE_*} constants.
To provide a useful message to your users, you can request a corresponding string for each state by calling {@code Helpers.getDownloaderStringResourceIDFromState()}. This returns the resource ID for one of the strings bundled with the Downloader Library. For example, the string "Download paused because you are roaming" corresponds to {@code STATE_PAUSED_ROAMING}.
Tip: For examples of these callbacks that update the download progress UI, see the {@code SampleDownloaderActivity} in the sample app provided with the Apk Expansion package.
Some public methods for the {@code IDownloaderService} interface you might find useful are:
mRemoteService
.setDownloadFlags(IDownloaderService.FLAGS_DOWNLOAD_OVER_CELLULAR);
If you decide to build your own downloader service instead of using the Google Play Downloader Library, you should still use the {@code APKExpansionPolicy} that's provided in the License Verification Library. The {@code APKExpansionPolicy} class is nearly identical to {@code ServerManagedPolicy} (available in the Google Play License Verification Library) but includes additional handling for the APK expansion file response extras.
Note: If you do use the Downloader Library as discussed in the previous section, the library performs all interaction with the {@code APKExpansionPolicy} so you don't have to use this class directly.
The class includes methods to help you get the necessary information about the available expansion files:
For more information about how to use the {@code APKExpansionPolicy} when you're not using the Downloader Library, see the documentation for Adding Licensing to Your App, which explains how to implement a license policy such as this one.
Once your APK expansion files are saved on the device, how you read your files depends on the type of file you've used. As discussed in the overview, your expansion files can be any kind of file you want, but are renamed using a particular file name format and are saved to {@code <shared-storage>/Android/obb/<package-name>/}.
Regardless of how you read your files, you should always first check that the external storage is available for reading. There's a chance that the user has the storage mounted to a computer over USB or has actually removed the SD card.
Note: When your application starts, you should always check whether the external storage space is available and readable by calling {@link android.os.Environment#getExternalStorageState()}. This returns one of several possible strings that represent the state of the external storage. In order for it to be readable by your application, the return value must be {@link android.os.Environment#MEDIA_MOUNTED}.
As described in the overview, your APK expansion files are saved using a specific file name format:
[main|patch].<expansion-version>.<package-name>.obb
To get the location and names of your expansion files, you should use the {@link android.os.Environment#getExternalStorageDirectory()} and {@link android.content.Context#getPackageName()} methods to construct the path to your files.
Here's a method you can use in your application to get an array containing the complete path to both your expansion files:
// The shared path to all app expansion files
private final static String EXP_PATH = "/Android/obb/";
static String[] getAPKExpansionFiles(Context ctx, int mainVersion,
int patchVersion) {
String packageName = ctx.getPackageName();
Vector<String> ret = new Vector<String>();
if (Environment.getExternalStorageState()
.equals(Environment.MEDIA_MOUNTED)) {
// Build the full path to the app's expansion files
File root = Environment.getExternalStorageDirectory();
File expPath = new File(root.toString() + EXP_PATH + packageName);
// Check that expansion file path exists
if (expPath.exists()) {
if ( mainVersion > 0 ) {
String strMainPath = expPath + File.separator + "main." +
mainVersion + "." + packageName + ".obb";
File main = new File(strMainPath);
if ( main.isFile() ) {
ret.add(strMainPath);
}
}
if ( patchVersion > 0 ) {
String strPatchPath = expPath + File.separator + "patch." +
mainVersion + "." + packageName + ".obb";
File main = new File(strPatchPath);
if ( main.isFile() ) {
ret.add(strPatchPath);
}
}
}
}
String[] retArray = new String[ret.size()];
ret.toArray(retArray);
return retArray;
}
You can call this method by passing it your application {@link android.content.Context} and the desired expansion file's version.
There are many ways you could determine the expansion file version number. One simple way is to save the version in a {@link android.content.SharedPreferences} file when the download begins, by querying the expansion file name with the {@code APKExpansionPolicy} class's {@code getExpansionFileName(int index)} method. You can then get the version code by reading the {@link android.content.SharedPreferences} file when you want to access the expansion file.
For more information about reading from the shared storage, see the Data Storage documentation.
If you're using your expansion files to store media files, a ZIP file still allows you to
use Android media playback calls that provide offset and length controls (such as {@link
android.media.MediaPlayer#setDataSource(FileDescriptor,long,long) MediaPlayer.setDataSource()} and
{@link android.media.SoundPool#load(FileDescriptor,long,long,int) SoundPool.load()}). In order for
this to work, you must not perform additional compression on the media files when creating the ZIP
packages. For example, when using the zip tool, you should use the -n
option to specify the file suffixes that should not be compressed:
zip -n .mp4;.ogg main_expansion media_files
The Google Market Apk Expansion package includes a library called the APK Expansion Zip Library (located in {@code <sdk>/extras/google/google_market_apk_expansion/zip_file/}). This is an optional library that helps you read your expansion files when they're saved as ZIP files. Using this library allows you to easily read resources from your ZIP expansion files as a virtual file system.
The APK Expansion Zip Library includes the following classes and APIs:
mainVersion and the
patchVersion, this returns a {@code ZipResourceFile} that provides read access to
all the data, with the patch file's data merged on top of the main file.assetPath must be the path to the desired file, relative to
the root of the ZIP file contents.assetPath must be the path to the desired file, relative to
the root of the ZIP file contents. This is useful for certain Android APIs that require an {@link
android.content.res.AssetFileDescriptor}, such as some {@link android.media.MediaPlayer} APIs.When using the APK Expansion Zip Library, reading a file from your ZIP usually requires the following:
// Get a ZipResourceFile representing a merger of both the main and patch files
ZipResourceFile expansionFile =
APKExpansionSupport.getAPKExpansionZipFile(appContext,
mainVersion, patchVersion);
// Get an input stream for a known file inside the expansion file ZIPs
InputStream fileStream = expansionFile.getInputStream(pathToFileInsideZip);
The above code provides access to any file that exists in either your main expansion file or patch expansion file, by reading from a merged map of all the files from both files. All you need to provide the {@code getAPKExpansionFile()} method is your application {@code android.content.Context} and the version number for both the main expansion file and patch expansion file.
If you'd rather read from a specific expansion file, you can use the {@code ZipResourceFile} constructor with the path to the desired expansion file:
// Get a ZipResourceFile representing a specific expansion file ZipResourceFile expansionFile = new ZipResourceFile(filePathToMyZip); // Get an input stream for a known file inside the expansion file ZIPs InputStream fileStream = expansionFile.getInputStream(pathToFileInsideZip);
For more information about using this library for your expansion files, look at the sample application's {@code SampleDownloaderActivity} class, which includes additional code to verify the downloaded files using CRC. Beware that if you use this sample as the basis for your own implementation, it requires that you declare the byte size of your expansion files in the {@code xAPKS} array.
Before publishing your application, there are two things you should test: Reading the expansion files and downloading the files.
Before you upload your application to Google Play, you should test your application's ability to read the files from the shared storage. All you need to do is add the files to the appropriate location on the device shared storage and launch your application:
For example, if your package name is {@code com.example.android}, you need to create the directory {@code Android/obb/com.example.android/} on the shared storage space. (Plug in your test device to your computer to mount the shared storage and manually create this directory.)
For example, regardless of the file type, the main expansion file for the {@code com.example.android} application should be {@code main.0300110.com.example.android.obb}. The version code can be whatever value you want. Just remember:
Here are some reminders about handling the expansion files:
obb/
directory. If you must unpack some data, save it into the location specified by {@link
android.content.Context#getExternalFilesDir getExternalFilesDir()}.Because your application must sometimes manually download the expansion files when it first opens, it's important that you test this process to be sure your application can successfully query for the URLs, download the files, and save them to the device.
To test your application's implementation of the manual download procedure, you can publish it to the alpha or beta channel, so it will only be available to authorized testers. If everything works as expected, your application should begin downloading the expansion files as soon as the main activity starts.
Note: Previously you could test an app by uploading an unpublished "draft" version. This functionality is no longer supported; instead, you must publish it to the alpha or beta distribution channel. For more information, see Draft Apps are No Longer Supported.
One of the great benefits to using expansion files on Google Play is the ability to update your application without re-downloading all of the original assets. Because Google Play allows you to provide two expansion files with each APK, you can use the second file as a "patch" that provides updates and new assets. Doing so avoids the need to re-download the main expansion file which could be large and expensive for users.
The patch expansion file is technically the same as the main expansion file and neither the Android system nor Google Play perform actual patching between your main and patch expansion files. Your application code must perform any necessary patches itself.
If you use ZIP files as your expansion files, the APK Expansion Zip Library that's included with the Apk Expansion package includes the ability to merge your patch file with the main expansion file.
Note: Even if you only need to make changes to the patch expansion file, you must still update the APK in order for Google Play to perform an update. If you don't require code changes in the application, you should simply update the {@code versionCode} in the manifest.
As long as you don't change the main expansion file that's associated with the APK in the Developer Console, users who previously installed your application will not download the main expansion file. Existing users receive only the updated APK and the new patch expansion file (retaining the previous main expansion file).
Here are a few issues to keep in mind regarding updates to expansion files: