1 page.title=APK Expansion Files 2 page.metaDescription=If your app needs more than the 50MB APK max, use free APK expansion files from Google Play. 3 page.tags="apk size, apk max, large assets" 4 @jd:body 5 6 7 <div id="qv-wrapper"> 8 <div id="qv"> 9 <h2>Quickview</h2> 10 <ul> 11 <li>Recommended for most apps that exceed the 50MB APK limit</li> 12 <li>You can provide up to 4GB of additional data for each APK</li> 13 <li>Google Play hosts and serves the expansion files at no charge</li> 14 <li>The files can be any file type you want and are saved to the device's shared storage</li> 15 </ul> 16 17 <h2>In this document</h2> 18 <ol> 19 <li><a href="#Overview">Overview</a> 20 <ol> 21 <li><a href="#Filename">File name format</a></li> 22 <li><a href="#StorageLocation">Storage location</a></li> 23 <li><a href="#DownloadProcess">Download process</a></li> 24 <li><a href="#Checklist">Development checklist</a></li> 25 </ol> 26 </li> 27 <li><a href="#Rules">Rules and Limitations</a></li> 28 <li><a href="#Downloading">Downloading the Expansion Files</a> 29 <ol> 30 <li><a href="#AboutLibraries">About the Downloader Library</a></li> 31 <li><a href="#Preparing">Preparing to use the Downloader Library</a></li> 32 <li><a href="#Permissions">Declaring user permissions</a></li> 33 <li><a href="#DownloaderService">Implementing the downloader service</a></li> 34 <li><a href="#AlarmReceiver">Implementing the alarm receiver</a></li> 35 <li><a href="#Download">Starting the download</a></li> 36 <li><a href="#Progress">Receiving download progress</a></li> 37 </ol> 38 </li> 39 <li><a href="#ExpansionPolicy">Using APKExpansionPolicy</a></li> 40 <li><a href="#ReadingTheFile">Reading the Expansion File</a> 41 <ol> 42 <li><a href="#GettingFilenames">Getting the file names</a></li> 43 <li><a href="#ZipLib">Using the APK Expansion Zip Library</a></li> 44 </ol> 45 </li> 46 <li><a href="#Testing">Testing Your Expansion Files</a> 47 <ol> 48 <li><a href="#TestingReading">Testing file reads</a></li> 49 <li><a href="#TestingReading">Testing file downloads</a></li> 50 </ol> 51 </li> 52 <li><a href="#Updating">Updating Your Application</a></li> 53 </ol> 54 55 <h2>See also</h2> 56 <ol> 57 <li><a href="{@docRoot}google/play/licensing/index.html">Application Licensing</a></li> 58 <li><a href="{@docRoot}google/play/publishing/multiple-apks.html">Multiple 59 APK Support</a></li> 60 </ol> 61 </div> 62 </div> 63 64 65 66 <p>Google Play currently requires that your APK file be no more than 50MB. For most 67 applications, this is plenty of space for all the application's code and assets. 68 However, some apps need more space for high-fidelity graphics, media files, or other large assets. 69 Previously, if your app exceeded 50MB, you had to host and download the additional resources 70 yourself when the user opens the app. Hosting and serving the extra files can be costly, and the 71 user experience is often less than ideal. To make this process easier for you and more pleasant 72 for users, Google Play allows you to attach two large expansion files that supplement your 73 APK.</p> 74 75 <p>Google Play hosts the expansion files for your application and serves them to the device at 76 no cost to you. The expansion files are saved to the device's shared storage location (the 77 SD card or USB-mountable partition; also known as the "external" storage) where your app can access 78 them. On most devices, Google Play downloads the expansion file(s) at the same time it 79 downloads the APK, so your application has everything it needs when the user opens it for the 80 first time. In some cases, however, your application must download the files from Google Play 81 when your application starts.</p> 82 83 84 85 <h2 id="Overview">Overview</h2> 86 87 <p>Each time you upload an APK using the Google Play Developer Console, you have the option to 88 add one or two expansion files to the APK. Each file can be up to 2GB and it can be any format you 89 choose, but we recommend you use a compressed file to conserve bandwidth during the download. 90 Conceptually, each expansion file plays a different role:</p> 91 92 <ul> 93 <li>The <strong>main</strong> expansion file is the 94 primary expansion file for additional resources required by your application.</li> 95 <li>The <strong>patch</strong> expansion file is optional and intended for small updates to the 96 main expansion file.</li> 97 </ul> 98 99 <p>While you can use the two expansion files any way you wish, we recommend that the main 100 expansion file deliver the primary assets and should rarely if ever updated; the patch expansion 101 file should be smaller and serve as a patch carrier, getting updated with each major 102 release or as necessary.</p> 103 104 <p>However, even if your application update requires only a new patch expansion file, you still must 105 upload a new APK with an updated <a 106 href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code 107 versionCode}</a> in the manifest. (The 108 Developer Console does not allow you to upload an expansion file to an existing APK.)</p> 109 110 <p class="note"><strong>Note:</strong> The patch expansion file is semantically the same as the 111 main expansion file—you can use each file any way you want. The system does 112 not use the patch expansion file to perform patching for your app. You must perform patching 113 yourself or be able to distinguish between the two files.</p> 114 115 116 117 <h3 id="Filename">File name format</h3> 118 119 <p>Each expansion file you upload can be any format you choose (ZIP, PDF, MP4, etc.). You can also 120 use the <a href="{@docRoot}tools/help/jobb.html">JOBB</a> tool to encapsulate and encrypt a set 121 of resource files and subsequent patches for that set. Regardless of the file type, Google Play 122 considers them opaque binary blobs and renames the files using the following scheme:</p> 123 124 <pre class="classic no-pretty-print"> 125 [main|patch].<expansion-version>.<package-name>.obb 126 </pre> 127 128 <p>There are three components to this scheme:</p> 129 130 <dl> 131 <dt>{@code main} or {@code patch}</dt> 132 <dd>Specifies whether the file is the main or patch expansion file. There can be 133 only one main file and one patch file for each APK.</dd> 134 <dt>{@code <expansion-version>}</dt> 135 <dd>This is an integer that matches the version code of the APK with which the expansion is 136 <em>first</em> associated (it matches the application's <a 137 href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code android:versionCode}</a> 138 value). 139 <p>"First" is emphasized because although the Developer Console allows you to 140 re-use an uploaded expansion file with a new APK, the expansion file's name does not change—it 141 retains the version applied to it when you first uploaded the file.</p></dd> 142 <dt>{@code <package-name>}</dt> 143 <dd>Your application's Java-style package name.</dd> 144 </dl> 145 146 <p>For example, suppose your APK version is 314159 and your package name is com.example.app. If you 147 upload a main expansion file, the file is renamed to:</p> 148 <pre class="classic no-pretty-print">main.314159.com.example.app.obb</pre> 149 150 151 <h3 id="StorageLocation">Storage location</h3> 152 153 <p>When Google Play downloads your expansion files to a device, it saves them to the system's 154 shared storage location. To ensure proper behavior, you must not delete, move, or rename the 155 expansion files. In the event that your application must perform the download from Google Play 156 itself, you must save the files to the exact same location.</p> 157 158 <p>The specific location for your expansion files is:</p> 159 160 <pre class="classic no-pretty-print"> 161 <shared-storage>/Android/obb/<package-name>/ 162 </pre> 163 164 <ul> 165 <li>{@code <shared-storage>} is the path to the shared storage space, available from 166 {@link android.os.Environment#getExternalStorageDirectory()}.</li> 167 <li>{@code <package-name>} is your application's Java-style package name, available 168 from {@link android.content.Context#getPackageName()}.</li> 169 </ul> 170 171 <p>For each application, there are never more than two expansion files in this directory. 172 One is the main expansion file and the other is the patch expansion file (if necessary). Previous 173 versions are overwritten when you update your application with new expansion files.</p> 174 175 <p>If you must unpack the contents of your expansion files, <strong>do not</strong> delete the 176 {@code .obb} expansion files afterwards and <strong>do not</strong> save the unpacked data 177 in the same directory. You should save your unpacked files in the directory 178 specified by {@link android.content.Context#getExternalFilesDir getExternalFilesDir()}. However, 179 if possible, it's best if you use an expansion file format that allows you to read directly from 180 the file instead of requiring you to unpack the data. For example, we've provided a library 181 project called the <a href="#ZipLib">APK Expansion Zip Library</a> that reads your data directly 182 from the ZIP file.</p> 183 184 <p class="note"><strong>Note:</strong> Unlike APK files, any files saved on the shared storage can 185 be read by the user and other applications.</p> 186 187 <p class="note"><strong>Tip:</strong> If you're packaging media files into a ZIP, you can use media 188 playback calls on the files with offset and length controls (such as {@link 189 android.media.MediaPlayer#setDataSource(FileDescriptor,long,long) MediaPlayer.setDataSource()} and 190 {@link android.media.SoundPool#load(FileDescriptor,long,long,int) SoundPool.load()}) without the 191 need to unpack your ZIP. In order for this to work, you must not perform additional compression on 192 the media files when creating the ZIP packages. For example, when using the <code>zip</code> tool, 193 you should use the <code>-n</code> option to specify the file suffixes that should not be 194 compressed: <br/> 195 <code>zip -n .mp4;.ogg main_expansion media_files</code></p> 196 197 198 <h3 id="DownloadProcess">Download process</h3> 199 200 <p>Most of the time, Google Play downloads and saves your expansion files at the same time it 201 downloads the APK to the device. However, in some cases Google Play 202 cannot download the expansion files or the user might have deleted previously downloaded expansion 203 files. To handle these situations, your app must be able to download the files 204 itself when the main activity starts, using a URL provided by Google Play.</p> 205 206 <p>The download process from a high level looks like this:</p> 207 208 <ol> 209 <li>User selects to install your app from Google Play.</li> 210 <li>If Google Play is able to download the expansion files (which is the case for most 211 devices), it downloads them along with the APK. 212 <p>If Google Play is unable to download the expansion files, it downloads the 213 APK only.</p> 214 </li> 215 <li>When the user launches your application, your app must check whether the expansion files are 216 already saved on the device. 217 <ol> 218 <li>If yes, your app is ready to go.</li> 219 <li>If no, your app must download the expansion files over HTTP from Google Play. Your app 220 must send a request to the Google Play client using the Google Play's <a 221 href="{@docRoot}google/play/licensing/index.html">Application Licensing</a> service, which 222 responds with the name, file size, and URL for each expansion file. With this information, you then 223 download the files and save them to the proper <a href="#StorageLocation">storage location</a>.</li> 224 </ol> 225 </li> 226 </ol> 227 228 <p class="caution"><strong>Caution:</strong> It is critical that you include the necessary code to 229 download the expansion files from Google Play in the event that the files are not already on the 230 device when your application starts. As discussed in the following section about <a 231 href="#Downloading">Downloading the Expansion Files</a>, we've made a library available to you that 232 greatly simplifies this process and performs the download from a service with a minimal amount of 233 code from you.</p> 234 235 236 237 238 <h3 id="Checklist">Development checklist</h3> 239 240 <p>Here's a summary of the tasks you should perform to use expansion files with your 241 application:</p> 242 243 <ol> 244 <li>First determine whether your application absolutely requires more than 50MB per installation. 245 Space is precious and you should keep your total application size as small as possible. If your app 246 uses more than 50MB in order to provide multiple versions of your graphic assets for multiple screen 247 densities, consider instead publishing <a 248 href="{@docRoot}google/play/publishing/multiple-apks.html">multiple APKs</a> in which each APK 249 contains only the assets required for the screens that it targets.</li> 250 <li>Determine which application resources to separate from your APK and package them in a 251 file to use as the main expansion file. 252 <p>Normally, you should only use the second patch expansion file when performing updates to 253 the main expansion file. However, if your resources exceed the 2GB limit for the main 254 expansion file, you can use the patch file for the rest of your assets.</p> 255 </li> 256 <li>Develop your application such that it uses the resources from your expansion files in the 257 device's <a href="#StorageLocation">shared storage location</a>. 258 <p>Remember that you must not delete, move, or rename the expansion files.</p> 259 <p>If your application doesn't demand a specific format, we suggest you create ZIP files for 260 your expansion files, then read them using the <a href="#ZipLib">APK Expansion Zip 261 Library</a>.</p> 262 </li> 263 <li>Add logic to your application's main activity that checks whether the expansion files 264 are on the device upon start-up. If the files are not on the device, use Google Play's <a 265 href="{@docRoot}google/play/licensing/index.html">Application Licensing</a> service to request URLs 266 for the expansion files, then download and save them. 267 <p>To greatly reduce the amount of code you must write and ensure a good user experience 268 during the download, we recommend you use the <a href="#AboutLibraries">Downloader 269 Library</a> to implement your download behavior.</p> 270 <p>If you build your own download service instead of using the library, be aware that you 271 must not change the name of the expansion files and must save them to the proper 272 <a href="#StorageLocation">storage location</a>.</p></li> 273 </ol> 274 275 <p>Once you've finished your application development, follow the guide to <a href="#Testing">Testing 276 Your Expansion Files</a>.</p> 277 278 279 280 281 282 283 <h2 id="Rules">Rules and Limitations</h2> 284 285 <p>Adding APK expansion files is a feature available when you upload your application using the 286 Developer Console. When uploading your application for the first time or updating an 287 application that uses expansion files, you must be aware of the following rules and limitations:</p> 288 289 <ol type="I"> 290 <li>Each expansion file can be no more than 2GB.</li> 291 <li>In order to download your expansion files from Google Play, <strong>the user must have 292 acquired your application from Google Play</strong>. Google Play will not 293 provide the URLs for your expansion files if the application was installed by other means.</li> 294 <li>When performing the download from within your application, the URL that Google Play 295 provides for each file is unique for every download and each one expires shortly after it is given 296 to your application.</li> 297 <li>If you update your application with a new APK or upload <a 298 href="{@docRoot}google/play/publishing/multiple-apks.html">multiple APKs</a> for the same 299 application, you can select expansion files that you've uploaded for a previous APK. <strong>The 300 expansion file's name does not change</strong>—it retains the version received by the APK to 301 which the file was originally associated.</li> 302 <li>If you use expansion files in combination with <a 303 href="{@docRoot}google/play/publishing/multiple-apks.html">multiple APKs</a> in order to 304 provide different expansion files for different devices, you still must upload separate APKs 305 for each device in order to provide a unique <a 306 href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code versionCode}</a> 307 value and declare different <a href="{@docRoot}google/play/filters.html">filters</a> for 308 each APK.</li> 309 <li>You cannot issue an update to your application by changing the expansion files 310 alone—<strong>you must upload a new APK</strong> to update your app. If your changes only 311 concern the assets in your expansion files, you can update your APK simply by changing the <a 312 href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code versionCode}</a> (and 313 perhaps also the <a href="{@docRoot}guide/topics/manifest/manifest-element.html#vname">{@code 314 versionName}</a>).</p></li> 315 <li><strong>Do not save other data into your <code>obb/</code> 316 directory</strong>. If you must unpack some data, save it into the location specified by {@link 317 android.content.Context#getExternalFilesDir getExternalFilesDir()}.</li> 318 <li><strong>Do not delete or rename the {@code .obb} expansion file</strong> (unless you're 319 performing an update). Doing so will cause Google Play (or your app itself) to repeatedly 320 download the expansion file.</li> 321 <li>When updating an expansion file manually, you must delete the previous expansion file.</li> 322 </ol> 323 324 325 326 327 328 329 330 331 332 <h2 id="Downloading">Downloading the Expansion Files</h2> 333 334 <p>In most cases, Google Play downloads and saves your expansion files to the device at the same 335 time it installs or updates the APK. This way, the expansion files are available when your 336 application launches for the first time. However, in some cases your app must download the 337 expansion files itself by requesting them from a URL provided to you in a response 338 from Google Play's <a 339 href="{@docRoot}google/play/licensing/index.html">Application Licensing</a> service.</p> 340 341 <p>The basic logic you need to download your expansion files is the following:</p> 342 343 <ol> 344 <li>When your application starts, look for the expansion files on the <a 345 href="#StorageLocation">shared storage location</a> (in the 346 <code>Android/obb/<package-name>/</code> directory). 347 <ol type="a"> 348 <li>If the expansion files are there, you're all set and your application can continue.</li> 349 <li>If the expansion files are <em>not</em> there: 350 <ol> 351 <li>Perform a request using Google Play's <a 352 href="{@docRoot}google/play/licensing/index.html">Application Licensing</a> to get your 353 app's expansion file names, sizes, and URLs.</li> 354 <li>Use the URLs provided by Google Play to download the expansion files and save 355 the expansion files. You <strong>must</strong> save the files to the <a 356 href="#StorageLocation">shared storage location</a> 357 (<code>Android/obb/<package-name>/</code>) and use the exact file name provided 358 by Google Play's response. 359 <p class="note"><strong>Note:</strong> The URL that Google Play provides for your 360 expansion files is unique for every download and each one expires shortly after it is given to 361 your application.</p> 362 </li> 363 </ol> 364 </li> 365 </ol> 366 </li> 367 </ol> 368 369 370 <p>If your application is free (not a paid app), then you probably haven't used the <a 371 href="{@docRoot}google/play/licensing/index.html">Application Licensing</a> service. It's primarily 372 designed for you to enforce 373 licensing policies for your application and ensure that the user has the right to 374 use your app (he or she rightfully paid for it on Google Play). In order to facilitate the 375 expansion file functionality, the licensing service has been enhanced to provide a response 376 to your application that includes the URL of your application's expansion files that are hosted 377 on Google Play. So, even if your application is free for users, you need to include the 378 License Verification Library (LVL) to use APK expansion files. Of course, if your application 379 is free, you don't need to enforce license verification—you simply need the 380 library to perform the request that returns the URL of your expansion files.</p> 381 382 <p class="note"><strong>Note:</strong> Whether your application is free or not, Google Play 383 returns the expansion file URLs only if the user acquired your application from Google Play.</p> 384 385 <p>In addition to the LVL, you need a set of code that downloads the expansion files 386 over an HTTP connection and saves them to the proper location on the device's shared storage. 387 As you build this procedure into your application, there are several issues you should take into 388 consideration:</p> 389 390 <ul> 391 <li>The device might not have enough space for the expansion files, so you should check 392 before beginning the download and warn the user if there's not enough space.</li> 393 <li>File downloads should occur in a background service in order to avoid blocking the user 394 interaction and allow the user to leave your app while the download completes.</li> 395 <li>A variety of errors might occur during the request and download that you must 396 gracefully handle.</li> 397 <li>Network connectivity can change during the download, so you should handle such changes and 398 if interrupted, resume the download when possible.</li> 399 <li>While the download occurs in the background, you should provide a notification that 400 indicates the download progress, notifies the user when it's done, and takes the user back to 401 your application when selected.</li> 402 </ul> 403 404 405 <p>To simplify this work for you, we've built the <a href="#AboutLibraries">Downloader Library</a>, 406 which requests the expansion file URLs through the licensing service, downloads the expansion files, 407 performs all of the tasks listed above, and even allows your activity to pause and resume the 408 download. By adding the Downloader Library and a few code hooks to your application, almost all the 409 work to download the expansion files is already coded for you. As such, in order to provide the best 410 user experience with minimal effort on your behalf, we recommend you use the Downloader Library to 411 download your expansion files. The information in the following sections explain how to integrate 412 the library into your application.</p> 413 414 <p>If you'd rather develop your own solution to download the expansion files using the Google 415 Play URLs, you must follow the <a href="{@docRoot}google/play/licensing/index.html">Application 416 Licensing</a> documentation to perform a license request, then retrieve the expansion file names, 417 sizes, and URLs from the response extras. You should use the <a href="#ExpansionPolicy">{@code 418 APKExpansionPolicy}</a> class (included in the License Verification Library) as your licensing 419 policy, which captures the expansion file names, sizes, and URLs from the licensing service..</p> 420 421 422 423 <h3 id="AboutLibraries">About the Downloader Library</h3> 424 425 <p>To use APK expansion files with your application and provide the best user experience with 426 minimal effort on your behalf, we recommend you use the Downloader Library that's included in the 427 Google Play APK Expansion Library package. This library downloads your expansion files in a 428 background service, shows a user notification with the download status, handles network 429 connectivity loss, resumes the download when possible, and more.</p> 430 431 <p>To implement expansion file downloads using the Downloader Library, all you need to do is:</p> 432 433 <ul> 434 <li>Extend a special {@link android.app.Service} subclass and {@link 435 android.content.BroadcastReceiver} subclass that each require just a few 436 lines of code from you.</li> 437 <li>Add some logic to your main activity that checks whether the expansion files have 438 already been downloaded and, if not, invokes the download process and displays a 439 progress UI.</li> 440 <li>Implement a callback interface with a few methods in your main activity that 441 receives updates about the download progress.</li> 442 </ul> 443 444 <p>The following sections explain how to set up your app using the Downloader Library.</p> 445 446 447 <h3 id="Preparing">Preparing to use the Downloader Library</h3> 448 449 <p>To use the Downloader Library, you need to 450 download two packages from the SDK Manager and add the appropriate libraries to your 451 application.</p> 452 453 <p>First, open the <a href="{@docRoot}sdk/exploring.html">Android SDK Manager</a>, expand 454 <em>Extras</em> and download:</p> 455 <ul> 456 <li><em>Google Play Licensing Library package</em></li> 457 <li><em>Google Play APK Expansion Library package</em></li> 458 </ul> 459 460 <p>If you're using Eclipse, create a project for each library and add it to your app:</p> 461 <ol> 462 <li>Create a new Library Project for the License Verification Library and Downloader 463 Library. For each library: 464 <ol> 465 <li>Begin a new Android project.</li> 466 <li>Select <strong>Create project from existing 467 source</strong> and choose the library from the {@code <sdk>/extras/google/} directory 468 ({@code market_licensing/} for the License Verification Library or {@code 469 market_apk_expansion/downloader_library/} for the Downloader Library).</li> 470 <li>Specify a <em>Project Name</em> such as "Google Play License Library" and "Google Play 471 Downloader 472 Library"</li> 473 <li>Click <strong>Finish</strong>.</li> 474 </ol> 475 <p class="note"><strong>Note:</strong> The Downloader Library depends on the License 476 Verification Library. Be sure to add the License 477 Verification Library to the Downloader Library's project properties (same process as 478 steps 2 and 3 below).</p> 479 </li> 480 <li>Right-click the Android project in which you want to use APK expansion files and 481 select <strong>Properties</strong>.</li> 482 <li>In the <em>Library</em> panel, click <strong>Add</strong> to select and add each of the 483 libraries to your application.</li> 484 </ol> 485 486 <p>Or, from a command line, update your project to include the libraries:</p> 487 <ol> 488 <li>Change directories to the <code><sdk>/tools/</code> directory.</li> 489 <li>Execute <code>android update project</code> with the {@code --library} option to add both the 490 LVL and the Downloader Library to your project. For example: 491 <pre class="no-pretty-print"> 492 android update project --path ~/Android/MyApp \ 493 --library ~/android_sdk/extras/google/market_licensing \ 494 --library ~/android_sdk/extras/google/market_apk_expansion/downloader_library 495 </pre> 496 </li> 497 </ol> 498 499 <p>With both the License Verification Library and Downloader Library added to your 500 application, you'll be able to quickly integrate the ability to download expansion files from 501 Google Play. The format that you choose for the expansion files and how you read them 502 from the shared storage is a separate implementation that you should consider based on your 503 application needs.</p> 504 505 <p class="note"><strong>Tip:</strong> The Apk Expansion package includes a sample 506 application 507 that shows how to use the Downloader Library in an app. The sample uses a third library 508 available in the Apk Expansion package called the APK Expansion Zip Library. If 509 you plan on 510 using ZIP files for your expansion files, we suggest you also add the APK Expansion Zip Library to 511 your application. For more information, see the section below 512 about <a href="#ZipLib">Using the APK Expansion Zip Library</a>.</p> 513 514 515 516 <h3 id="Permissions">Declaring user permissions</h3> 517 518 <p>In order to download the expansion files, the Downloader Library 519 requires several permissions that you must declare in your application's manifest file. They 520 are:</p> 521 522 <pre> 523 <manifest ...> 524 <!-- Required to access Google Play Licensing --> 525 <uses-permission android:name="com.android.vending.CHECK_LICENSE" /> 526 527 <!-- Required to download files from Google Play --> 528 <uses-permission android:name="android.permission.INTERNET" /> 529 530 <!-- Required to keep CPU alive while downloading files 531 (NOT to keep screen awake) --> 532 <uses-permission android:name="android.permission.WAKE_LOCK" /> 533 534 <!-- Required to poll the state of the network connection 535 and respond to changes --> 536 <uses-permission 537 android:name="android.permission.ACCESS_NETWORK_STATE" /> 538 539 <!-- Required to check whether Wi-Fi is enabled --> 540 <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/> 541 542 <!-- Required to read and write the expansion files on shared storage --> 543 <uses-permission 544 android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> 545 ... 546 </manifest> 547 </pre> 548 549 <p class="note"><strong>Note:</strong> By default, the Downloader Library requires API 550 level 4, but the APK Expansion Zip Library requires API level 5.</p> 551 552 553 <h3 id="DownloaderService">Implementing the downloader service</h3> 554 555 <p>In order to perform downloads in the background, the Downloader Library provides its 556 own {@link android.app.Service} subclass called {@code DownloaderService} that you should extend. In 557 addition to downloading the expansion files for you, the {@code DownloaderService} also:</p> 558 559 <ul> 560 <li>Registers a {@link android.content.BroadcastReceiver} that listens for changes to the 561 device's network connectivity (the {@link android.net.ConnectivityManager#CONNECTIVITY_ACTION} 562 broadcast) in order to pause the download when necessary (such as due to connectivity loss) and 563 resume the download when possible (connectivity is acquired).</li> 564 <li>Schedules an {@link android.app.AlarmManager#RTC_WAKEUP} alarm to retry the download for 565 cases in which the service gets killed.</li> 566 <li>Builds a custom {@link android.app.Notification} that displays the download progress and 567 any errors or state changes.</li> 568 <li>Allows your application to manually pause and resume the download.</li> 569 <li>Verifies that the shared storage is mounted and available, that the files don't already exist, 570 and that there is enough space, all before downloading the expansion files. Then notifies the user 571 if any of these are not true.</li> 572 </ul> 573 574 <p>All you need to do is create a class in your application that extends the {@code 575 DownloaderService} class and override three methods to provide specific application details:</p> 576 577 <dl> 578 <dt>{@code getPublicKey()}</dt> 579 <dd>This must return a string that is the Base64-encoded RSA public key for your publisher 580 account, available from the profile page on the Developer Console (see <a 581 href="{@docRoot}google/play/licensing/setting-up.html">Setting Up for Licensing</a>).</dd> 582 <dt>{@code getSALT()}</dt> 583 <dd>This must return an array of random bytes that the licensing {@code Policy} uses to 584 create an <a 585 href="{@docRoot}google/play/licensing/adding-licensing.html#impl-Obfuscator">{@code 586 Obfuscator}</a>. The salt ensures that your obfuscated {@link android.content.SharedPreferences} 587 file in which your licensing data is saved will be unique and non-discoverable.</dd> 588 <dt>{@code getAlarmReceiverClassName()}</dt> 589 <dd>This must return the class name of the {@link android.content.BroadcastReceiver} in 590 your application that should receive the alarm indicating that the download should be 591 restarted (which might happen if the downloader service unexpectedly stops).</dd> 592 </dl> 593 594 <p>For example, here's a complete implementation of {@code DownloaderService}:</p> 595 596 <pre> 597 public class SampleDownloaderService extends DownloaderService { 598 // You must use the public key belonging to your publisher account 599 public static final String BASE64_PUBLIC_KEY = "YourLVLKey"; 600 // You should also modify this salt 601 public static final byte[] SALT = new byte[] { 1, 42, -12, -1, 54, 98, 602 -100, -12, 43, 2, -8, -4, 9, 5, -106, -107, -33, 45, -1, 84 603 }; 604 605 @Override 606 public String getPublicKey() { 607 return BASE64_PUBLIC_KEY; 608 } 609 610 @Override 611 public byte[] getSALT() { 612 return SALT; 613 } 614 615 @Override 616 public String getAlarmReceiverClassName() { 617 return SampleAlarmReceiver.class.getName(); 618 } 619 } 620 </pre> 621 622 <p class="caution"><strong>Notice:</strong> You must update the {@code BASE64_PUBLIC_KEY} value 623 to be the public key belonging to your publisher account. You can find the key in the Developer 624 Console under your profile information. This is necessary even when testing 625 your downloads.</p> 626 627 <p>Remember to declare the service in your manifest file:</p> 628 <pre> 629 <application ...> 630 <service android:name=".SampleDownloaderService" /> 631 ... 632 </application> 633 </pre> 634 635 636 637 <h3 id="AlarmReceiver">Implementing the alarm receiver</h3> 638 639 <p>In order to monitor the progress of the file downloads and restart the download if necessary, the 640 {@code DownloaderService} schedules an {@link android.app.AlarmManager#RTC_WAKEUP} alarm that 641 delivers an {@link android.content.Intent} to a {@link android.content.BroadcastReceiver} in your 642 application. You must define the {@link android.content.BroadcastReceiver} to call an API 643 from the Downloader Library that checks the status of the download and restarts 644 it if necessary.</p> 645 646 <p>You simply need to override the {@link android.content.BroadcastReceiver#onReceive 647 onReceive()} method to call {@code 648 DownloaderClientMarshaller.startDownloadServiceIfRequired()}.</p> 649 650 <p>For example:</p> 651 652 <pre> 653 public class SampleAlarmReceiver extends BroadcastReceiver { 654 @Override 655 public void onReceive(Context context, Intent intent) { 656 try { 657 DownloaderClientMarshaller.startDownloadServiceIfRequired(context, 658 intent, SampleDownloaderService.class); 659 } catch (NameNotFoundException e) { 660 e.printStackTrace(); 661 } 662 } 663 } 664 </pre> 665 666 <p>Notice that this is the class for which you must return the name 667 in your service's {@code getAlarmReceiverClassName()} method (see the previous section).</p> 668 669 <p>Remember to declare the receiver in your manifest file:</p> 670 <pre> 671 <application ...> 672 <receiver android:name=".SampleAlarmReceiver" /> 673 ... 674 </application> 675 </pre> 676 677 678 679 <h3 id="Download">Starting the download</h3> 680 681 <p>The main activity in your application (the one started by your launcher icon) is 682 responsible for verifying whether the expansion files are already on the device and initiating 683 the download if they are not.</p> 684 685 <p>Starting the download using the Downloader Library requires the following 686 procedures:</p> 687 688 <ol> 689 <li>Check whether the files have been downloaded. 690 <p>The Downloader Library includes some APIs in the {@code Helper} class to 691 help with this process:</p> 692 <ul> 693 <li>{@code getExpansionAPKFileName(Context, c, boolean mainFile, int 694 versionCode)}</li> 695 <li>{@code doesFileExist(Context c, String fileName, long fileSize)}</li> 696 </ul> 697 <p>For example, the sample app provided in the Apk Expansion package calls the 698 following method in the activity's {@link android.app.Activity#onCreate onCreate()} method to check 699 whether the expansion files already exist on the device:</p> 700 701 <pre> 702 boolean expansionFilesDelivered() { 703 for (XAPKFile xf : xAPKS) { 704 String fileName = Helpers.getExpansionAPKFileName(this, xf.mIsBase, 705 xf.mFileVersion); 706 if (!Helpers.doesFileExist(this, fileName, xf.mFileSize, false)) 707 return false; 708 } 709 return true; 710 } 711 </pre> 712 713 <p>In this case, each {@code XAPKFile} object holds the version number and file size of a known 714 expansion file and a boolean as to whether it's the main expansion file. (See the sample 715 application's {@code SampleDownloaderActivity} class for details.)</p> 716 <p>If this method returns false, then the application must begin the download.</p> 717 </li> 718 <li>Start the download by calling the static method {@code 719 DownloaderClientMarshaller.startDownloadServiceIfRequired(Context c, PendingIntent 720 notificationClient, Class<?> serviceClass)}. 721 <p>The method takes the following parameters:</p> 722 <ul> 723 <li><code>context</code>: Your application's {@link android.content.Context}.</li> 724 <li><code>notificationClient</code>: A {@link android.app.PendingIntent} to start your main 725 activity. This is used in the {@link android.app.Notification} that the {@code DownloaderService} 726 creates to show the download progress. When the user selects the notification, the system 727 invokes the {@link android.app.PendingIntent} you supply here and should open the activity 728 that shows the download progress (usually the same activity that started the download).</li> 729 <li><code>serviceClass</code>: The {@link java.lang.Class} object for your implementation of 730 {@code DownloaderService}, required to start the service and begin the download if necessary.</li> 731 </ul> 732 <p>The method returns an integer that indicates 733 whether or not the download is required. Possible values are:</p> 734 <ul> 735 <li>{@code NO_DOWNLOAD_REQUIRED}: Returned if the files already 736 exist or a download is already in progress.</li> 737 <li>{@code LVL_CHECK_REQUIRED}: Returned if a license verification is 738 required in order to acquire the expansion file URLs.</li> 739 <li>{@code DOWNLOAD_REQUIRED}: Returned if the expansion file URLs are already known, 740 but have not been downloaded.</li> 741 </ul> 742 <p>The behavior for {@code LVL_CHECK_REQUIRED} and {@code DOWNLOAD_REQUIRED} are essentially the 743 same and you normally don't need to be concerned about them. In your main activity that calls {@code 744 startDownloadServiceIfRequired()}, you can simply check whether or not the response is {@code 745 NO_DOWNLOAD_REQUIRED}. If the response is anything <em>other than</em> {@code NO_DOWNLOAD_REQUIRED}, 746 the Downloader Library begins the download and you should update your activity UI to 747 display the download progress (see the next step). If the response <em>is</em> {@code 748 NO_DOWNLOAD_REQUIRED}, then the files are available and your application can start.</p> 749 <p>For example:</p> 750 751 <pre> 752 @Override 753 public void onCreate(Bundle savedInstanceState) { 754 // Check if expansion files are available before going any further 755 if (!expansionFilesDelivered()) { 756 // Build an Intent to start this activity from the Notification 757 Intent notifierIntent = new Intent(this, MainActivity.getClass()); 758 notifierIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | 759 Intent.FLAG_ACTIVITY_CLEAR_TOP); 760 ... 761 PendingIntent pendingIntent = PendingIntent.getActivity(this, 0, 762 notifierIntent, PendingIntent.FLAG_UPDATE_CURRENT); 763 764 // Start the download service (if required) 765 int startResult = 766 DownloaderClientMarshaller.startDownloadServiceIfRequired(this, 767 pendingIntent, SampleDownloaderService.class); 768 // If download has started, initialize this activity to show 769 // download progress 770 if (startResult != DownloaderClientMarshaller.NO_DOWNLOAD_REQUIRED) { 771 // This is where you do set up to display the download 772 // progress (next step) 773 ... 774 return; 775 } // If the download wasn't necessary, fall through to start the app 776 } 777 startApp(); // Expansion files are available, start the app 778 } 779 </pre> 780 781 </li> 782 <li>When the {@code startDownloadServiceIfRequired()} method returns anything <em>other 783 than</em> {@code NO_DOWNLOAD_REQUIRED}, create an instance of {@code IStub} by 784 calling {@code DownloaderClientMarshaller.CreateStub(IDownloaderClient client, Class<?> 785 downloaderService)}. The {@code IStub} provides a binding between your activity to the downloader 786 service such that your activity receives callbacks about the download progress. 787 <p>In order to instantiate your {@code IStub} by calling {@code CreateStub()}, you must pass it 788 an implementation of the {@code IDownloaderClient} interface and your {@code DownloaderService} 789 implementation. The next section about <a href="#Progress">Receiving download progress</a> discusses 790 the {@code IDownloaderClient} interface, which you should usually implement in your {@link 791 android.app.Activity} class so you can update the activity UI when the download state changes.</p> 792 <p>We recommend that you call {@code 793 CreateStub()} to instantiate your {@code IStub} during your activity's {@link 794 android.app.Activity#onCreate onCreate()} method, after {@code startDownloadServiceIfRequired()} 795 starts the download. </p> 796 <p>For example, in the previous code sample for {@link android.app.Activity#onCreate 797 onCreate()}, you can respond to the {@code startDownloadServiceIfRequired()} result like this:</p> 798 799 <pre> 800 // Start the download service (if required) 801 int startResult = 802 DownloaderClientMarshaller.startDownloadServiceIfRequired(this, 803 pendingIntent, SampleDownloaderService.class); 804 // If download has started, initialize activity to show progress 805 if (startResult != DownloaderClientMarshaller.NO_DOWNLOAD_REQUIRED) { 806 // Instantiate a member instance of IStub 807 mDownloaderClientStub = DownloaderClientMarshaller.CreateStub(this, 808 SampleDownloaderService.class); 809 // Inflate layout that shows download progress 810 setContentView(R.layout.downloader_ui); 811 return; 812 } 813 </pre> 814 815 <p>After the {@link android.app.Activity#onCreate onCreate()} method returns, your activity 816 receives a call to {@link android.app.Activity#onResume onResume()}, which is where you should then 817 call {@code connect()} on the {@code IStub}, passing it your application's {@link 818 android.content.Context}. Conversely, you should call 819 {@code disconnect()} in your activity's {@link android.app.Activity#onStop onStop()} callback.</p> 820 <pre> 821 @Override 822 protected void onResume() { 823 if (null != mDownloaderClientStub) { 824 mDownloaderClientStub.connect(this); 825 } 826 super.onResume(); 827 } 828 829 @Override 830 protected void onStop() { 831 if (null != mDownloaderClientStub) { 832 mDownloaderClientStub.disconnect(this); 833 } 834 super.onStop(); 835 } 836 </pre> 837 <p>Calling {@code connect()} on the {@code IStub} binds your activity to the {@code 838 DownloaderService} such that your activity receives callbacks regarding changes to the download 839 state through the {@code IDownloaderClient} interface.</p> 840 </li> 841 </ol> 842 843 844 845 <h3 id="Progress">Receiving download progress</h3> 846 847 <p>To receive updates regarding the download progress and to interact with the {@code 848 DownloaderService}, you must implement the Downloader Library's {@code IDownloaderClient} interface. 849 Usually, the activity you use to start the download should implement this interface in order to 850 display the download progress and send requests to the service.</p> 851 852 <p>The required interface methods for {@code IDownloaderClient} are:</p> 853 854 <dl> 855 <dt>{@code onServiceConnected(Messenger m)}</dt> 856 <dd>After you instantiate the {@code IStub} in your activity, you'll receive a call to this 857 method, which passes a {@link android.os.Messenger} object that's connected with your instance 858 of {@code DownloaderService}. To send requests to the service, such as to pause and resume 859 downloads, you must call {@code DownloaderServiceMarshaller.CreateProxy()} to receive the {@code 860 IDownloaderService} interface connected to the service. 861 <p>A recommended implementation looks like this:</p> 862 <pre> 863 private IDownloaderService mRemoteService; 864 ... 865 866 @Override 867 public void onServiceConnected(Messenger m) { 868 mRemoteService = DownloaderServiceMarshaller.CreateProxy(m); 869 mRemoteService.onClientUpdated(mDownloaderClientStub.getMessenger()); 870 } 871 </pre> 872 <p>With the {@code IDownloaderService} object initialized, you can send commands to the 873 downloader service, such as to pause and resume the download ({@code requestPauseDownload()} 874 and {@code requestContinueDownload()}).</p> 875 </dd> 876 <dt>{@code onDownloadStateChanged(int newState)}</dt> 877 <dd>The download service calls this when a change in download state occurs, such as the 878 download begins or completes. 879 <p>The <code>newState</code> value will be one of several possible values specified in 880 by one of the {@code IDownloaderClient} class's {@code STATE_*} constants.</p> 881 <p>To provide a useful message to your users, you can request a corresponding string 882 for each state by calling {@code Helpers.getDownloaderStringResourceIDFromState()}. This 883 returns the resource ID for one of the strings bundled with the Downloader 884 Library. For example, the string "Download paused because you are roaming" corresponds to {@code 885 STATE_PAUSED_ROAMING}.</p></dd> 886 <dt>{@code onDownloadProgress(DownloadProgressInfo progress)}</dt> 887 <dd>The download service calls this to deliver a {@code DownloadProgressInfo} object, 888 which describes various information about the download progress, including estimated time remaining, 889 current speed, overall progress, and total so you can update the download progress UI.</dd> 890 </dl> 891 <p class="note"><strong>Tip:</strong> For examples of these callbacks that update the download 892 progress UI, see the {@code SampleDownloaderActivity} in the sample app provided with the 893 Apk Expansion package.</p> 894 895 <p>Some public methods for the {@code IDownloaderService} interface you might find useful are:</p> 896 897 <dl> 898 <dt>{@code requestPauseDownload()}</dt> 899 <dd>Pauses the download.</dd> 900 <dt>{@code requestContinueDownload()}</dt> 901 <dd>Resumes a paused download.</dd> 902 <dt>{@code setDownloadFlags(int flags)}</dt> 903 <dd>Sets user preferences for network types on which its OK to download the files. The 904 current implementation supports one flag, {@code FLAGS_DOWNLOAD_OVER_CELLULAR}, but you can add 905 others. By default, this flag is <em>not</em> enabled, so the user must be on Wi-Fi to download 906 expansion files. You might want to provide a user preference to enable downloads over 907 the cellular network. In which case, you can call: 908 <pre> 909 mRemoteService 910 .setDownloadFlags(IDownloaderService.FLAGS_DOWNLOAD_OVER_CELLULAR); 911 </pre> 912 </dd> 913 </dl> 914 915 916 917 918 <h2 id="ExpansionPolicy">Using APKExpansionPolicy</h2> 919 920 <p>If you decide to build your own downloader service instead of using the Google Play 921 <a href="#AboutLibraries">Downloader Library</a>, you should still use the {@code 922 APKExpansionPolicy} that's provided in the License Verification Library. The {@code 923 APKExpansionPolicy} class is nearly identical to {@code ServerManagedPolicy} (available in the 924 Google Play License Verification Library) but includes additional handling for the APK expansion 925 file response extras.</p> 926 927 <p class="note"><strong>Note:</strong> If you <em>do use</em> the <a 928 href="#AboutLibraries">Downloader Library</a> as discussed in the previous section, the 929 library performs all interaction with the {@code APKExpansionPolicy} so you don't have to use 930 this class directly.</p> 931 932 <p>The class includes methods to help you get the necessary information about the available 933 expansion files:</p> 934 935 <ul> 936 <li>{@code getExpansionURLCount()}</li> 937 <li>{@code getExpansionURL(int index)}</li> 938 <li>{@code getExpansionFileName(int index)}</li> 939 <li>{@code getExpansionFileSize(int index)}</li> 940 </ul> 941 942 <p>For more information about how to use the {@code APKExpansionPolicy} when you're <em>not</em> 943 using the <a 944 href="#AboutLibraries">Downloader Library</a>, see the documentation for <a 945 href="{@docRoot}google/play/licensing/adding-licensing.html">Adding Licensing to Your App</a>, 946 which explains how to implement a license policy such as this one.</p> 947 948 949 950 951 952 953 954 <h2 id="ReadingTheFile">Reading the Expansion File</h2> 955 956 <p>Once your APK expansion files are saved on the device, how you read your files 957 depends on the type of file you've used. As discussed in the <a href="#Overview">overview</a>, your 958 expansion files can be any kind of file you 959 want, but are renamed using a particular <a href="#Filename">file name format</a> and are saved to 960 {@code <shared-storage>/Android/obb/<package-name>/}.</p> 961 962 <p>Regardless of how you read your files, you should always first check that the external 963 storage is available for reading. There's a chance that the user has the storage mounted to a 964 computer over USB or has actually removed the SD card.</p> 965 966 <p class="note"><strong>Note:</strong> When your application starts, you should always check whether 967 the external storage space is available and readable by calling {@link 968 android.os.Environment#getExternalStorageState()}. This returns one of several possible strings 969 that represent the state of the external storage. In order for it to be readable by your 970 application, the return value must be {@link android.os.Environment#MEDIA_MOUNTED}.</p> 971 972 973 <h3 id="GettingFilenames">Getting the file names</h3> 974 975 <p>As described in the <a href="#Overview">overview</a>, your APK expansion files are saved 976 using a specific file name format:</p> 977 978 <pre class="classic no-pretty-print"> 979 [main|patch].<expansion-version>.<package-name>.obb 980 </pre> 981 982 <p>To get the location and names of your expansion files, you should use the 983 {@link android.os.Environment#getExternalStorageDirectory()} and {@link 984 android.content.Context#getPackageName()} methods to construct the path to your files.</p> 985 986 <p>Here's a method you can use in your application to get an array containing the complete path 987 to both your expansion files:</p> 988 989 <pre> 990 // The shared path to all app expansion files 991 private final static String EXP_PATH = "/Android/obb/"; 992 993 static String[] getAPKExpansionFiles(Context ctx, int mainVersion, 994 int patchVersion) { 995 String packageName = ctx.getPackageName(); 996 Vector<String> ret = new Vector<String>(); 997 if (Environment.getExternalStorageState() 998 .equals(Environment.MEDIA_MOUNTED)) { 999 // Build the full path to the app's expansion files 1000 File root = Environment.getExternalStorageDirectory(); 1001 File expPath = new File(root.toString() + EXP_PATH + packageName); 1002 1003 // Check that expansion file path exists 1004 if (expPath.exists()) { 1005 if ( mainVersion > 0 ) { 1006 String strMainPath = expPath + File.separator + "main." + 1007 mainVersion + "." + packageName + ".obb"; 1008 File main = new File(strMainPath); 1009 if ( main.isFile() ) { 1010 ret.add(strMainPath); 1011 } 1012 } 1013 if ( patchVersion > 0 ) { 1014 String strPatchPath = expPath + File.separator + "patch." + 1015 mainVersion + "." + packageName + ".obb"; 1016 File main = new File(strPatchPath); 1017 if ( main.isFile() ) { 1018 ret.add(strPatchPath); 1019 } 1020 } 1021 } 1022 } 1023 String[] retArray = new String[ret.size()]; 1024 ret.toArray(retArray); 1025 return retArray; 1026 } 1027 </pre> 1028 1029 <p>You can call this method by passing it your application {@link android.content.Context} 1030 and the desired expansion file's version.</p> 1031 1032 <p>There are many ways you could determine the expansion file version number. One simple way is to 1033 save the version in a {@link android.content.SharedPreferences} file when the download begins, by 1034 querying the expansion file name with the {@code APKExpansionPolicy} class's {@code 1035 getExpansionFileName(int index)} method. You can then get the version code by reading the {@link 1036 android.content.SharedPreferences} file when you want to access the expansion 1037 file.</p> 1038 1039 <p>For more information about reading from the shared storage, see the <a 1040 href="{@docRoot}guide/topics/data/data-storage.html#filesExternal">Data Storage</a> 1041 documentation.</p> 1042 1043 1044 1045 <h3 id="ZipLib">Using the APK Expansion Zip Library</h3> 1046 1047 <div class="sidebox-wrapper"> 1048 <div class="sidebox"> 1049 <h3>Reading media files from a ZIP</h3> 1050 <p>If you're using your expansion files to store media files, a ZIP file still allows you to 1051 use Android media playback calls that provide offset and length controls (such as {@link 1052 android.media.MediaPlayer#setDataSource(FileDescriptor,long,long) MediaPlayer.setDataSource()} and 1053 {@link android.media.SoundPool#load(FileDescriptor,long,long,int) SoundPool.load()}). In order for 1054 this to work, you must not perform additional compression on the media files when creating the ZIP 1055 packages. For example, when using the <code>zip</code> tool, you should use the <code>-n</code> 1056 option to specify the file suffixes that should not be compressed:</p> 1057 <p><code>zip -n .mp4;.ogg main_expansion media_files</code></p> 1058 </div> 1059 </div> 1060 1061 <p>The Google Market Apk Expansion package includes a library called the APK 1062 Expansion Zip Library (located in {@code 1063 <sdk>/extras/google/google_market_apk_expansion/zip_file/}). This is an optional library that 1064 helps you read your expansion 1065 files when they're saved as ZIP files. Using this library allows you to easily read resources from 1066 your ZIP expansion files as a virtual file system.</p> 1067 1068 <p>The APK Expansion Zip Library includes the following classes and APIs:</p> 1069 1070 <dl> 1071 <dt>{@code APKExpansionSupport}</dt> 1072 <dd>Provides some methods to access expansion file names and ZIP files: 1073 1074 <dl style="margin-top:1em"> 1075 <dt>{@code getAPKExpansionFiles()}</dt> 1076 <dd>The same method shown above that returns the complete file path to both expansion 1077 files.</dd> 1078 <dt>{@code getAPKExpansionZipFile(Context ctx, int mainVersion, int 1079 patchVersion)}</dt> 1080 <dd>Returns a {@code ZipResourceFile} representing the sum of both the main file and 1081 patch file. That is, if you specify both the <code>mainVersion</code> and the 1082 <code>patchVersion</code>, this returns a {@code ZipResourceFile} that provides read access to 1083 all the data, with the patch file's data merged on top of the main file.</dd> 1084 </dl> 1085 </dd> 1086 1087 <dt>{@code ZipResourceFile}</dt> 1088 <dd>Represents a ZIP file on the shared storage and performs all the work to provide a virtual 1089 file system based on your ZIP files. You can get an instance using {@code 1090 APKExpansionSupport.getAPKExpansionZipFile()} or with the {@code ZipResourceFile} by passing it the 1091 path to your expansion file. This class includes a variety of useful methods, but you generally 1092 don't need to access most of them. A couple of important methods are: 1093 1094 <dl style="margin-top:1em"> 1095 <dt>{@code getInputStream(String assetPath)}</dt> 1096 <dd>Provides an {@link java.io.InputStream} to read a file within the ZIP file. The 1097 <code>assetPath</code> must be the path to the desired file, relative to 1098 the root of the ZIP file contents.</dd> 1099 <dt>{@code getAssetFileDescriptor(String assetPath)}</dt> 1100 <dd>Provides an {@link android.content.res.AssetFileDescriptor} for a file within the 1101 ZIP file. The <code>assetPath</code> must be the path to the desired file, relative to 1102 the root of the ZIP file contents. This is useful for certain Android APIs that require an {@link 1103 android.content.res.AssetFileDescriptor}, such as some {@link android.media.MediaPlayer} APIs.</dd> 1104 </dl> 1105 </dd> 1106 1107 <dt>{@code APEZProvider}</dt> 1108 <dd>Most applications don't need to use this class. This class defines a {@link 1109 android.content.ContentProvider} that marshals the data from the ZIP files through a content 1110 provider {@link android.net.Uri} in order to provide file access for certain Android APIs that 1111 expect {@link android.net.Uri} access to media files. For example, this is useful if you want to 1112 play a video with {@link android.widget.VideoView#setVideoURI VideoView.setVideoURI()}.</p></dd> 1113 </dl> 1114 1115 <h4>Reading from a ZIP file</h4> 1116 1117 <p>When using the APK Expansion Zip Library, reading a file from your ZIP usually requires the 1118 following:</p> 1119 1120 <pre> 1121 // Get a ZipResourceFile representing a merger of both the main and patch files 1122 ZipResourceFile expansionFile = 1123 APKExpansionSupport.getAPKExpansionZipFile(appContext, 1124 mainVersion, patchVersion); 1125 1126 // Get an input stream for a known file inside the expansion file ZIPs 1127 InputStream fileStream = expansionFile.getInputStream(pathToFileInsideZip); 1128 </pre> 1129 1130 <p>The above code provides access to any file that exists in either your main expansion file or 1131 patch expansion file, by reading from a merged map of all the files from both files. All you 1132 need to provide the {@code getAPKExpansionFile()} method is your application {@code 1133 android.content.Context} and the version number for both the main expansion file and patch 1134 expansion file.</p> 1135 1136 <p>If you'd rather read from a specific expansion file, you can use the {@code 1137 ZipResourceFile} constructor with the path to the desired expansion file:</p> 1138 1139 <pre> 1140 // Get a ZipResourceFile representing a specific expansion file 1141 ZipResourceFile expansionFile = new ZipResourceFile(filePathToMyZip); 1142 1143 // Get an input stream for a known file inside the expansion file ZIPs 1144 InputStream fileStream = expansionFile.getInputStream(pathToFileInsideZip); 1145 </pre> 1146 1147 <p>For more information about using this library for your expansion files, look at 1148 the sample application's {@code SampleDownloaderActivity} class, which includes additional code to 1149 verify the downloaded files using CRC. Beware that if you use this sample as the basis for 1150 your own implementation, it requires that you <strong>declare the byte size of your expansion 1151 files</strong> in the {@code xAPKS} array.</p> 1152 1153 1154 1155 1156 <h2 id="Testing">Testing Your Expansion Files</h2> 1157 1158 <p>Before publishing your application, there are two things you should test: Reading the 1159 expansion files and downloading the files.</p> 1160 1161 1162 <h3 id="TestingReading">Testing file reads</h3> 1163 1164 <p>Before you upload your application to Google Play, you 1165 should test your application's ability to read the files from the shared storage. All you need to do 1166 is add the files to the appropriate location on the device shared storage and launch your 1167 application:</p> 1168 1169 <ol> 1170 <li>On your device, create the appropriate directory on the shared storage where Google 1171 Play will save your files. 1172 <p>For example, if your package name is {@code com.example.android}, you need to create 1173 the directory {@code Android/obb/com.example.android/} on the shared storage space. (Plug in 1174 your test device to your computer to mount the shared storage and manually create this 1175 directory.)</p> 1176 </li> 1177 <li>Manually add the expansion files to that directory. Be sure that you rename your files to 1178 match the <a href="#Filename">file name format</a> that Google Play will use. 1179 <p>For example, regardless of the file type, the main expansion file for the {@code 1180 com.example.android} application should be {@code main.0300110.com.example.android.obb}. 1181 The version code can be whatever value you want. Just remember:</p> 1182 <ul> 1183 <li>The main expansion file always starts with {@code main} and the patch file starts with 1184 {@code patch}.</li> 1185 <li>The package name always matches that of the APK to which the file is attached on 1186 Google Play. 1187 </ul> 1188 </li> 1189 <li>Now that the expansion file(s) are on the device, you can install and run your application to 1190 test your expansion file(s).</li> 1191 </ol> 1192 1193 <p>Here are some reminders about handling the expansion files:</p> 1194 <ul> 1195 <li><strong>Do not delete or rename</strong> the {@code .obb} expansion files (even if you unpack 1196 the data to a different location). Doing so will cause Google Play (or your app itself) to 1197 repeatedly download the expansion file.</li> 1198 <li><strong>Do not save other data into your <code>obb/</code> 1199 directory</strong>. If you must unpack some data, save it into the location specified by {@link 1200 android.content.Context#getExternalFilesDir getExternalFilesDir()}.</li> 1201 </ul> 1202 1203 1204 1205 <h3 id="TestingReading">Testing file downloads</h3> 1206 1207 <p>Because your application must sometimes manually download the expansion files when it first 1208 opens, it's important that you test this process to be sure your application can successfully query 1209 for the URLs, download the files, and save them to the device.</p> 1210 1211 <p>To test your application's implementation of the manual download procedure, 1212 you can publish it to the alpha or beta channel, so it will only be available to 1213 authorized testers. 1214 If everything works as expected, your application should begin downloading the expansion 1215 files as soon as the main activity starts.</p> 1216 1217 <p class="note"><strong>Note:</strong> Previously you could test an app by 1218 uploading an unpublished "draft" version. This functionality is no longer 1219 supported; instead, you must publish it to the alpha or beta distribution 1220 channel. For more information, see <a 1221 href="{@docRoot}google/play/billing/billing_testing.html#draft_apps">Draft Apps 1222 are No Longer Supported</a>. 1223 1224 <h2 id="Updating">Updating Your Application</h2> 1225 1226 <p>One of the great benefits to using expansion files on Google Play is the ability to 1227 update your application without re-downloading all of the original assets. Because Google Play 1228 allows you to provide two expansion files with each APK, you can use the second file as a "patch" 1229 that provides updates and new assets. Doing so avoids the 1230 need to re-download the main expansion file which could be large and expensive for users.</p> 1231 1232 <p>The patch expansion file is technically the same as the main expansion file and neither 1233 the Android system nor Google Play perform actual patching between your main and patch expansion 1234 files. Your application code must perform any necessary patches itself.</p> 1235 1236 <p>If you use ZIP files as your expansion files, the <a href="#ZipLib">APK Expansion Zip 1237 Library</a> that's included with the Apk Expansion package includes the ability to merge 1238 your 1239 patch file with the main expansion file.</p> 1240 1241 <p class="note"><strong>Note:</strong> Even if you only need to make changes to the patch 1242 expansion file, you must still update the APK in order for Google Play to perform an update. 1243 If you don't require code changes in the application, you should simply update the <a 1244 href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code versionCode}</a> in the 1245 manifest.</p> 1246 1247 <p>As long as you don't change the main expansion file that's associated with the APK 1248 in the Developer Console, users who previously installed your application will not 1249 download the main expansion file. Existing users receive only the updated APK and the new patch 1250 expansion file (retaining the previous main expansion file).</p> 1251 1252 <p>Here are a few issues to keep in mind regarding updates to expansion files:</p> 1253 1254 <ul> 1255 <li>There can be only two expansion files for your application at a time. One main expansion 1256 file and one patch expansion file. During an update to a file, Google Play deletes the 1257 previous version (and so must your application when performing manual updates).</li> 1258 <li>When adding a patch expansion file, the Android system does not actually patch your 1259 application or main expansion file. You must design your application to support the patch data. 1260 However, the Apk Expansion package includes a library for using ZIP files 1261 as expansion files, which merges the data from the patch file into the main expansion file so 1262 you can easily read all the expansion file data.</li> 1263 </ul> 1264 1265 1266 1267 <!-- Tools are not ready. 1268 1269 <h3>Using OBB tool and APIs</h3> 1270 1271 <pre> 1272 $ mkobb.sh -d /data/myfiles -k my_secret_key -o /data/data.obb 1273 $ obbtool a -n com.example.myapp -v 1 -s seed_from_mkobb /data/data.obb 1274 </pre> 1275 1276 <pre> 1277 storage = (StorageManager) getSystemService( STORAGE_SERVICE ); 1278 storage.mountObb( obbFilepath, "my_secret_key", myListener ); 1279 obbContentPath = storage.getMountedObbPath( obbFilepath ); 1280 </pre> 1281 --> 1282