APK Expansion Files

APK Expansion Files

Quickview

• Recommended for most apps that exceed the 50MB APK limit
• You can provide up to 4GB of additional data for each APK
• Google Play hosts and serves the expansion files at no charge
• The files can be any file type you want and are saved to the device's shared storage

In this document

1. Overview
   1. File name format
   2. Storage location
   3. Download process
   4. Development checklist
2. Rules and Limitations
3. Downloading the Expansion Files
   1. About the Downloader Library
   2. Preparing to use the Downloader Library
   3. Declaring user permissions
   4. Implementing the downloader service
   5. Implementing the alarm receiver
   6. Starting the download
   7. Receiving download progress
4. Using APKExpansionPolicy
5. Reading the Expansion File
   1. Getting the file names
   2. Using the APK Expansion Zip Library
6. Testing Your Expansion Files
   1. Testing file reads
   2. Testing file downloads
7. Updating Your Application

See also

1. Application Licensing
2. MultipleAPK Support

Google Play currently requires that your APK file be no more than 50MB. For mostapplications, 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 resourcesyourself when the user opens the app. Hosting and serving the extra files can be costly, and theuser experience is often less than ideal. To make this process easier for you and more pleasantfor users, Google Play allows you to attach two large expansion files that supplement yourAPK.

Google Play hosts the expansion files for your application and serves them to the device atno cost to you. The expansion files are saved to the device's shared storage location (theSD card or USB-mountable partition; also known as the "external" storage) where your app can accessthem. On most devices, Google Play downloads the expansion file(s) at the same time itdownloads the APK, so your application has everything it needs when the user opens it for thefirst time. In some cases, however, your application must download the files from Google Playwhen your application starts.

Overview

Each time you upload an APK using the Google Play Developer Console, you have the option toadd one or two expansion files to the APK. Each file can be up to 2GB and it can be any format youchoose, but we recommend you use a compressed file to conserve bandwidth during the download.Conceptually, each expansion file plays a different role:

• The main expansion file is theprimary expansion file for additional resources required by your application.
• The patch expansion file is optional and intended for small updates to themain expansion file.

While you can use the two expansion files any way you wish, we recommend that the mainexpansion file deliver the primary assets and should rarely if ever updated; the patch expansionfile should be smaller and serve as a “patch carrier,” getting updated with each majorrelease or as necessary.

However, even if your application update requires only a new patch expansion file, you still mustupload a new APK with an updated versionCode in the manifest. (TheDeveloper Console does not allow you to upload an expansion file to an existing APK.)

Note: The patch expansion file is semantically the same as themain expansion file—you can use each file any way you want. The system doesnot use the patch expansion file to perform patching for your app. You must perform patchingyourself or be able to distinguish between the two files.

File name format

Each expansion file you upload can be any format you choose (ZIP, PDF, MP4, etc.). You can alsouse the JOBB tool to encapsulate and encrypt a setof resource files and subsequent patches for that set. Regardless of the file type, Google Playconsiders 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:

main or patch

Specifies whether the file is the main or patch expansion file. There can beonly one main file and one patch file for each APK.

<expansion-version>

This is an integer that matches the version code of the APK with which the expansion is first associated (it matches the application's android:versionCodevalue).

"First" is emphasized because although the Developer Console allows you tore-use an uploaded expansion file with a new APK, the expansion file's name does not change—itretains the version applied to it when you first uploaded the file.

<package-name>

Your application's Java-style package name.

For example, suppose your APK version is 314159 and your package name is com.example.app. If youupload a main expansion file, the file is renamed to:

main.314159.com.example.app.obb

Storage location

When Google Play downloads your expansion files to a device, it saves them to the system'sshared storage location. To ensure proper behavior, you must not delete, move, or rename theexpansion files. In the event that your application must perform the download from Google Playitself, you must save the files to the exact same location.

The specific location for your expansion files is:

<shared-storage>/Android/obb/<package-name>/

• <shared-storage> is the path to the shared storage space, available fromgetExternalStorageDirectory().
• <package-name> is your application's Java-style package name, availablefrom getPackageName().

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). Previousversions 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.obb expansion files afterwards and do not save the unpacked datain the same directory. You should save your unpacked files in the directoryspecified by getExternalFilesDir(). However,if possible, it's best if you use an expansion file format that allows you to read directly fromthe file instead of requiring you to unpack the data. For example, we've provided a libraryproject called the APK Expansion Zip Library that reads your data directlyfrom the ZIP file.

