202 lines
11 KiB
Plaintext
202 lines
11 KiB
Plaintext
|
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>
|
||
|
|
</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>
|
||
|
|
|