+<manifest>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 {@code +android:installLocation} manifest attribute. If you do +not declare this attribute, your application will be installed on the internal storage +only and it cannot be moved to the external storage.
+ +To allow the system to install your application on the external storage, modify your
+manifest file to include the {@code
+android:installLocation} attribute in the <manifest> element,
+with a value of either "{@code preferExternal}" or "{@code auto}". For example:
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" + android:installLocation="preferExternal" + ... > ++ +
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.
+ +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.
+ +When your application is installed on the external storage:
+Warning: 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.
+ + + +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 lower than 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.
+ +To allow installation on external storage and remain compatible with versions lower than API +Level 8:
+<manifest>
+element.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.
+ +Caution: 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 Backward Compatibility +article.
+ + + +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 should not 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:
+ +If your application uses any of the features listed above, you should not allow +your application to install on external storage. By default, the system will not 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 {@code +android:installLocation} 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.
+ + +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 +Activity lifecycle).
+ +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.
+ diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 22775017c0826..a484c9fb49fa2 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -110,7 +110,7 @@Introduced in: API Level 8.
+