Note: Unlike APK files, any files saved on the shared storage canbe read by the user and other applications.

Tip: If you're packaging media files into a ZIP, you can use mediaplayback calls on the files with offset and length controls (such as MediaPlayer.setDataSource() andSoundPool.load()) without theneed to unpack your ZIP. In order for this to work, you must not perform additional compression onthe 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 becompressed:
zip -n .mp4;.ogg main_expansion media_files

Download process

Most of the time, Google Play downloads and saves your expansion files at the same time itdownloads the APK to the device. However, in some cases Google Playcannot download the expansion files or the user might have deleted previously downloaded expansionfiles. To handle these situations, your app must be able to download the filesitself when the main activity starts, using a URL provided by Google Play.

The download process from a high level looks like this:

1. User selects to install your app from Google Play.
2. If Google Play is able to download the expansion files (which is the case for mostdevices), it downloads them along with the APK.

   If Google Play is unable to download the expansion files, it downloads theAPK only.

3. When the user launches your application, your app must check whether the expansion files arealready saved on the device.
   1. If yes, your app is ready to go.
   2. If no, your app must download the expansion files over HTTP from Google Play. Your appmust send a request to the Google Play client using the Google Play's Application Licensing service, whichresponds with the name, file size, and URL for each expansion file. With this information, you thendownload the files and save them to the proper storage location.

Caution: It is critical that you include the necessary code todownload the expansion files from Google Play in the event that the files are not already on thedevice when your application starts. As discussed in the following section about Downloading the Expansion Files, we've made a library available to you thatgreatly simplifies this process and performs the download from a service with a minimal amount ofcode from you.

Development checklist

Here's a summary of the tasks you should perform to use expansion files with yourapplication:

1. First determine whether your application absolutely requires more than 50MB per installation.Space is precious and you should keep your total application size as small as possible. If your appuses more than 50MB in order to provide multiple versions of your graphic assets for multiple screendensities, consider instead publishing multiple APKs in which each APKcontains only the assets required for the screens that it targets.
2. Determine which application resources to separate from your APK and package them in afile to use as the main expansion file.

   Normally, you should only use the second patch expansion file when performing updates tothe main expansion file. However, if your resources exceed the 2GB limit for the mainexpansion file, you can use the patch file for the rest of your assets.

3. Develop your application such that it uses the resources from your expansion files in thedevice's shared storage location.

   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 foryour expansion files, then read them using the APK Expansion ZipLibrary.

4. Add logic to your application's main activity that checks whether the expansion filesare on the device upon start-up. If the files are not on the device, use Google Play's Application Licensing service to request URLsfor the expansion files, then download and save them.

   To greatly reduce the amount of code you must write and ensure a good user experienceduring the download, we recommend you use the DownloaderLibrary to implement your download behavior.

   If you build your own download service instead of using the library, be aware that youmust not change the name of the expansion files and must save them to the properstorage location.

Once you've finished your application development, follow the guide to TestingYour Expansion Files.

Rules and Limitations

Adding APK expansion files is a feature available when you upload your application using theDeveloper Console. When uploading your application for the first time or updating anapplication that uses expansion files, you must be aware of the following rules and limitations:

