diff options
Diffstat (limited to 'docs/html/guide/appendix/install-location.jd')
| -rw-r--r-- | docs/html/guide/appendix/install-location.jd | 197 |
1 files changed, 197 insertions, 0 deletions
diff --git a/docs/html/guide/appendix/install-location.jd b/docs/html/guide/appendix/install-location.jd new file mode 100644 index 0000000..77cebc6 --- /dev/null +++ b/docs/html/guide/appendix/install-location.jd @@ -0,0 +1,197 @@ +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="{@docRoog}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 compatiblity 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> +</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 innactive. 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.html#lcycles">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> + |