Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 1 | page.title=App Install Location |
Scott Main | 64461bf | 2013-04-11 19:32:08 -0700 | [diff] [blame] | 2 | page.tags="sdcard","external" |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 3 | @jd:body |
| 4 | |
| 5 | |
| 6 | <div id="qv-wrapper"> |
| 7 | <div id="qv"> |
| 8 | |
| 9 | <h2>Quickview</h2> |
| 10 | <ul> |
| 11 | <li>You can allow your application to install on the device's external storage.</li> |
| 12 | <li>Some types of applications should <strong>not</strong> allow installation on the external |
| 13 | storage.</li> |
| 14 | <li>Installing on the external storage is ideal for large applications that are not tightly |
| 15 | integrated with the system (most commonly, games).</li> |
| 16 | </ul> |
| 17 | |
| 18 | <h2>In this document</h2> |
| 19 | <ol> |
| 20 | <li><a href="#Compatiblity">Backward Compatibility</a></li> |
| 21 | <li><a href="#ShouldNot">Applications That Should NOT Install on External Storage</a></li> |
| 22 | <li><a href="#Should">Applications That Should Install on External Storage</a></li> |
| 23 | </ol> |
| 24 | |
| 25 | <h2>See also</h2> |
| 26 | <ol> |
| 27 | <li><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"> |
| 28 | <manifest></a></code></li> |
| 29 | </ol> |
| 30 | |
| 31 | </div> |
| 32 | </div> |
| 33 | |
| 34 | <p>Beginning with API Level 8, you can allow your application to be installed on the |
| 35 | external storage (for example, the device's SD card). This is an optional feature you can declare |
| 36 | for your application with the <a |
| 37 | href="{@docRoot}guide/topics/manifest/manifest-element.html#install">{@code |
| 38 | android:installLocation}</a> manifest attribute. If you do |
| 39 | <em>not</em> declare this attribute, your application will be installed on the internal storage |
| 40 | only and it cannot be moved to the external storage.</p> |
| 41 | |
| 42 | <p>To allow the system to install your application on the external storage, modify your |
| 43 | manifest file to include the <a |
| 44 | href="{@docRoot}guide/topics/manifest/manifest-element.html#install">{@code |
| 45 | android:installLocation}</a> attribute in the <code><a |
| 46 | href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element, |
| 47 | with a value of either "{@code preferExternal}" or "{@code auto}". For example:</p> |
| 48 | |
| 49 | <pre> |
| 50 | <manifest xmlns:android="http://schemas.android.com/apk/res/android" |
| 51 | android:installLocation="preferExternal" |
| 52 | ... > |
| 53 | </pre> |
| 54 | |
| 55 | <p>If you declare "{@code preferExternal}", you request that your application be installed on the |
| 56 | external storage, but the system does not guarantee that your application will be installed on |
| 57 | the external storage. If the external storage is full, the system will install it on the internal |
| 58 | storage. The user can also move your application between the two locations.</p> |
| 59 | |
| 60 | <p>If you declare "{@code auto}", you indicate that your application may be installed on the |
| 61 | external storage, but you don't have a preference of install location. The system will |
| 62 | decide where to install your application based on several factors. The user can also move your |
| 63 | application between the two locations.</p> |
| 64 | |
| 65 | <p>When your application is installed on the external storage:</p> |
| 66 | <ul> |
| 67 | <li>There is no effect on the application performance so long |
| 68 | as the external storage is mounted on the device.</li> |
| 69 | <li>The {@code .apk} file is saved on the external storage, but all private user data, |
| 70 | databases, optimized {@code .dex} files, and extracted native code are saved on the |
| 71 | internal device memory.</li> |
| 72 | <li>The unique container in which your application is stored is encrypted with a randomly |
| 73 | generated key that can be decrypted only by the device that originally installed it. Thus, an |
| 74 | application installed on an SD card works for only one device.</li> |
| 75 | <li>The user can move your application to the internal storage through the system settings.</li> |
| 76 | </ul> |
| 77 | |
| 78 | <p class="warning"><strong>Warning:</strong> When the user enables USB mass storage to share files |
| 79 | with a computer or unmounts the SD card via the system settings, the external storage is unmounted |
| 80 | from the device and all applications running on the external storage are immediately killed.</p> |
| 81 | |
| 82 | |
| 83 | |
| 84 | <h2 id="Compatiblity">Backward Compatibility</h2> |
| 85 | |
| 86 | <p>The ability for your application to install on the external storage is a feature available only |
| 87 | on devices running API Level 8 (Android 2.2) or greater. Existing applications that were built prior |
| 88 | to API Level 8 will always install on the internal storage and cannot be moved to the external |
| 89 | storage (even on devices with API Level 8). However, if your application is designed to support an |
| 90 | API Level <em>lower than</em> 8, you can choose to support this feature for devices with API Level 8 |
| 91 | or greater and still be compatible with devices using an API Level lower than 8.</p> |
| 92 | |
| 93 | <p>To allow installation on external storage and remain compatible with versions lower than API |
| 94 | Level 8:</p> |
| 95 | <ol> |
| 96 | <li>Include the {@code android:installLocation} attribute with a value of "{@code auto}" or |
| 97 | "{@code preferExternal}" in the <code><a |
| 98 | href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><manifest></a></code> |
| 99 | element.</li> |
| 100 | <li>Leave your {@code android:minSdkVersion} attribute as is (something <em>less |
| 101 | than</em> "8") and be certain that your application code uses only APIs compatible with that |
| 102 | level.</li> |
| 103 | <li>In order to compile your application, change your build target to API Level 8. This is |
| 104 | necessary because older Android libraries don't understand the {@code android:installLocation} |
| 105 | attribute and will not compile your application when it's present.</li> |
| 106 | </ol> |
| 107 | |
| 108 | <p>When your application is installed on a device with an API Level lower than 8, the {@code |
| 109 | android:installLocation} attribute is ignored and the application is installed on the internal |
| 110 | storage.</p> |
| 111 | |
| 112 | <p class="caution"><strong>Caution:</strong> Although XML markup such as this will be ignored by |
| 113 | older platforms, you must be careful not to use programming APIs introduced in API Level 8 |
| 114 | while your {@code minSdkVersion} is less than "8", unless you perform the work necessary to |
Scott Main | f284d49 | 2012-07-31 09:46:52 -0700 | [diff] [blame] | 115 | provide backward compatibility in your code.</p> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 116 | |
| 117 | |
| 118 | |
| 119 | <h2 id="ShouldNot">Applications That Should NOT Install on External Storage</h2> |
| 120 | |
| 121 | <p>When the user enables USB mass storage to share files with their computer (or otherwise |
| 122 | unmounts or removes the external storage), any application |
| 123 | installed on the external storage and currently running is killed. The system effectively becomes |
| 124 | unaware of the application until mass storage is disabled and the external storage is |
| 125 | remounted on the device. Besides killing the application and making it unavailable to the user, |
| 126 | this can break some types of applications in a more serious way. In order for your application to |
| 127 | consistently behave as expected, you <strong>should not</strong> allow your application to be |
| 128 | installed on the external storage if it uses any of the following features, due to the cited |
| 129 | consequences when the external storage is unmounted:</p> |
| 130 | |
| 131 | <dl> |
| 132 | <dt>Services</dt> |
| 133 | <dd>Your running {@link android.app.Service} will be killed and will not be restarted when |
| 134 | external storage is remounted. You can, however, register for the {@link |
| 135 | android.content.Intent#ACTION_EXTERNAL_APPLICATIONS_AVAILABLE} broadcast Intent, which will notify |
| 136 | your application when applications installed on external storage have become available to the |
| 137 | system again. At which time, you can restart your Service.</dd> |
| 138 | <dt>Alarm Services</dt> |
| 139 | <dd>Your alarms registered with {@link android.app.AlarmManager} will be cancelled. You must |
| 140 | manually re-register any alarms when external storage is remounted.</dd> |
| 141 | <dt>Input Method Engines</dt> |
Scott Main | f284d49 | 2012-07-31 09:46:52 -0700 | [diff] [blame] | 142 | <dd>Your <a href="{@docRoot}guide/topics/text/creating-input-method.html">IME</a> will be |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 143 | replaced by the default IME. When external storage is remounted, the user can open system settings |
| 144 | to enable your IME again.</dd> |
| 145 | <dt>Live Wallpapers</dt> |
Scott Main | f284d49 | 2012-07-31 09:46:52 -0700 | [diff] [blame] | 146 | <dd>Your running <a href="http://android-developers.blogspot.com/2010/02/live-wallpapers.html">Live Wallpaper</a> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 147 | will be replaced by the default Live Wallpaper. When external storage is remounted, the user can |
| 148 | select your Live Wallpaper again.</dd> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 149 | <dt>App Widgets</dt> |
| 150 | <dd>Your <a href="{@docRoot}guide/topics/appwidgets/index.html">App Widget</a> will be removed |
| 151 | from the home screen. When external storage is remounted, your App Widget will <em>not</em> be |
| 152 | available for the user to select until the system resets the home application (usually not until a |
| 153 | system reboot).</dd> |
| 154 | <dt>Account Managers</dt> |
| 155 | <dd>Your accounts created with {@link android.accounts.AccountManager} will disappear until |
| 156 | external storage is remounted.</dd> |
| 157 | <dt>Sync Adapters</dt> |
| 158 | <dd>Your {@link android.content.AbstractThreadedSyncAdapter} and all its sync functionality will |
| 159 | not work until external storage is remounted.</dd> |
| 160 | <dt>Device Administrators</dt> |
| 161 | <dd>Your {@link android.app.admin.DeviceAdminReceiver} and all its admin capabilities will |
| 162 | be disabled, which can have unforeseeable consequences for the device functionality, which may |
| 163 | persist after external storage is remounted.</dd> |
| 164 | <dt>Broadcast Receivers listening for "boot completed"</dt> |
| 165 | <dd>The system delivers the {@link android.content.Intent#ACTION_BOOT_COMPLETED} broadcast |
| 166 | before the external storage is mounted to the device. If your application is installed on the |
| 167 | external storage, it can never receive this broadcast.</dd> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 168 | </dl> |
| 169 | |
| 170 | <p>If your application uses any of the features listed above, you <strong>should not</strong> allow |
| 171 | your application to install on external storage. By default, the system <em>will not</em> allow your |
| 172 | application to install on the external storage, so you don't need to worry about your existing |
| 173 | applications. However, if you're certain that your application should never be installed on the |
| 174 | external storage, then you should make this clear by declaring <a |
| 175 | href="{@docRoot}guide/topics/manifest/manifest-element.html#install">{@code |
| 176 | android:installLocation}</a> with a value of "{@code internalOnly}". Though this does not |
| 177 | change the default behavior, it explicitly states that your application should only be installed |
| 178 | on the internal storage and serves as a reminder to you and other developers that this decision has |
| 179 | been made.</p> |
| 180 | |
| 181 | |
| 182 | <h2 id="Should">Applications That Should Install on External Storage</h2> |
| 183 | |
| 184 | <p>In simple terms, anything that does not use the features listed in the previous section |
| 185 | are safe when installed on external storage. Large games are more commonly the types of |
| 186 | applications that should allow installation on external storage, because games don't typically |
| 187 | provide additional services when inactive. When external storage becomes unavailable and a game |
| 188 | process is killed, there should be no visible effect when the storage becomes available again and |
| 189 | the user restarts the game (assuming that the game properly saved its state during the normal |
| 190 | <a href="{@docRoot}guide/components/activities.html#Lifecycle">Activity lifecycle</a>).</p> |
| 191 | |
| 192 | <p>If your application requires several megabytes for the APK file, you should |
| 193 | carefully consider whether to enable the application to install on the external storage so that |
| 194 | users can preserve space on their internal storage.</p> |
| 195 | |