1. Each expansion file can be no more than 2GB.
2. In order to download your expansion files from Google Play, the user must haveacquired your application from Google Play. Google Play will notprovide the URLs for your expansion files if the application was installed by other means.
3. When performing the download from within your application, the URL that Google Playprovides for each file is unique for every download and each one expires shortly after it is givento your application.
4. If you update your application with a new APK or upload multiple APKs for the sameapplication, you can select expansion files that you've uploaded for a previous APK. Theexpansion file's name does not change—it retains the version received by the APK towhich the file was originally associated.
5. If you use expansion files in combination with multiple APKs in order toprovide different expansion files for different devices, you still must upload separate APKsfor each device in order to provide a unique versionCodevalue and declare different filters foreach APK.
6. You cannot issue an update to your application by changing the expansion filesalone—you must upload a new APK to update your app. If your changes onlyconcern the assets in your expansion files, you can update your APK simply by changing the versionCode (andperhaps also the versionName).
7. Do not save other data into your obb/directory. If you must unpack some data, save it into the location specified by getExternalFilesDir().
8. Do not delete or rename the .obb expansion file (unless you'reperforming an update). Doing so will cause Google Play (or your app itself) to repeatedlydownload the expansion file.
9. When updating an expansion file manually, you must delete the previous expansion file.

Downloading the Expansion Files

In most cases, Google Play downloads and saves your expansion files to the device at the sametime it installs or updates the APK. This way, the expansion files are available when yourapplication launches for the first time. However, in some cases your app must download theexpansion files itself by requesting them from a URL provided to you in a responsefrom Google Play's Application Licensing service.

The basic logic you need to download your expansion files is the following:

1. When your application starts, look for the expansion files on the shared storage location (in theAndroid/obb/<package-name>/ directory).
   1. If the expansion files are there, you're all set and your application can continue.
   2. If the expansion files are not there:
      1. Perform a request using Google Play's Application Licensing to get yourapp's expansion file names, sizes, and URLs.
      2. Use the URLs provided by Google Play to download the expansion files and savethe expansion files. You must save the files to the shared storage location(Android/obb/<package-name>/) and use the exact file name providedby Google Play's response.

         Note: The URL that Google Play provides for yourexpansion files is unique for every download and each one expires shortly after it is given toyour application.

If your application is free (not a paid app), then you probably haven't used the Application Licensing service. It's primarilydesigned for you to enforcelicensing policies for your application and ensure that the user has the right touse your app (he or she rightfully paid for it on Google Play). In order to facilitate theexpansion file functionality, the licensing service has been enhanced to provide a responseto your application that includes the URL of your application's expansion files that are hostedon Google Play. So, even if your application is free for users, you need to include theLicense Verification Library (LVL) to use APK expansion files. Of course, if your applicationis free, you don't need to enforce license verification—you simply need thelibrary to perform the request that returns the URL of your expansion files.

Note: Whether your application is free or not, Google Playreturns 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 filesover 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 intoconsideration:

• The device might not have enough space for the expansion files, so you should checkbefore beginning the download and warn the user if there's not enough space.
• File downloads should occur in a background service in order to avoid blocking the userinteraction and allow the user to leave your app while the download completes.
• A variety of errors might occur during the request and download that you mustgracefully handle.
• Network connectivity can change during the download, so you should handle such changes andif interrupted, resume the download when possible.
• While the download occurs in the background, you should provide a notification thatindicates the download progress, notifies the user when it's done, and takes the user back toyour application when selected.

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 thedownload. By adding the Downloader Library and a few code hooks to your application, almost all thework to download the expansion files is already coded for you. As such, in order to provide the bestuser experience with minimal effort on your behalf, we recommend you use the Downloader Library todownload your expansion files. The information in the following sections explain how to integratethe library into your application.

If you'd rather develop your own solution to download the expansion files using the GooglePlay URLs, you must follow the ApplicationLicensing documentation to perform a license request, then retrieve the expansion file names,sizes, and URLs from the response extras. You should use the APKExpansionPolicy class (included in the License Verification Library) as your licensingpolicy, which captures the expansion file names, sizes, and URLs from the licensing service..

About the Downloader Library

To use APK expansion files with your application and provide the best user experience withminimal effort on your behalf, we recommend you use the Downloader Library that's included in theGoogle Play APK Expansion Library package. This library downloads your expansion files in abackground service, shows a user notification with the download status, handles networkconnectivity loss, resumes the download when possible, and more.

To implement expansion file downloads using the Downloader Library, all you need to do is:

• Extend a special Service subclass and BroadcastReceiver subclass that each require just a fewlines of code from you.
• Add some logic to your main activity that checks whether the expansion files havealready been downloaded and, if not, invokes the download process and displays aprogress UI.
• Implement a callback interface with a few methods in your main activity thatreceives updates about the download progress.

The following sections explain how to set up your app using the Downloader Library.

Preparing to use the Downloader Library

To use the Downloader Library, you need todownload two packages from the SDK Manager and add the appropriate libraries to yourapplication.

First, open the Android SDK Manager, expandExtras and download:

• Google Play Licensing Library package
• Google Play APK Expansion Library package

If you're using Eclipse, create a project for each library and add it to your app:

1. Create a new Library Project for the License Verification Library and DownloaderLibrary. For each library:
   1. Begin a new Android project.
   2. Select Create project from existingsource and choose the library from the <sdk>/extras/google/ directory(market_licensing/ for the License Verification Library or market_apk_expansion/downloader_library/ for the Downloader Library).
   3. Specify a Project Name such as "Google Play License Library" and "Google PlayDownloaderLibrary"
   4. Click Finish.

   Note: The Downloader Library depends on the LicenseVerification Library. Be sure to add the LicenseVerification Library to the Downloader Library's project properties (same process assteps 2 and 3 below).

2. Right-click the Android project in which you want to use APK expansion files andselect Properties.
3. In the Library panel, click Add to select and add each of thelibraries to your application.

Or, from a command line, update your project to include the libraries:

1. Change directories to the <sdk>/tools/ directory.
2. Execute android update project with the --library option to add both theLVL 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 yourapplication, you'll be able to quickly integrate the ability to download expansion files fromGoogle Play. The format that you choose for the expansion files and how you read themfrom the shared storage is a separate implementation that you should consider based on yourapplication needs.

Tip: The Apk Expansion package includes a sampleapplicationthat shows how to use the Downloader Library in an app. The sample uses a third libraryavailable in the Apk Expansion package called the APK Expansion Zip Library. Ifyou plan onusing ZIP files for your expansion files, we suggest you also add the APK Expansion Zip Library toyour application. For more information, see the section belowabout Using the APK Expansion Zip Library.

Declaring user permissions

In order to download the expansion files, the Downloader Libraryrequires several permissions that you must declare in your application's manifest file. Theyare:

<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 APIlevel 4, but the APK Expansion Zip Library requires API level 5.

Implementing the downloader service

In order to perform downloads in the background, the Downloader Library provides itsown Service subclass called DownloaderService that you should extend. Inaddition to downloading the expansion files for you, the DownloaderService also:

• Registers a BroadcastReceiver that listens for changes to thedevice's network connectivity (the CONNECTIVITY_ACTIONbroadcast) in order to pause the download when necessary (such as due to connectivity loss) andresume the download when possible (connectivity is acquired).
• Schedules an RTC_WAKEUP alarm to retry the download forcases in which the service gets killed.
• Builds a custom Notification that displays the download progress andany errors or state changes.
• Allows your application to manually pause and resume the download.
• Verifies that the shared storage is mounted and available, that the files don't already exist,and that there is enough space, all before downloading the expansion files. Then notifies the userif any of these are not true.

All you need to do is create a class in your application that extends the DownloaderService class and override three methods to provide specific application details:

getPublicKey()

This must return a string that is the Base64-encoded RSA public key for your publisheraccount, available from the profile page on the Developer Console (see Setting Up for Licensing).

getSALT()

This must return an array of random bytes that the licensing Policy uses tocreate an Obfuscator. The salt ensures that your obfuscated SharedPreferencesfile in which your licensing data is saved will be unique and non-discoverable.

getAlarmReceiverClassName()

This must return the class name of the BroadcastReceiver inyour application that should receive the alarm indicating that the download should berestarted (which might happen if the downloader service unexpectedly stops).

For example, here's a complete implementation of 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 BASE64_PUBLIC_KEY valueto be the public key belonging to your publisher account. You can find the key in the DeveloperConsole under your profile information. This is necessary even when testingyour downloads.

Remember to declare the service in your manifest file:

<application ...>
    <service android:name=".SampleDownloaderService" />
    ...
</application>

Implementing the alarm receiver

In order to monitor the progress of the file downloads and restart the download if necessary, theDownloaderService schedules an RTC_WAKEUP alarm thatdelivers an Intent to a BroadcastReceiver in yourapplication. You must define the BroadcastReceiver to call an APIfrom the Downloader Library that checks the status of the download and restartsit if necessary.

You simply need to override the onReceive() method to call 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 namein your service's getAlarmReceiverClassName() method (see the previous section).

Remember to declare the receiver in your manifest file:

<application ...>
    <receiver android:name=".SampleAlarmReceiver" />
    ...
</application>

Starting the download

The main activity in your application (the one started by your launcher icon) isresponsible for verifying whether the expansion files are already on the device and initiatingthe download if they are not.

Starting the download using the Downloader Library requires the followingprocedures:

1. Check whether the files have been downloaded.

   The Downloader Library includes some APIs in the Helper class tohelp with this process:

   • getExpansionAPKFileName(Context, c, boolean mainFile, intversionCode)
   • doesFileExist(Context c, String fileName, long fileSize)

   For example, the sample app provided in the Apk Expansion package calls thefollowing method in the activity's onCreate() method to checkwhether 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 XAPKFile object holds the version number and file size of a knownexpansion file and a boolean as to whether it's the main expansion file. (See the sampleapplication's SampleDownloaderActivity class for details.)

   If this method returns false, then the application must begin the download.

2. Start the download by calling the static method DownloaderClientMarshaller.startDownloadServiceIfRequired(Context c, PendingIntentnotificationClient, Class<?> serviceClass).

   The method takes the following parameters:

   • context: Your application's Context.
   • notificationClient: A PendingIntent to start your mainactivity. This is used in the Notification that the DownloaderServicecreates to show the download progress. When the user selects the notification, the systeminvokes the PendingIntent you supply here and should open the activitythat shows the download progress (usually the same activity that started the download).
   • serviceClass: The Class object for your implementation ofDownloaderService, required to start the service and begin the download if necessary.

   The method returns an integer that indicateswhether or not the download is required. Possible values are:

   • NO_DOWNLOAD_REQUIRED: Returned if the files alreadyexist or a download is already in progress.
   • LVL_CHECK_REQUIRED: Returned if a license verification isrequired in order to acquire the expansion file URLs.
   • DOWNLOAD_REQUIRED: Returned if the expansion file URLs are already known,but have not been downloaded.

   The behavior for LVL_CHECK_REQUIRED and DOWNLOAD_REQUIRED are essentially thesame and you normally don't need to be concerned about them. In your main activity that calls startDownloadServiceIfRequired(), you can simply check whether or not the response is NO_DOWNLOAD_REQUIRED. If the response is anything other than NO_DOWNLOAD_REQUIRED,the Downloader Library begins the download and you should update your activity UI todisplay the download progress (see the next step). If the response is 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
   }

3. When the startDownloadServiceIfRequired() method returns anything otherthan NO_DOWNLOAD_REQUIRED, create an instance of IStub bycalling DownloaderClientMarshaller.CreateStub(IDownloaderClient client, Class<?>downloaderService). The IStub provides a binding between your activity to the downloaderservice such that your activity receives callbacks about the download progress.

   In order to instantiate your IStub by calling CreateStub(), you must pass itan implementation of the IDownloaderClient interface and your DownloaderServiceimplementation. The next section about Receiving download progress discussesthe IDownloaderClient interface, which you should usually implement in your Activity class so you can update the activity UI when the download state changes.

   We recommend that you call CreateStub() to instantiate your IStub during your activity's onCreate() method, after startDownloadServiceIfRequired()starts the download.

   For example, in the previous code sample for onCreate(), you can respond to the 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 onCreate() method returns, your activityreceives a call to onResume(), which is where you should thencall connect() on the IStub, passing it your application's Context. Conversely, you should calldisconnect() in your activity's 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 connect() on the IStub binds your activity to the DownloaderService such that your activity receives callbacks regarding changes to the downloadstate through the IDownloaderClient interface.

Receiving download progress

To receive updates regarding the download progress and to interact with the DownloaderService, you must implement the Downloader Library's IDownloaderClient interface.Usually, the activity you use to start the download should implement this interface in order todisplay the download progress and send requests to the service.

The required interface methods for IDownloaderClient are:

onServiceConnected(Messenger m)

After you instantiate the IStub in your activity, you'll receive a call to thismethod, which passes a Messenger object that's connected with your instanceof DownloaderService. To send requests to the service, such as to pause and resumedownloads, you must call DownloaderServiceMarshaller.CreateProxy() to receive the IDownloaderService interface connected to the service.

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 IDownloaderService object initialized, you can send commands to thedownloader service, such as to pause and resume the download (requestPauseDownload()and requestContinueDownload()).

onDownloadStateChanged(int newState)

The download service calls this when a change in download state occurs, such as thedownload begins or completes.

The newState value will be one of several possible values specified inby one of the IDownloaderClient class's STATE_* constants.

To provide a useful message to your users, you can request a corresponding stringfor each state by calling Helpers.getDownloaderStringResourceIDFromState(). Thisreturns the resource ID for one of the strings bundled with the DownloaderLibrary. For example, the string "Download paused because you are roaming" corresponds to STATE_PAUSED_ROAMING.

onDownloadProgress(DownloadProgressInfo progress)

The download service calls this to deliver a DownloadProgressInfo object,which describes various information about the download progress, including estimated time remaining,current speed, overall progress, and total so you can update the download progress UI.

Tip: For examples of these callbacks that update the downloadprogress UI, see the SampleDownloaderActivity in the sample app provided with theApk Expansion package.

Some public methods for the IDownloaderService interface you might find useful are:

requestPauseDownload()

Pauses the download.

requestContinueDownload()

Resumes a paused download.

setDownloadFlags(int flags)

Sets user preferences for network types on which its OK to download the files. Thecurrent implementation supports one flag, FLAGS_DOWNLOAD_OVER_CELLULAR, but you can addothers. By default, this flag is not enabled, so the user must be on Wi-Fi to downloadexpansion files. You might want to provide a user preference to enable downloads overthe cellular network. In which case, you can call:

mRemoteService.setDownloadFlags(IDownloaderService.FLAGS_DOWNLOAD_OVER_CELLULAR);

Using APKExpansionPolicy

If you decide to build your own downloader service instead of using the Google PlayDownloader Library, you should still use the APKExpansionPolicy that's provided in the License Verification Library. The APKExpansionPolicy class is nearly identical to ServerManagedPolicy (available in theGoogle Play License Verification Library) but includes additional handling for the APK expansionfile response extras.

Note: If you do use the Downloader Library as discussed in the previous section, thelibrary performs all interaction with the APKExpansionPolicy so you don't have to usethis class directly.

The class includes methods to help you get the necessary information about the availableexpansion files:

• getExpansionURLCount()
• getExpansionURL(int index)
• getExpansionFileName(int index)
• getExpansionFileSize(int index)

For more information about how to use the APKExpansionPolicy when you're notusing the Downloader Library, see the documentation for Adding Licensing to Your App,which explains how to implement a license policy such as this one.

Reading the Expansion File

Once your APK expansion files are saved on the device, how you read your filesdepends on the type of file you've used. As discussed in the overview, yourexpansion files can be any kind of file youwant, but are renamed using a particular file name format and are saved to<shared-storage>/Android/obb/<package-name>/.

Regardless of how you read your files, you should always first check that the externalstorage is available for reading. There's a chance that the user has the storage mounted to acomputer over USB or has actually removed the SD card.

Note: When your application starts, you should always check whetherthe external storage space is available and readable by calling getExternalStorageState(). This returns one of several possible stringsthat represent the state of the external storage. In order for it to be readable by yourapplication, the return value must be MEDIA_MOUNTED.

Getting the file names

As described in the overview, your APK expansion files are savedusing 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 thegetExternalStorageDirectory() and 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 pathto 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 Contextand the desired expansion file's version.

There are many ways you could determine the expansion file version number. One simple way is tosave the version in a SharedPreferences file when the download begins, byquerying the expansion file name with the APKExpansionPolicy class's getExpansionFileName(int index) method. You can then get the version code by reading the SharedPreferences file when you want to access the expansionfile.

For more information about reading from the shared storage, see the Data Storagedocumentation.

Using the APK Expansion Zip Library

Reading media files from a ZIP

If you're using your expansion files to store media files, a ZIP file still allows you touse Android media playback calls that provide offset and length controls (such as MediaPlayer.setDataSource() andSoundPool.load()). In order forthis to work, you must not perform additional compression on the media files when creating the ZIPpackages. For example, when using the zip tool, you should use the -noption 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 APKExpansion Zip Library (located in <sdk>/extras/google/google_market_apk_expansion/zip_file/). This is an optional library thathelps you read your expansionfiles when they're saved as ZIP files. Using this library allows you to easily read resources fromyour ZIP expansion files as a virtual file system.

The APK Expansion Zip Library includes the following classes and APIs:

APKExpansionSupport

Provides some methods to access expansion file names and ZIP files:

getAPKExpansionFiles()

The same method shown above that returns the complete file path to both expansionfiles.

getAPKExpansionZipFile(Context ctx, int mainVersion, intpatchVersion)

Returns a ZipResourceFile representing the sum of both the main file andpatch file. That is, if you specify both the mainVersion and the patchVersion, this returns a ZipResourceFile that provides read access toall the data, with the patch file's data merged on top of the main file.

ZipResourceFile

Represents a ZIP file on the shared storage and performs all the work to provide a virtualfile system based on your ZIP files. You can get an instance using APKExpansionSupport.getAPKExpansionZipFile() or with the ZipResourceFile by passing it thepath to your expansion file. This class includes a variety of useful methods, but you generallydon't need to access most of them. A couple of important methods are:

getInputStream(String assetPath)

Provides an InputStream to read a file within the ZIP file. The assetPath must be the path to the desired file, relative tothe root of the ZIP file contents.

getAssetFileDescriptor(String assetPath)

Provides an AssetFileDescriptor for a file within theZIP file. The assetPath must be the path to the desired file, relative tothe root of the ZIP file contents. This is useful for certain Android APIs that require an AssetFileDescriptor, such as some MediaPlayer APIs.

APEZProvider

Most applications don't need to use this class. This class defines a ContentProvider that marshals the data from the ZIP files through a contentprovider Uri in order to provide file access for certain Android APIs thatexpect Uri access to media files. For example, this is useful if you want toplay a video with VideoView.setVideoURI().

Reading from a ZIP file

When using the APK Expansion Zip Library, reading a file from your ZIP usually requires thefollowing:

// 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 orpatch expansion file, by reading from a merged map of all the files from both files. All youneed to provide the getAPKExpansionFile() method is your application android.content.Context and the version number for both the main expansion file and patchexpansion file.

If you'd rather read from a specific expansion file, you can use the 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 atthe sample application's SampleDownloaderActivity class, which includes additional code toverify the downloaded files using CRC. Beware that if you use this sample as the basis foryour own implementation, it requires that you declare the byte size of your expansionfiles in the xAPKS array.

Testing Your Expansion Files

Before publishing your application, there are two things you should test: Reading theexpansion files and downloading the files.

Testing file reads

Before you upload your application to Google Play, youshould test your application's ability to read the files from the shared storage. All you need to dois add the files to the appropriate location on the device shared storage and launch yourapplication:

1. On your device, create the appropriate directory on the shared storage where GooglePlay will save your files.

   For example, if your package name is com.example.android, you need to createthe directory Android/obb/com.example.android/ on the shared storage space. (Plug inyour test device to your computer to mount the shared storage and manually create thisdirectory.)

2. Manually add the expansion files to that directory. Be sure that you rename your files tomatch the file name format that Google Play will use.

   For example, regardless of the file type, the main expansion file for the com.example.android application should be main.0300110.com.example.android.obb.The version code can be whatever value you want. Just remember:

   • The main expansion file always starts with main and the patch file starts withpatch.
   • The package name always matches that of the APK to which the file is attached onGoogle Play.
3. Now that the expansion file(s) are on the device, you can install and run your application totest your expansion file(s).

Here are some reminders about handling the expansion files:

• Do not delete or rename the .obb expansion files (even if you unpackthe data to a different location). Doing so will cause Google Play (or your app itself) torepeatedly download the expansion file.
• Do not save other data into your obb/directory. If you must unpack some data, save it into the location specified by getExternalFilesDir().

Testing file downloads

Because your application must sometimes manually download the expansion files when it firstopens, it's important that you test this process to be sure your application can successfully queryfor the URLs, download the files, and save them to the device.

To test your application's implementation of the manual download procedure, you must uploadyour application to Google Play as a "draft" to make your expansion files available fordownload:

1. Upload your APK and corresponding expansion files using the Google Play DeveloperConsole.
2. Fill in the necessary application details (title, screenshots, etc.). You can come back andfinalize these details before publishing your application.

   Click the Save button. Do not click Publish. This savesthe application as a draft, such that your application is not published for Google Play users,but the expansion files are available for you to test the download process.

3. Install the application on your test device using the Eclipse tools or adb.
4. Launch the app.

If everything works as expected, your application should begin downloading the expansionfiles as soon as the main activity starts.

Updating Your Application

One of the great benefits to using expansion files on Google Play is the ability toupdate your application without re-downloading all of the original assets. Because Google Playallows 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 theneed 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 neitherthe Android system nor Google Play perform actual patching between your main and patch expansionfiles. Your application code must perform any necessary patches itself.

If you use ZIP files as your expansion files, the APK Expansion ZipLibrary that's included with the Apk Expansion package includes the ability to mergeyourpatch file with the main expansion file.

Note: Even if you only need to make changes to the patchexpansion 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 versionCode in themanifest.

As long as you don't change the main expansion file that's associated with the APKin the Developer Console, users who previously installed your application will notdownload the main expansion file. Existing users receive only the updated APK and the new patchexpansion file (retaining the previous main expansion file).

Here are a few issues to keep in mind regarding updates to expansion files:

• There can be only two expansion files for your application at a time. One main expansionfile and one patch expansion file. During an update to a file, Google Play deletes theprevious version (and so must your application when performing manual updates).
• When adding a patch expansion file, the Android system does not actually patch yourapplication or main expansion file. You must design your application to support the patch data.However, the Apk Expansion package includes a library for using ZIP filesas expansion files, which merges the data from the patch file into the main expansion file soyou can easily read all the expansion file data.