| page.title=App Install Location |
| @jd:body |
| |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| |
| <h2>Quickview</h2> |
| <ul> |
| <li>You can allow your application to install on the device's external storage.</li> |
| <li>Some types of applications should <strong>not</strong> allow installation on the external |
| storage.</li> |
| <li>Installing on the external storage is ideal for large applications that are not tightly |
| integrated with the system (most commonly, games).</li> |
| </ul> |
| |
| <h2>In this document</h2> |
| <ol> |
| <li><a href="#Compatiblity">Backward Compatibility</a></li> |
| <li><a href="#ShouldNot">Applications That Should NOT Install on External Storage</a></li> |
| <li><a href="#Should">Applications That Should Install on External Storage</a></li> |
| </ol> |
| |
| <h2>See also</h2> |
| <ol> |
| <li><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"> |
| <manifest></a></code></li> |
| </ol> |
| |
| </div> |
| </div> |
| |
| <p>Beginning with API Level 8, you can allow your application to be installed on the |
| external storage (for example, the device's SD card). This is an optional feature you can declare |
| for your application with the <a |
| href="{@docRoot}guide/topics/manifest/manifest-element.html#install">{@code |
| android:installLocation}</a> manifest attribute. If you do |
| <em>not</em> declare this attribute, your application will be installed on the internal storage |
| only and it cannot be moved to the external storage.</p> |
| |
| <p>To allow the system to install your application on the external storage, modify your |
| manifest file to include the <a |
| href="{@docRoot}guide/topics/manifest/manifest-element.html#install">{@code |
| android:installLocation}</a> attribute in the <code><a |
| href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element, |
| with a value of either "{@code preferExternal}" or "{@code auto}". For example:</p> |
| |
| <pre> |
| <manifest xmlns:android="http://schemas.android.com/apk/res/android" |
| android:installLocation="preferExternal" |
| ... > |
| </pre> |
| |
| <p>If you declare "{@code preferExternal}", you request that your application be installed on the |
| external storage, but the system does not guarantee that your application will be installed on |
| the external storage. If the external storage is full, the system will install it on the internal |
| storage. The user can also move your application between the two locations.</p> |
| |
| <p>If you declare "{@code auto}", you indicate that your application may be installed on the |
| external storage, but you don't have a preference of install location. The system will |
| decide where to install your application based on several factors. The user can also move your |
| application between the two locations.</p> |
| |
| <p>When your application is installed on the external storage:</p> |
| <ul> |
| <li>There is no effect on the application performance so long |
| as the external storage is mounted on the device.</li> |
| <li>The {@code .apk} file is saved on the external storage, but all private user data, |
| databases, optimized {@code .dex} files, and extracted native code are saved on the |
| internal device memory.</li> |
| <li>The unique container in which your application is stored is encrypted with a randomly |
| generated key that can be decrypted only by the device that originally installed it. Thus, an |
| application installed on an SD card works for only one device.</li> |
| <li>The user can move your application to the internal storage through the system settings.</li> |
| </ul> |
| |
| <p class="warning"><strong>Warning:</strong> When the user enables USB mass storage to share files |
| with a computer or unmounts the SD card via the system settings, the external storage is unmounted |
| from the device and all applications running on the external storage are immediately killed.</p> |
| |
| |
| |
| <h2 id="Compatiblity">Backward Compatibility</h2> |
| |
| <p>The ability for your application to install on the external storage is a feature available only |
| on devices running API Level 8 (Android 2.2) or greater. Existing applications that were built prior |
| to API Level 8 will always install on the internal storage and cannot be moved to the external |
| storage (even on devices with API Level 8). However, if your application is designed to support an |
| API Level <em>lower than</em> 8, you can choose to support this feature for devices with API Level 8 |
| or greater and still be compatible with devices using an API Level lower than 8.</p> |
| |
| <p>To allow installation on external storage and remain compatible with versions lower than API |
| Level 8:</p> |
| <ol> |
| <li>Include the {@code android:installLocation} attribute with a value of "{@code auto}" or |
| "{@code preferExternal}" in the <code><a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><manifest></a></code> |
| element.</li> |
| <li>Leave your {@code android:minSdkVersion} attribute as is (something <em>less |
| than</em> "8") and be certain that your application code uses only APIs compatible with that |
| level.</li> |
| <li>In order to compile your application, change your build target to API Level 8. This is |
| necessary because older Android libraries don't understand the {@code android:installLocation} |
| attribute and will not compile your application when it's present.</li> |
| </ol> |
| |
| <p>When your application is installed on a device with an API Level lower than 8, the {@code |
| android:installLocation} attribute is ignored and the application is installed on the internal |
| storage.</p> |
| |
| <p class="caution"><strong>Caution:</strong> Although XML markup such as this will be ignored by |
| older platforms, you must be careful not to use programming APIs introduced in API Level 8 |
| while your {@code minSdkVersion} is less than "8", unless you perform the work necessary to |
| provide backward compatibility in your code. For information about building |
| backward compatibility in your application code, see the <a |
| href="{@docRoot}resources/articles/backward-compatibility.html">Backward Compatibility</a> |
| article.</p> |
| |
| |
| |
| <h2 id="ShouldNot">Applications That Should NOT Install on External Storage</h2> |
| |
| <p>When the user enables USB mass storage to share files with their computer (or otherwise |
| unmounts or removes the external storage), any application |
| installed on the external storage and currently running is killed. The system effectively becomes |
| unaware of the application until mass storage is disabled and the external storage is |
| remounted on the device. Besides killing the application and making it unavailable to the user, |
| this can break some types of applications in a more serious way. In order for your application to |
| consistently behave as expected, you <strong>should not</strong> allow your application to be |
| installed on the external storage if it uses any of the following features, due to the cited |
| consequences when the external storage is unmounted:</p> |
| |
| <dl> |
| <dt>Services</dt> |
| <dd>Your running {@link android.app.Service} will be killed and will not be restarted when |
| external storage is remounted. You can, however, register for the {@link |
| android.content.Intent#ACTION_EXTERNAL_APPLICATIONS_AVAILABLE} broadcast Intent, which will notify |
| your application when applications installed on external storage have become available to the |
| system again. At which time, you can restart your Service.</dd> |
| <dt>Alarm Services</dt> |
| <dd>Your alarms registered with {@link android.app.AlarmManager} will be cancelled. You must |
| manually re-register any alarms when external storage is remounted.</dd> |
| <dt>Input Method Engines</dt> |
| <dd>Your <a href="{@docRoot}resources/articles/on-screen-inputs.html">IME</a> will be |
| replaced by the default IME. When external storage is remounted, the user can open system settings |
| to enable your IME again.</dd> |
| <dt>Live Wallpapers</dt> |
| <dd>Your running <a href="{@docRoot}resources/articles/live-wallpapers.html">Live Wallpaper</a> |
| will be replaced by the default Live Wallpaper. When external storage is remounted, the user can |
| select your Live Wallpaper again.</dd> |
| <dt>Live Folders</dt> |
| <dd>Your <a href="{@docRoot}resources/articles/live-folders.html">Live Folder</a> will be |
| removed from the home screen. When external storage is remounted, the user can add your Live Folder |
| to the home screen again.</dd> |
| <dt>App Widgets</dt> |
| <dd>Your <a href="{@docRoot}guide/topics/appwidgets/index.html">App Widget</a> will be removed |
| from the home screen. When external storage is remounted, your App Widget will <em>not</em> be |
| available for the user to select until the system resets the home application (usually not until a |
| system reboot).</dd> |
| <dt>Account Managers</dt> |
| <dd>Your accounts created with {@link android.accounts.AccountManager} will disappear until |
| external storage is remounted.</dd> |
| <dt>Sync Adapters</dt> |
| <dd>Your {@link android.content.AbstractThreadedSyncAdapter} and all its sync functionality will |
| not work until external storage is remounted.</dd> |
| <dt>Device Administrators</dt> |
| <dd>Your {@link android.app.admin.DeviceAdminReceiver} and all its admin capabilities will |
| be disabled, which can have unforeseeable consequences for the device functionality, which may |
| persist after external storage is remounted.</dd> |
| <dt>Broadcast Receivers listening for "boot completed"</dt> |
| <dd>The system delivers the {@link android.content.Intent#ACTION_BOOT_COMPLETED} broadcast |
| before the external storage is mounted to the device. If your application is installed on the |
| external storage, it can never receive this broadcast.</dd> |
| <dt>Copy Protection</dt> |
| <dd>Your application cannot be installed to a device's SD card if it uses Google Play's |
| Copy Protection feature. However, if you use Google Play's |
| <a href="{@docRoot}guide/market/licensing.html">Application Licensing</a> instead, your |
| application <em>can</em> be installed to internal or external storage, including SD cards.</dd> |
| </dl> |
| |
| <p>If your application uses any of the features listed above, you <strong>should not</strong> allow |
| your application to install on external storage. By default, the system <em>will not</em> allow your |
| application to install on the external storage, so you don't need to worry about your existing |
| applications. However, if you're certain that your application should never be installed on the |
| external storage, then you should make this clear by declaring <a |
| href="{@docRoot}guide/topics/manifest/manifest-element.html#install">{@code |
| android:installLocation}</a> with a value of "{@code internalOnly}". Though this does not |
| change the default behavior, it explicitly states that your application should only be installed |
| on the internal storage and serves as a reminder to you and other developers that this decision has |
| been made.</p> |
| |
| |
| <h2 id="Should">Applications That Should Install on External Storage</h2> |
| |
| <p>In simple terms, anything that does not use the features listed in the previous section |
| are safe when installed on external storage. Large games are more commonly the types of |
| applications that should allow installation on external storage, because games don't typically |
| provide additional services when inactive. When external storage becomes unavailable and a game |
| process is killed, there should be no visible effect when the storage becomes available again and |
| the user restarts the game (assuming that the game properly saved its state during the normal |
| <a href="{@docRoot}guide/topics/fundamentals/activities.html#Lifecycle">Activity lifecycle</a>).</p> |
| |
| <p>If your application requires several megabytes for the APK file, you should |
| carefully consider whether to enable the application to install on the external storage so that |
| users can preserve space on their internal storage.</p> |
| |