docs: add document about app install location
Change-Id: Ife7d79ce8374f3435f4850cbf97d163e69bf8d26
This commit is contained in:
Scott Main
197
docs/html/guide/appendix/install-location.jd
Normal file
197
docs/html/guide/appendix/install-location.jd
Normal file
@@ -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>
|
||||
|
||||
@@ -110,7 +110,7 @@
|
||||
</a></li>
|
||||
<li><a href="<?cs var:toroot ?>guide/topics/resources/runtime-changes.html">
|
||||
<span class="en">Handling Runtime Changes</span>
|
||||
</a></li>
|
||||
</a> <span class="new">new!</span></li>
|
||||
<li><a href="<?cs var:toroot ?>guide/topics/resources/localization.html">
|
||||
<span class="en">Localization</span>
|
||||
</a></li>
|
||||
@@ -431,8 +431,11 @@
|
||||
<span class="en">Android API Levels</span>
|
||||
</a></li>
|
||||
<li><a href="<?cs var:toroot ?>guide/appendix/market-filters.html">
|
||||
<span class="en">Market Filters </span>
|
||||
</a><span class="new">new!</span></li>
|
||||
<span class="en">Market Filters</span>
|
||||
</a> <span class="new">new!</span></li>
|
||||
<li><a href="<?cs var:toroot ?>guide/appendix/install-location.html">
|
||||
<span class="en">App Install Location</span>
|
||||
</a> <span class="new">new!</span></li>
|
||||
<li><a href="<?cs var:toroot ?>guide/appendix/media-formats.html">
|
||||
<span class="en">Supported Media Formats</span>
|
||||
</a></li>
|
||||
|
||||
@@ -161,6 +161,7 @@ this attribute is set to {@code internalOnly}, which is the default setting.</p>
|
||||
|
||||
<p>Introduced in: API Level 8.</p>
|
||||
|
||||
|
||||
</dd>
|
||||
|
||||
</dl>
|
||||
|
||||
Reference in New Issue
Block a user