However, even if your application update requires only a new patch expansion file, you must +main expansion file.
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 Android Market -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 @@ -160,12 +164,6 @@ itself, you must save the files to the exact same location.
Note: The location of the shared storage may be -different on different devices, so you should never refer to the shared storage space using an -absolute URI path. Always use {@link android.os.Environment#getExternalStorageDirectory} to -retrieve the root directory of the shared storage location.
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 @@ -180,7 +178,10 @@ the file instead of requiring you to unpack the data. For example, we've provide project called the APK Expansion Zip Library that reads your data directly from the ZIP file.
-Note: If you're packaging media files into a ZIP, you can use media +
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 @@ -261,7 +262,7 @@ are on the device upon start-up. If the files are not on the device, use Android href="{@docRoot}guide/market/licensing/index.html">Application Licensing service to request URLs for the expansion files, then download and save them.
To greatly reduce the amount of code you must write and ensure a good user experience -during the download, we recommend you use the Expansion Downloader +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 @@ -344,7 +345,8 @@ href="#StorageLocation">shared storage location (in the
Note: Whether your application is free or not, Android Market returns the expansion file URLs only if the user acquired your application from Android Market.
-To simplify this work for you, we've built the Expansion Downloader -Library, which requests the expansion file URLs through the licensing service and -downloads the expansion files for you. By adding this library and a few code hooks to your -application, almost all the work to download the expansion files is already coded for you, including -a status notification that tracks the download progress. As such, in order to provide the best user -experience with minimal effort on your behalf, we recommend you use the -Expansion 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 Android -Market 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 Android Market Expansion Downloader -Library.
- -As mentioned above, in order to use expansion files hosted by Android Market, you must use -the Android Market License Verification Library (LVL) to request the URLs from which to download the -expansion files. In addition to the LVL, you need a set of code that downloads the expansion files +
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:
@@ -422,9 +398,34 @@ indicates the download progress, notifies the user when it's done, and takes the your application when selected.Fortunately, the Android Market Expansion Downloader Library handles all of this work for you -and also allows your app to pause and resume the download. To implement expansion file downloads -using the library, all you need to do is:
+ +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 Android +Market 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 +Android Market 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 Expansion Downloader Library, you need to +
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 Expansion Downloader Library depends on the License +
Note: The Downloader Library depends on the License Verification Library. Be sure to add the License -Verification Library to the Expansion Downloader Library's project properties (same process as +Verification Library to the Downloader Library's project properties (same process as steps 2 and 3 below).
android update project --path ~/Android/MyApp \ --library ~/android_sdk/extras/google/market_licensing \ ---library ~/android_sdk/extras/google/market_downloader +--library ~/android_sdk/extras/google/market_apk_expansion/downloader_library
With both the License Verification Library and Expansion Downloader Library added to your +
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 Android Market. 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 Expansion Downloader package includes a sample application -that shows how to use the Expansion Downloader library in an app. The sample uses a third library -available in the Expansion Downloader package called the APK Expansion Zip Library. If you plan on +
Tip: The APK Expansion Library 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 Library 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. You might want to use the sample application as a starting point for your -implementation.
+your application. For more information, see the section below +about Using the APK Expansion Zip Library.In order to download the expansion files, the Expansion Downloader 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:
@@ -532,13 +538,13 @@ are: </manifest> -Note: By default, the Expansion Downloader Library requires API +
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 Expansion Downloader Library provides its +
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:
@@ -626,7 +632,7 @@ your downloads. {@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 Expansion Downloader Library that checks the status of the download and restarts +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 @@ -668,19 +674,19 @@ in your service's {@code getAlarmReceiverClassName()} method (see the previous s 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 Expansion Downloader library requires the following +
Starting the download using the Downloader Library requires the following procedures:
The Expansion Downloader library includes some APIs in the {@code Helper} class to +
The Downloader Library includes some APIs in the {@code Helper} class to help with this process:
For example, the sample app provided in the Expansion Downloader package calls the +
For example, the sample app provided in the APK Expansion Library 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:
@@ -725,7 +731,7 @@ but have not been downloaded.
For example:
@@ -855,7 +861,7 @@ download begins or completes. 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 Expansion Downloader +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}.
If you decide to build your own downloader service instead of using the Android Market -Expansion Downloader Library, you should still use the {@code +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 Android Market License Verification Library) but includes additional handling for the APK expansion file response extras.
Note: If you do use the Expansion Downloader Library as discussed in the previous section, the +href="#AboutLibraries">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.
@@ -915,7 +921,7 @@ expansion files:For more information about how to use the {@code APKExpansionPolicy} when you're not using the Expansion Downloader Library, see the documentation for Downloader Library, see the documentation for Adding Licensing to Your App, which explains how to implement a license policy such as this one.
@@ -1030,8 +1036,10 @@ option to specify the file suffixes that should not be compressed: -The Android Market Expansion Downloader package includes a library called the APK -Expansion Zip Library. This is an optional library that helps you read your expansion +
The Android Market APK Expansion Library 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.
@@ -1080,7 +1088,7 @@ android.content.ContentProvider} that marshals the data from the ZIP files throu provider {@link android.net.Uri} in order to provide file access for certain Android APIs that expect {@link android.net.Uri} access to media files.The sample application available in the -Expansion Downloader package demonstrates a scenario in which this class is useful +APK Expansion Library package demonstrates a scenario in which this class is useful to specify a video with {@link android.widget.VideoView#setVideoURI VideoView.setVideoURI()}. See the sample app's class {@code SampleZipfileProvider} for an example of how to extend this class to use in your application.
@@ -1212,7 +1220,8 @@ the Android system nor Android Market perform actual patching between your main 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 Expansion Downloader package includes the ability to merge your +Library that's included with the APK Expansion Library 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 @@ -1234,14 +1243,13 @@ file and one patch expansion file. During an update to a file, Android Market de previous version (and so must your application when performing manual updates).