1189 lines
60 KiB
HTML
1189 lines
60 KiB
HTML
<html devsite>
|
|
<head>
|
|
<title>Android 2.1 Compatibility Definition</title>
|
|
<link rel="stylesheet" type="text/css" href="cdd.css"/>
|
|
</head>
|
|
<body>
|
|
<p>Copyright © 2010, Google Inc. All rights reserved.<br/>
|
|
<a href="mailto:compatibility@android.com">compatibility@android.com</a>
|
|
</p>
|
|
|
|
<h2>1. Introduction</h2>
|
|
<p>This document enumerates the requirements that must be met in order for
|
|
mobile phones to be compatible with Android 2.1.</p>
|
|
<p>The use of "must", "must not", "required", "shall", "shall not", "should",
|
|
"should not", "recommended", "may" and "optional" is per the IETF standard
|
|
defined in RFC2119 [<a href="#resources01">Resources, 1</a>].</p>
|
|
<p>As used in this document, a "device implementer" or "implementer" is a
|
|
person or organization developing a hardware/software solution running Android
|
|
2.1. A "device implementation" or "implementation" is the hardware/software
|
|
solution so developed.</p>
|
|
<p>To be considered compatible with Android 2.1, device implementations:</p>
|
|
<ul>
|
|
<li>MUST meet the requirements presented in this Compatibility Definition,
|
|
including any documents incorporated via reference.</li>
|
|
<li>MUST pass the most recent version of the Android Compatibility Test Suite
|
|
(CTS) available at the time of the device implementation's software is
|
|
completed. (The CTS is available as part of the Android Open Source Project [<a
|
|
href="#resources02">Resources, 2</a>].) The CTS tests many, but not all, of the
|
|
components outlined in this document.</li>
|
|
</ul>
|
|
<p>Where this definition or the CTS is silent, ambiguous, or incomplete, it is
|
|
the responsibility of the device implementer to ensure compatibility with
|
|
existing implementations. For this reason, the Android Open Source Project [<a
|
|
href="#resources03">Resources, 3</a>] is both the reference and preferred
|
|
implementation of Android. Device implementers are strongly encouraged to base
|
|
their implementations on the "upstream" source code available from the Android
|
|
Open Source Project. While some components can hypothetically be replaced with
|
|
alternate implementations this practice is strongly discouraged, as passing
|
|
the CTS tests will become substantially more difficult. It is the
|
|
implementer's responsibility to ensure full behavioral compatibility with the
|
|
standard Android implementation, including and beyond the Compatibility Test
|
|
Suite. Finally, note that certain component substitutions and modifications
|
|
are explicitly forbidden by this document.</p>
|
|
|
|
<a name="resources"/><h2>2. Resources</h2>
|
|
<ol>
|
|
<a name="resources01"/><li>IETF RFC2119 Requirement Levels: <a href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a></li>
|
|
<a name="resources02"/><li>Android Compatibility Program Overview: <a href="http://source.android.com/compatibility/index.html">http://source.android.com/compatibility/index.html</a></li>
|
|
<a name="resources03"/><li>Android Open Source Project: <a href="http://source.android.com/">http://source.android.com/</a></li>
|
|
<a name="resources04"/><li>API definitions and documentation: <a href="http://developer.android.com/reference/packages.html">http://developer.android.com/reference/packages.html</a></li>
|
|
<a name="resources05"/><li>Android Permissions reference: <a href="http://developer.android.com/reference/android/Manifest.permission.html">http://developer.android.com/reference/android/Manifest.permission.html</a></li>
|
|
<a name="resources06"/><li>android.os.Build reference: <a href="http://developer.android.com/reference/android/os/Build.html">http://developer.android.com/reference/android/os/Build.html</a></li>
|
|
<a name="resources07"/><li>Android 2.1 allowed version strings: <a href="http://source.android.com/compatibility/2.1/versions.xhtml">http://source.android.com/compatibility/2.1/versions.xhtml</a></li>
|
|
<a name="resources08"/><li>android.webkit.WebView class: <a href="http://developer.android.com/reference/android/webkit/WebView.html">http://developer.android.com/reference/android/webkit/WebView.html</a></li>
|
|
<a name="resources09"/><li>HTML5: <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/">http://www.whatwg.org/specs/web-apps/current-work/multipage/</a></li>
|
|
<a name="resources10"/><li>Dalvik Virtual Machine specification: available in the Android source code, at dalvik/docs</li>
|
|
<a name="resources11"/><li>AppWidgets: <a href="http://developer.android.com/guide/practices/ui_guidelines/widget_design.html">http://developer.android.com/guide/practices/ui_guidelines/widget_design.html</a></li>
|
|
<a name="resources12"/><li>Notifications: <a href="http://developer.android.com/guide/topics/ui/notifiers/notifications.html">http://developer.android.com/guide/topics/ui/notifiers/notifications.html</a></li>
|
|
<a name="resources13"/><li>Application Resources: <a href="http://code.google.com/android/reference/available-resources.html">http://code.google.com/android/reference/available-resources.html</a></li>
|
|
<a name="resources14"/><li>Status Bar icon style guide: <a href="http://developer.android.com/guide/practices/ui_guidelines/icon_design.html#statusbarstructure">http://developer.android.com/guide/practices/ui_guideline /icon_design.html#statusbarstructure</a></li>
|
|
<a name="resources15"/><li>Search Manager: <a href="http://developer.android.com/reference/android/app/SearchManager.html">http://developer.android.com/reference/android/app/SearchManager.html</a></li>
|
|
<a name="resources16"/><li>Toasts: <a href="http://developer.android.com/reference/android/widget/Toast.html">http://developer.android.com/reference/android/widget/Toast.html</a></li>
|
|
<a name="resources17"/><li>Live Wallpapers: <a href="http://developer.android.com/resources/articles/live-wallpapers.html">http://developer.android.com/resources/articles/live-wallpapers.html</a></li>
|
|
<a name="resources18"/><li>Apps for Android: <a href="http://code.google.com/p/apps-for-android">http://code.google.com/p/apps-for-android</a></li>
|
|
<a name="resources19"/><li>Reference tool documentation (for adb, aapt, ddms): <a href="http://developer.android.com/guide/developing/tools/index.html">http://developer.android.com/guide/developing/tools/index.html</a></li>
|
|
<a name="resources20"/><li>Android apk file description: <a href="http://developer.android.com/guide/topics/fundamentals.html">http://developer.android.com/guide/topics/fundamentals.html</a></li>
|
|
<a name="resources21"/><li>Manifest files: <a href="http://developer.android.com/guide/topics/manifest/manifest-intro.html">http://developer.android.com/guide/topics/manifest/manifest-intro.html</a></li>
|
|
<a name="resources22"/><li>Monkey testing tool: <a href="http://developer.android.com/guide/developing/tools/monkey.html">http://developer.android.com/guide/developing/tools/monkey.html</a></li>
|
|
<a name="resources23"/><li>Supporting Multiple Screens: <a href="http://developer.android.com/guide/practices/screens_support.html">http://developer.android.com/guide/practices/screens_support.html</a></li>
|
|
<a name="resources24"/><li>android.content.res.Configuration: <a href="http://developer.android.com/reference/android/content/res/Configuration.html">http://developer.android.com/reference/android/content/res/Configuration.html</a></li>
|
|
<a name="resources25"/><li>android.util.DisplayMetrics: <a href="http://developer.android.com/reference/android/util/DisplayMetrics.html">http://developer.android.com/reference/android/util/DisplayMetrics.html</a></li>
|
|
<a name="resources26"/><li>android.hardware.Camera: <a href="http://developer.android.com/reference/android/hardware/Camera.html">http://developer.android.com/reference/android/hardware/Camera.html</a></li>
|
|
<a name="resources27"/><li>Sensor coordinate space: <a href="http://developer.android.com/reference/android/hardware/SensorEvent.html">http://developer.android.com/reference/android/hardware/SensorEvent.html</a></li>
|
|
<a name="resources28"/><li>Android Security and Permissions reference: <a href="http://developer.android.com/guide/topics/security/security.html">http://developer.android.com/guide/topics/security/security.html</a></li>
|
|
<a name="resources29"/><li>Bluetooth API: <a href="http://developer.android.com/reference/android/bluetooth/package-summary.html">http://developer.android.com/reference/android/bluetooth/package-summary.html</a></li>
|
|
</ol>
|
|
<p>Many of these resources are derived directly or indirectly from the Android
|
|
2.1 SDK, and will be functionally identical to the information in that SDK's
|
|
documentation. In any cases where this Compatibility Definition or the
|
|
Compatibility Test Suite disagrees with the SDK documentation, the SDK
|
|
documentation is considered authoritative. Any technical details provided in
|
|
the references included above are considered by inclusion to be part of this
|
|
Compatibility Definition.</p>
|
|
|
|
<h2>3. Software</h2>
|
|
<p>The Android platform includes a set of managed APIs, a set of native APIs,
|
|
and a body of so-called "soft" APIs such as the Intent system and
|
|
web-application APIs. This section details the hard and soft APIs that are
|
|
integral to compatibility, as well as certain other relevant technical and
|
|
user interface behaviors. Device implementations MUST comply with all the
|
|
requirements in this section.</p>
|
|
|
|
<h3>3.1. Managed API Compatibility</h3>
|
|
<p>The managed (Dalvik-based) execution environment is the primary vehicle for
|
|
Android applications. The Android application programming interface (API) is
|
|
the set of Android platform interfaces exposed to applications running in the
|
|
managed VM environment. Device implementations MUST provide complete
|
|
implementations, including all documented behaviors, of any documented API
|
|
exposed by the Android 2.1 SDK [<a href="#resources04">Resources, 4</a>].</p>
|
|
<p>Device implementations MUST NOT omit any managed APIs, alter API interfaces
|
|
or signatures, deviate from the documented behavior, or include no-ops, except
|
|
where specifically allowed by this Compatibility Definition.</p>
|
|
|
|
<h3>3.2. Soft API Compatibility</h3>
|
|
<p>In addition to the managed APIs from Section 3.1, Android also includes a
|
|
significant runtime-only "soft" API, in the form of such things such as
|
|
Intents, permissions, and similar aspects of Android applications that cannot
|
|
be enforced at application compile time. This section details the "soft" APIs
|
|
and system behaviors required for compatibility with Android 2.1. Device
|
|
implementations MUST meet all the requirements presented in this section.</p>
|
|
<h4>3.2.1. Permissions</h4>
|
|
<p>Device implementers MUST support and enforce all permission constants as
|
|
documented by the Permission reference page [<a
|
|
href="#resources05">Resources, 5</a>]. Note that Section 10 lists addtional
|
|
requirements related to the Android security model.</p>
|
|
<h4>3.2.2. Build Parameters</h4>
|
|
<p>The Android APIs include a number of constants on the <code>android.os.Build</code>
|
|
class [<a href="#resources06">Resources, 6</a>] that are intended to describe
|
|
the current device. To provide consistent, meaningful values across device
|
|
implementations, the table below includes additional restrictions on the
|
|
formats of these values to which device implementations MUST conform.</p>
|
|
<table>
|
|
<tbody>
|
|
<tr>
|
|
<td><b>Parameter</b></td>
|
|
<td><b>Comments</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td>android.os.Build.VERSION.RELEASE</td>
|
|
<td>The version of the currently-executing Android system, in human-readable
|
|
format. This field MUST have one of the string values defined in [<a
|
|
href="#resources07">Resources, 7</a>].</td>
|
|
</tr>
|
|
<tr>
|
|
<td>android.os.Build.VERSION.SDK</td>
|
|
<td>The version of the currently-executing Android system, in a format
|
|
accessible to third-party application code. For Android 2.1, this field MUST have
|
|
the integer value 7.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>android.os.Build.VERSION.INCREMENTAL</td>
|
|
<td>A value chosen by the device implementer designating the specific build of
|
|
the currently-executing Android system, in human-readable format. This value
|
|
MUST NOT be re-used for different builds shipped to end users. A typical use
|
|
of this field is to indicate which build number or source-control change
|
|
identifier was used to generate the build. There are no requirements on the
|
|
specific format of this field, except that it MUST NOT be null or the empty
|
|
string ("").</td>
|
|
</tr>
|
|
<tr>
|
|
<td>android.os.Build.BOARD</td>
|
|
<td>A value chosen by the device implementer identifying the specific internal
|
|
hardware used by the device, in human-readable format. A possible use of this
|
|
field is to indicate the specific revision of the board powering the device.
|
|
There are no requirements on the specific format of this field, except that it
|
|
MUST NOT be null or the empty string ("").</td>
|
|
</tr>
|
|
<tr>
|
|
<td>android.os.Build.BRAND</td>
|
|
<td>A value chosen by the device implementer identifying the name of the
|
|
company, organization, individual, etc. who produced the device, in
|
|
human-readable format. A possible use of this field is to indicate the OEM
|
|
and/or carrier who sold the device. There are no requirements on the specific
|
|
format of this field, except that it MUST NOT be null or the empty string
|
|
("").</td>
|
|
</tr>
|
|
<tr>
|
|
<td>android.os.Build.DEVICE</td>
|
|
<td>A value chosen by the device implementer identifying the specific
|
|
configuration or revision of the body (sometimes called "industrial design")
|
|
of the device. There are no requirements on the specific format of this field,
|
|
except that it MUST NOT be null or the empty string ("").</td>
|
|
</tr>
|
|
<tr>
|
|
<td>android.os.Build.FINGERPRINT</td>
|
|
<td>A string that uniquely identifies this build. It SHOULD be reasonably
|
|
human-readable. It MUST follow this template:
|
|
<br/><code>$(BRAND)/$(PRODUCT)/$(DEVICE)/$(BOARD):$(VERSION.RELEASE)/$(ID)/$(VERSION.INCREMENTAL):$(TYPE)/$(TAGS)</code><br/>
|
|
For example:
|
|
<br/><code>acme/mydevice/generic/generic:2.1-update1/ERC77/3359:userdebug/test-keys</code><br/>
|
|
The fingerprint MUST NOT include spaces. If other fields included in the
|
|
template above have spaces, they SHOULD be replaced with the ASCII underscore
|
|
("_") character in the fingerprint.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>android.os.Build.HOST</td>
|
|
<td>A string that uniquely identifies the host the build was built on, in
|
|
human readable format. There are no requirements on the specific format of
|
|
this field, except that it MUST NOT be null or the empty string ("").</td>
|
|
</tr>
|
|
<tr>
|
|
<td>android.os.Build.ID</td>
|
|
<td>An identifier chosen by the device implementer to refer to a specific
|
|
release, in human readable format. This field can be the same as
|
|
android.os.Build.VERSION.INCREMENTAL, but SHOULD be a value sufficiently
|
|
meaningful for end users to distinguish between software builds. There are no
|
|
requirements on the specific format of this field, except that it MUST NOT be
|
|
null or the empty string ("").</td>
|
|
</tr>
|
|
<tr>
|
|
<td>android.os.Build.MODEL</td>
|
|
<td>A value chosen by the device implementer containing the name of the device
|
|
as known to the end user. This SHOULD be the same name under which the device
|
|
is marketed and sold to end users. There are no requirements on the specific
|
|
format of this field, except that it MUST NOT be null or the empty string
|
|
("").</td>
|
|
</tr>
|
|
<tr>
|
|
<td>android.os.Build.PRODUCT</td>
|
|
<td>A value chosen by the device implementer containing the development name
|
|
or code name of the device. MUST be human-readable, but is not necessarily
|
|
intended for view by end users. There are no requirements on the specific
|
|
format of this field, except that it MUST NOT be null or the empty string
|
|
("").</td>
|
|
</tr>
|
|
<tr>
|
|
<td>android.os.Build.TAGS</td>
|
|
<td>A comma-separated list of tags chosen by the device implementer that
|
|
further distinguish the build. For example, "unsigned,debug". This field MUST
|
|
NOT be null or the empty string (""), but a single tag (such as "release") is
|
|
fine.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>android.os.Build.TIME</td>
|
|
<td>A value representing the timestamp of when the build occurred.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>android.os.Build.TYPE</td>
|
|
<td>A value chosen by the device implementer specifying the runtime
|
|
configuration of the build. This field SHOULD have one of the values
|
|
corresponding to the three typical Android runtime configurations: "user",
|
|
"userdebug", or "eng".</td>
|
|
</tr>
|
|
<tr>
|
|
<td>android.os.Build.USER</td>
|
|
<td>A name or user ID of the user (or automated user) that generated the
|
|
build. There are no requirements on the specific format of this field, except
|
|
that it MUST NOT be null or the empty string ("").</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<h4>3.2.3. Intent Compatibility</h4>
|
|
<p>Android uses Intents to achieve loosely-coupled integration between
|
|
applications. This section describes requirements related to the Intent
|
|
patterns that MUST be honored by device implementations. By "honored", it is
|
|
meant that the device implementer MUST provide an Android Activity or Service
|
|
that specifies a matching Intent filter and binds to and implements correct
|
|
behavior for each specified Intent pattern.</p>
|
|
<h4>3.2.3.1. Core Application Intents</h4>
|
|
<p>The Android upstream project defines a number of core applications, such as
|
|
a phone dialer, calendar, contacts book, music player, and so on. Device
|
|
implementers MAY replace these applications with alternative versions.</p>
|
|
<p>However, any such alternative versions MUST honor the same Intent patterns
|
|
provided by the upstream project. For example, if a device contains an
|
|
alternative music player, it must still honor the Intent pattern issued by
|
|
third-party applications to pick a song.</p>
|
|
<p>The following applications are considered core Android system
|
|
applications:</p>
|
|
<ul>
|
|
<li>Desk Clock</li>
|
|
<li>Browser</li>
|
|
<li>Calendar</li>
|
|
<li>Calculator</li>
|
|
<li>Camera</li>
|
|
<li>Contacts</li>
|
|
<li>Email</li>
|
|
<li>Gallery</li>
|
|
<li>GlobalSearch</li>
|
|
<li>Launcher</li>
|
|
<li>LivePicker (that is, the Live Wallpaper picker application; MAY be omitted
|
|
if the device does not support Live Wallpapers, per Section 3.8.5.)</li>
|
|
<li>Messaging (AKA "Mms")</li>
|
|
<li>Music</li>
|
|
<li>Phone</li>
|
|
<li>Settings</li>
|
|
<li>SoundRecorder</li>
|
|
</ul>
|
|
<p>The core Android system applications include various Activity, or Service
|
|
components that are considered "public".
|
|
That is, the attribute "android:exported" may be absent, or may have the value
|
|
"true".</p>
|
|
<p>For every Activity or Service defined
|
|
in one of the core Android system apps that is not marked as non-public via an
|
|
android:exported attribute with the value "false", device implementations MUST
|
|
include a compontent of the same type implementing the same Intent filter
|
|
patterns as the core Android system app.</p>
|
|
<p>In other words, a device implementation MAY replace core Android system
|
|
apps; however, if it does, the device implementation MUST support all Intent
|
|
patterns defined by each core Android system app being replaced.</p>
|
|
<h4>3.2.3.2. Intent Overrides</h4>
|
|
<p>As Android is an extensible platform, device implementers MUST allow each
|
|
Intent pattern defined in core system apps to be overridden by third-party
|
|
applications. The upstream Android open source project allows this by default;
|
|
device implementers MUST NOT attach special privileges to system applications'
|
|
use of these Intent patterns, or prevent third-party applications from binding
|
|
to and assuming control of these patterns. This prohibition specifically
|
|
includes but is not limited to disabling the "Chooser" user interface which
|
|
allows the user to select between multiple applications which all handle the
|
|
same Intent pattern.</p>
|
|
<div class="cdd-erratum">Note: this section was modified by Erratum EX6580.</div>
|
|
<h4>3.2.3.3. Intent Namespaces</h4>
|
|
<p>Device implementers MUST NOT include any Android component that honors any
|
|
new Intent or Broadcast Intent patterns using an ACTION, CATEGORY, or other
|
|
key string in the android.* namespace. Device implementers MUST NOT include
|
|
any Android components that honor any new Intent or Broadcast Intent patterns
|
|
using an ACTION, CATEGORY, or other key string in a package space belonging to
|
|
another organization. Device implementers MUST NOT alter or extend any of the
|
|
Intent patterns used by the core apps listed in Section 3.2.3.1.</p>
|
|
<p>This prohibition is analogous to that specified for Java language classes
|
|
in Section 3.6.</p>
|
|
<h4>3.2.3.4. Broadcast Intents</h4>
|
|
<p>Third-party applications rely on the platform to broadcast certain Intents
|
|
to notify them of changes in the hardware or software environment.
|
|
Android-compatible devices MUST broadcast the public broadcast Intents in
|
|
response to appropriate system events. Broadcast Intents are described in the
|
|
SDK documentation.</p>
|
|
|
|
<h3>3.3. Native API Compatibility</h3>
|
|
<p>Managed code running in Dalvik can call into native code provided in the
|
|
application .apk file as an ELF .so file compiled for the appropriate device
|
|
hardware architecture. Device implementations MUST include support for code
|
|
running in the managed environment to call into native code, using the
|
|
standard Java Native Interface (JNI) semantics. The following APIs MUST be
|
|
available to native code:</p>
|
|
<ul>
|
|
<li>libc (C library)</li>
|
|
<li>libm (math library)</li>
|
|
<li>JNI interface</li>
|
|
<li>libz (Zlib compression)</li>
|
|
<li>liblog (Android logging)</li>
|
|
<li>Minimal support for C++</li>
|
|
<li>Support for OpenGL, as described below</li>
|
|
</ul>
|
|
<p>Device implementations MUST support OpenGL ES 1.0. Devices that lack
|
|
hardware acceleration MUST implement OpenGL ES 1.0 using a software renderer.
|
|
Device implementations SHOULD implement as much of OpenGL ES 1.1 as the device
|
|
hardware supports. Device implementations SHOULD provide an implementation
|
|
for OpenGL ES 2.0, if the hardware is capable of reasonable performance on
|
|
those APIs.</p>
|
|
<p>These libraries MUST be source-compatible (i.e. header compatible) and
|
|
binary-compatible (for a given processor architecture) with the versions
|
|
provided in Bionic by the Android Open Source project. Since the Bionic
|
|
implementations are not fully compatible with other implementations such as
|
|
the GNU C library, device implementers SHOULD use the Android implementation.
|
|
If device implementers use a different implementation of these libraries, they
|
|
MUST ensure header, binary, and behavioral compatibility.</p>
|
|
<p>Device implementations MUST accurately report the native Application Binary
|
|
Interface (ABI) supported by the device, via the
|
|
<code>android.os.Build.CPU_ABI</code> API. The ABI MUST be one of the entries
|
|
documented in the latest version of the Android NDK, in the file
|
|
<code>docs/CPU-ARCH-ABIS.txt</code>. Note that additional releases of the
|
|
Android NDK may introduce support for additional ABIs.</p>
|
|
<p>Native code compatibility is challenging. For this reason, it should be
|
|
repeated that device implementers are VERY strongly encouraged to use the
|
|
upstream implementations of the libraries listed above, to help ensure
|
|
compatibility.</p>
|
|
|
|
<h3>3.4. Web API Compatibility</h3>
|
|
<p>Many developers and applications rely on the behavior of the
|
|
<code>android.webkit.WebView</code> class [<a
|
|
href="#resources08">Resources, 8</a>]
|
|
for their user interfaces, so the WebView implementation must be
|
|
compatible across Android implementations. The Android Open Source
|
|
implementation uses the WebKit rendering engine to implement the
|
|
WebView.</p>
|
|
<p>Because it is not feasible to develop a comprehensive test suite for a web
|
|
browser, device implementers MUST use the specific upstream build of WebKit in
|
|
the WebView implementation. Specifically:</p>
|
|
<ul>
|
|
<li>WebView MUST use the 530.17 WebKit build from the upstream Android Open
|
|
Source tree for Android 2.1. This build includes a specific set of functionality
|
|
and security fixes for the WebView.</li>
|
|
<li>The user agent string reported by the WebView MUST be in this format:<br/>
|
|
<code>Mozilla/5.0 (Linux; U; Android $(VERSION); $(LOCALE); $(MODEL) Build/$(BUILD)) AppleWebKit/530.17 (KHTML, like Gecko) Version/4.0 Mobile Safari/530.17</code>
|
|
<ul>
|
|
<li>The value of the $(VERSION) string MUST be the same as the value for <code>android.os.Build.VERSION.RELEASE</code></li>
|
|
<li>The value of the $(LOCALE) string SHOULD follow the ISO conventions for country code and language, and SHOULD refer to the current configured locale of the device</li>
|
|
<li>The value of the $(MODEL) string MUST be the same as the value for <code>android.os.Build.MODEL</code></li>
|
|
<li>The value of the $(BUILD) string MUST be the same as the value for <code>android.os.Build.ID</code></li>
|
|
</ul></li>
|
|
</ul>
|
|
<p>Implementations MAY ship a custom user agent string in the standalone
|
|
Browser application. What's more, the standalone Browser MAY be based on an
|
|
alternate browser technology (such as Firefox, Opera, etc.) However, even if an
|
|
alternate Browser application is shipped, the WebView component provided to
|
|
third-party applications MUST be based on WebKit, as above.</p>
|
|
<p>The WebView configuration MUST include support for the HTML5 database,
|
|
application cache, and geolocation APIs [<a href="#resources09">Resources,
|
|
9</a>]. The WebView MUST include support for
|
|
the HTML5 <code><video></code> tag in
|
|
some form. The standalone Browser application (whether based on the upstream
|
|
WebKit Browser application or a third-party replacement) MUST include support
|
|
for the same HTML5 features just listed for WebView.</p>
|
|
|
|
<h3>3.5. API Behavioral Compatibility</h3>
|
|
<p>The behaviors of each of the API types (managed, soft, native, and web)
|
|
must be consistent with the preferred implementation of the upstream Android
|
|
open-source project [<a href="#resources03">Resources, 3</a>]. Some specific areas
|
|
of compatibility are:</p>
|
|
<ul>
|
|
<li>Devices MUST NOT change the behavior or meaning of a standard Intent</li>
|
|
<li>Devices MUST NOT alter the lifecycle or lifecycle semantics of a particular type of system component (such as Service, Activity, ContentProvider, etc.)</li>
|
|
<li>Devices MUST NOT change the semantics of a particular permission</li>
|
|
</ul>
|
|
<p>The above list is not comprehensive, and the onus is on device implementers
|
|
to ensure behavioral compatibility. For this reason, device implementers
|
|
SHOULD use the source code available via the Android Open Source Project where
|
|
possible, rather than re-implement significant parts of the system.</p>
|
|
<p>The Compatibility Test Suite (CTS) tests significant portions of the
|
|
platform for behavioral compatibility, but not all. It is the responsibility
|
|
of the implementer to ensure behavioral compatibility with the Android Open
|
|
Source Project.</p>
|
|
|
|
<h3>3.6. API Namespaces</h3>
|
|
<p>Android follows the package and class namespace conventions defined by the
|
|
Java programming language. To ensure compatibility with third-party
|
|
applications, device implementers MUST NOT make any prohibited modifications
|
|
(see below) to these package namespaces:</p>
|
|
<ul>
|
|
<li>java.*</li>
|
|
<li>javax.*</li>
|
|
<li>sun.*</li>
|
|
<li>android.*</li>
|
|
<li>com.android.*</li>
|
|
</ul>
|
|
<p>Prohibited modifications include:</p>
|
|
<ul>
|
|
<li>Device implementations MUST NOT modify the publicly exposed APIs on the
|
|
Android platform by changing any method or class signatures, or by removing
|
|
classes or class fields.</li>
|
|
<li>Device implementers MAY modify the underlying implementation of the APIs,
|
|
but such modifications MUST NOT impact the stated behavior and Java-language
|
|
signature of any publicly exposed APIs.</li>
|
|
<li>Device implementers MUST NOT add any publicly exposed elements (such as
|
|
classes or interfaces, or fields or methods to existing classes or interfaces)
|
|
to the APIs above.</li>
|
|
</ul>
|
|
<p>A "publicly exposed element" is any construct which is not decorated with
|
|
the "@hide" marker in the upstream Android source code. In other words, device
|
|
implementers MUST NOT expose new APIs or alter existing APIs in the namespaces
|
|
noted above. Device implementers MAY make internal-only modifications, but
|
|
those modifications MUST NOT be advertised or otherwise exposed to
|
|
developers.</p>
|
|
<p>Device implementers MAY add custom APIs, but any such APIs MUST NOT be in a
|
|
namespace owned by or referring to another organization. For instance, device
|
|
implementers MUST NOT add APIs to the com.google.* or similar namespace; only
|
|
Google may do so. Similarly, Google MUST NOT add APIs to other companies'
|
|
namespaces.</p>
|
|
<p>If a device implementer proposes to improve one of the package namespaces
|
|
above (such as by adding useful new functionality to an existing API, or
|
|
adding a new API), the implementer SHOULD visit source.android.com and begin
|
|
the process for contributing changes and code, according to the information on
|
|
that site.</p>
|
|
<p>Note that the restrictions above correspond to standard conventions for
|
|
naming APIs in the Java programming language; this section simply aims to
|
|
reinforce those conventions and make them binding through inclusion in this
|
|
compatibility definition.</p>
|
|
|
|
<h3>3.7. Virtual Machine Compatibility</h3>
|
|
<p>Device implementations MUST support the full Dalvik Executable (DEX)
|
|
bytecode specification and Dalvik Virtual Machine semantics [<a
|
|
href="#resources10">Resources, 10</a>].</p>
|
|
<p>Device implementations MUST configure Dalvik to allocate at least 16MB of
|
|
memory to each application on devices with screens classified as medium- or
|
|
low-density. Device implementations MUST configure Dalvik to allocate at least
|
|
24MB of memory to each application on devices with screens classified as
|
|
high-density. Note that device implementations MAY allocate more memory than
|
|
these figures, but are not required to.</p>
|
|
|
|
<h3>3.8. User Interface Compatibility</h3>
|
|
<p>The Android platform includes some developer APIs that allow developers to
|
|
hook into the system user interface. Device implementations MUST incorporate
|
|
these standard UI APIs into custom user interfaces they develop, as explained
|
|
below.</p>
|
|
<h4>3.8.1. Widgets</h4>
|
|
<p>Android defines a component type and corresponding API and lifecycle that
|
|
allows applications to expose an "AppWidget" to the end user [<a
|
|
href="#resources11">Resources, 11</a>].
|
|
The Android Open Source reference release includes a Launcher application that
|
|
includes user interface elements allowing the user to add, view, and remove
|
|
AppWidgets from the home screen.</p>
|
|
<p>Device implementers MAY substitute an alternative to the reference Launcher
|
|
(i.e. home screen). Alternative Launchers SHOULD include built-in support for
|
|
AppWidgets, and expose user interface elements to add, configure, view, and remove
|
|
AppWidgets directly within the Launcher. Alternative Launchers MAY omit these
|
|
user interface elements; however, if they are omitted, the device implementer
|
|
MUST provide a separate application accessible from the Launcher that allows
|
|
users to add, configure, view, and remove AppWidgets.</p>
|
|
<h4>3.8.2. Notifications</h4>
|
|
<p>Android includes APIs that allow developers to notify users of notable
|
|
events [<a href="#resources12">Resources, 12</a>]. Device implementers MUST provide support for each
|
|
class of notification so defined; specifically: sounds, vibration, light and
|
|
status bar.</p>
|
|
<p>Additionally, the implementation MUST correctly render all resources
|
|
(icons, sound files, etc.) provided for in the APIs [<a
|
|
href="#resources13">Resources, 13</a>], or in the
|
|
Status Bar icon style guide [<a href="#resources14">Resources, 14</a>]. Device implementers MAY provide
|
|
an alternative user experience for notifications than that provided by the
|
|
reference Android Open Source implementation; however, such alternative
|
|
notification systems MUST support existing notification resources, as
|
|
above.</p>
|
|
<h4>3.8.3. Search</h4>
|
|
<p>Android includes APIs [<a href="#resources15">Resources, 15</a>] that allow developers to incorporate
|
|
search into their applications, and expose their application's data into the
|
|
global system search. Generally speaking, this functionality consists of a
|
|
single, system-wide user interface that allows users to enter queries,
|
|
displays suggestions as users type, and displays results. The Android APIs
|
|
allow developers to reuse this interface to provide search within their own
|
|
apps, and allow developers to supply results to the common global search user
|
|
interface.</p>
|
|
<p>Device implementations MUST include a single, shared, system-wide search
|
|
user interface capable of real-time suggestions in response to user input.
|
|
Device implementations MUST implement the APIs that allow developers to reuse
|
|
this user interface to provide search within their own applications. Device
|
|
implementations MUST implement the APIs that allow third-party applications to
|
|
add suggestions to the search box when it is run in global search mode. If no
|
|
third-party applications are installed that make use of this functionality,
|
|
the default behavior SHOULD be to display web search engine results and
|
|
suggestions.</p>
|
|
<p>Device implementations MAY ship alternate search user interfaces, but
|
|
SHOULD include a hard or soft dedicated search button, that can be used at any
|
|
time within any app to invoke the search framework, with the behavior provided
|
|
for in the API documentation.</p>
|
|
<h4>3.8.4. Toasts</h4>
|
|
<p>Applications can use the "Toast" API (defined in [<a
|
|
href="#resources16">Resources, 16</a>]) to
|
|
display short non-modal strings to the end user, that disappear after a brief
|
|
period of time. Device implementations MUST display Toasts from applications
|
|
to end users in some high-visibility manner.</p>
|
|
<h4>3.8.5. Live Wallpapers</h4>
|
|
<p>Android defines a component type and corresponding API and lifecycle that
|
|
allows applications to expose one or more "Live Wallpapers" to the end user
|
|
[<a href="#resources17">Resources, 17</a>]. Live Wallpapers are animations,
|
|
patterns, or similar images with limited input capabilities that display as a
|
|
wallpaper, behind other applications.</p>
|
|
<p>Hardware is considered capable of reliably running live wallpapers if it
|
|
can run all live wallpapers, with no limitations on functionality, at a
|
|
reasonable framerate with no adverse affects on other applications. If
|
|
limitations in the hardware cause wallpapers and/or applications to crash,
|
|
malfunction, consume excessive CPU or battery power, or run at unacceptably
|
|
low frame rates, the hardware is considered incapable of running live
|
|
wallpaper. As an example, some live wallpapers may use an Open GL 1.0 or 2.0
|
|
context to render their content. Live wallpaper will not run reliably on
|
|
hardware that does not support multiple OpenGL contexts because the live
|
|
wallpaper use of an OpenGL context may conflict with other applications that
|
|
also use an OpenGL context. </p>
|
|
<p>Device implemenations capable of running live wallpapers reliably as
|
|
described above SHOULD implement live wallpapers. Device implementations
|
|
determined to not run live wallpapers reliably as described above MUST NOT
|
|
implement live wallpapers.</p>
|
|
|
|
<h2>4. Reference Software Compatibility</h2>
|
|
<p>Device implementers MUST test implementation compatibility using the
|
|
following open-source applications:</p>
|
|
<ul>
|
|
<li>Calculator (included in SDK)</li>
|
|
<li>Lunar Lander (included in SDK)</li>
|
|
<li>The "Apps for Android" applications [<a href="#resources18">Resources, 18</a>].</li>
|
|
</ul>
|
|
<p>Each app above MUST launch and behave correctly on the implementation, for
|
|
the implementation to be considered compatible.</p>
|
|
<p>Additionally, device implementations MUST test each menu item (including all
|
|
sub-menus) of each of these smoke-test applications:</p>
|
|
<ul>
|
|
<li>ApiDemos (included in SDK)</li>
|
|
<li>ManualSmokeTests (included in CTS)</li>
|
|
</ul>
|
|
<p>Each test case in the applications above MUST run correctly on the device
|
|
implementation.</p>
|
|
|
|
<h2>5. Application Packaging Compatibility</h2>
|
|
<p>Device implementations MUST install and run Android ".apk" files as
|
|
generated by the "aapt" tool included in the official Android SDK [<a
|
|
href="#resources19">Resources, 19</a>].</p>
|
|
<p>Devices implementations MUST NOT extend either the .apk [<a
|
|
href="#resources20">Resources, 20</a>], Android Manifest [<a
|
|
href="#resources21">Resources, 21</a>],
|
|
or Dalvik bytecode [<a href="#resources10">Resources, 10</a>] formats in such
|
|
a way that would prevent those files from
|
|
installing and running correctly on other compatible devices. Device
|
|
implementers SHOULD use the reference upstream implementation of Dalvik, and
|
|
the reference implementation's package management system.</p>
|
|
|
|
<h2>6. Multimedia Compatibility</h2>
|
|
<p>Device implemenations MUST support the following multimedia codecs. All of
|
|
these codecs are provided as software implementations in the preferred Android
|
|
implementation from the Android Open Source Project.</p>
|
|
<p>Please note that neither Google nor the Open Handset Alliance make any
|
|
representation that these codecs are unencumbered by third-party patents.
|
|
Those intending to use this source code in hardware or software products are
|
|
advised that implementations of this code, including in open source software
|
|
or shareware, may require patent licenses from the relevant patent
|
|
holders.</p>
|
|
<table><tbody>
|
|
<tr>
|
|
<td rowspan="11"><b>Audio</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>Name</b></td>
|
|
<td><b>Encoder</b></td>
|
|
<td><b>Decoder</b></td>
|
|
<td><b>Details</b></td>
|
|
<td><b>File/Container Format</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td>AAC LC/LTP</td>
|
|
<td> </td>
|
|
<td>X</td>
|
|
<td rowspan="3">Mono/Stereo content in any combination of standard bit rates up to 160 kbps and sampling rates between 8 to 48kHz</td>
|
|
<td rowspan="3">3GPP (.3gp) and MPEG-4 (.mp4, .m4a). No support for raw AAC (.aac)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>HE-AACv1 (AAC+)</td>
|
|
<td> </td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr>
|
|
<td>HE-AACv2 (enhanced AAC+)</td>
|
|
<td> </td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr>
|
|
<td>AMR-NB</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>4.75 to 12.2 kbps sampled @ 8kHz</td>
|
|
<td>3GPP (.3gp)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>AMR-WB</td>
|
|
<td> </td>
|
|
<td>X</td>
|
|
<td>9 rates from 6.60 kbit/s to 23.85 kbit/s sampled @ 16kHz</td>
|
|
<td>3GPP (.3gp)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>MP3</td>
|
|
<td> </td>
|
|
<td>X</td>
|
|
<td>Mono/Stereo 8-320Kbps constant (CBR) or variable bit-rate (VBR)</td>
|
|
<td>MP3 (.mp3)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>MIDI</td>
|
|
<td> </td>
|
|
<td>X</td>
|
|
<td>MIDI Type 0 and 1. DLS Version 1 and 2. XMF and Mobile XMF. Support for ringtone formats RTTTL/RTX, OTA, and iMelody</td>
|
|
<td>Type 0 and 1 (.mid, .xmf, .mxmf). Also RTTTL/RTX (.rtttl, .rtx), OTA (.ota), and iMelody (.imy)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Ogg Vorbis</td>
|
|
<td> </td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td>Ogg (.ogg)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>PCM</td>
|
|
<td> </td>
|
|
<td>X</td>
|
|
<td>8- and 16-bit linear PCM (rates up to limit of hardware)</td>
|
|
<td>WAVE (.wav)</td>
|
|
</tr>
|
|
<tr>
|
|
<td rowspan="5"><b>Image</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td>JPEG</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>base+progressive</td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td>GIF</td>
|
|
<td> </td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td>PNG</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td>BMP</td>
|
|
<td> </td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td rowspan="4"><b>Video</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td>H.263</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td>3GPP (.3gp) files</td>
|
|
</tr>
|
|
<tr>
|
|
<td>H.264</td>
|
|
<td> </td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td>3GPP (.3gp) and MPEG-4 (.mp4) files</td>
|
|
</tr>
|
|
<tr>
|
|
<td>MPEG4 Simple Profile</td>
|
|
<td> </td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td>3GPP (.3gp) file</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Note that the table above does not list specific bitrate requirements for
|
|
most video codecs. The reason for this is that in practice, current device
|
|
hardware does not necessarily support bitrates that map exactly to the
|
|
required bitrates specified by the relevant standards. Instead, device
|
|
implementations SHOULD support the highest bitrate practical on the hardware,
|
|
up to the limits defined by the specifications.</p>
|
|
|
|
<h2>7. Developer Tool Compatibility</h2>
|
|
<p>Device implemenations MUST support the Android Developer Tools provided in
|
|
the Android SDK. Specifically, Android-compatible devices MUST be compatible
|
|
with:</p>
|
|
<ul>
|
|
<li><b>Android Debug Bridge (known as adb)</b> [<a href="#resources19">Resources, 19</a>]<br/>
|
|
Device implementations MUST support all <code>adb</code> functions as
|
|
documented in the Android SDK. The device-side <code>adb</code> daemon SHOULD
|
|
be inactive by default, but there MUST be a user-accessible mechanism to turn
|
|
on the Android Debug Bridge.</li>
|
|
<li><b>Dalvik Debug Monitor Service (known as ddms)</b> [<a href="#resources19">Resources, 19</a>]<br/>
|
|
Device implementations MUST support all <code>ddms</code> features as documented in the
|
|
Android SDK. As <code>ddms</code> uses <code>adb</code>, support for
|
|
<code>ddms</code> SHOULD be inactive by default,
|
|
but MUST be supported whenever the user has activated the Android Debug
|
|
Bridge, as above.</li>
|
|
<li><b>Monkey</b> [<a href="#resources22">Resources, 22</a>]<br/>
|
|
Device implementations MUST include the Monkey framework, and make it
|
|
available for applications to use.</li>
|
|
</ul>
|
|
|
|
<h2>8. Hardware Compatibility</h2>
|
|
<p>Android is intended to support device implementers creating innovative form
|
|
factors and configurations. At the same time Android developers expect
|
|
certain hardware, sensors and APIs across all Android device. This section
|
|
lists the hardware features that all Android 2.1 compatible devices must
|
|
support.</p>
|
|
<p>If a device includes a particular hardware component that has a
|
|
corresponding API for third-party developers, the device implementation MUST
|
|
implement that API as defined in the Android SDK documentation. If an API in
|
|
the SDK interacts with a hardware component that is stated to be optional and the device
|
|
implementation does not possess that component:</p>
|
|
<ul>
|
|
<li>class definitions for the component's APIs MUST be present</li>
|
|
<li>the API's behaviors MUST be implemented as no-ops in some reasonable fashion</li>
|
|
<li>API methods MUST return null values where permitted by the SDK documentation</li>
|
|
<li>API methods MUST return no-op implementations of classes where null values are not permitted by the SDK documentation</li>
|
|
</ul>
|
|
<p>A typical example of a scenario where these requirements apply is the
|
|
telephony API: even on non-phone devices, these APIs must be implemented as
|
|
reasonable no-ops.</p>
|
|
<p>Device implementations MUST accurate report accurate hardware configuration
|
|
information via the <code>getSystemAvailableFeatures()</code> and
|
|
<code>hasSystemFeature(String)</code> methods on the
|
|
<code>android.content.pm.PackageManager</code> class.</p>
|
|
|
|
<h3>8.1. Display</h3>
|
|
<p>Android 2.1 includes facilities that perform certain automatic scaling and
|
|
transformation operations under some circumstances, to ensure that third-party
|
|
applications run reasonably well on a variety of hardware configurations [<a
|
|
href="#resources23">Resources, 23</a>]. Devices MUST properly implement these
|
|
behaviors, as detailed in this section.</p>
|
|
<p>For Android 2.1, this are the most common display configurations:</p>
|
|
<table><tbody>
|
|
<tr>
|
|
<td>Screen Type</td>
|
|
<td>Width (Pixels)</td>
|
|
<td>Height (Pixels)</td>
|
|
<td>Diagonal Length Range (inches)</td>
|
|
<td>Screen Size Group</td>
|
|
<td>Screen Density Group</td>
|
|
</tr>
|
|
<tr>
|
|
<td>QVGA</td>
|
|
<td>240</td>
|
|
<td>320</td>
|
|
<td>2.6 - 3.0</td>
|
|
<td>Small</td>
|
|
<td>Low</td>
|
|
</tr>
|
|
<tr>
|
|
<td>WQVGA</td>
|
|
<td>240</td>
|
|
<td>400</td>
|
|
<td>3.2 - 3.5</td>
|
|
<td>Normal</td>
|
|
<td>Low</td>
|
|
</tr>
|
|
<tr>
|
|
<td>FWQVGA</td>
|
|
<td>240</td>
|
|
<td>432</td>
|
|
<td>3.5 - 3.8</td>
|
|
<td>Normal</td>
|
|
<td>Low</td>
|
|
</tr>
|
|
<tr>
|
|
<td>HVGA</td>
|
|
<td>320</td>
|
|
<td>480</td>
|
|
<td>3.0 - 3.5</td>
|
|
<td>Normal</td>
|
|
<td>Medium</td>
|
|
</tr>
|
|
<tr>
|
|
<td>WVGA</td>
|
|
<td>480</td>
|
|
<td>800</td>
|
|
<td>3.3 - 4.0</td>
|
|
<td>Normal</td>
|
|
<td>High</td>
|
|
</tr>
|
|
<tr>
|
|
<td>FWVGA</td>
|
|
<td>480</td>
|
|
<td>854</td>
|
|
<td>3.5 - 4.0</td>
|
|
<td>Normal</td>
|
|
<td>High</td>
|
|
</tr>
|
|
<tr>
|
|
<td>WVGA </td>
|
|
<td>480 </td>
|
|
<td>800 </td>
|
|
<td>4.8 - 5.5 </td>
|
|
<td>Large </td>
|
|
<td>Medium</td>
|
|
</tr>
|
|
<tr>
|
|
<td>FWVGA</td>
|
|
<td>480</td>
|
|
<td>854</td>
|
|
<td>5.0 - 5.8</td>
|
|
<td>Large</td>
|
|
<td>Medium</td>
|
|
</tr>
|
|
</tbody></table>
|
|
|
|
<p>Device implementations corresponding to one of the standard configurations
|
|
above MUST be configured to report the indicated screen size to applications
|
|
via the <code>android.content.res.Configuration</code> [<a href="#resources24">Resources,
|
|
24</a>] class.</p>
|
|
<p>Some .apk packages have manifests that do not identify them as supporting a
|
|
specific density range. When running such applications, the following
|
|
constraints apply:</p>
|
|
<ul>
|
|
<li>Device implementations MUST interpret resources in a .apk that lack a
|
|
density qualifier as defaulting to "medium" (known as "mdpi" in the SDK
|
|
documentation.)</li>
|
|
<li>When operating on a "low" density screen, device implementations MUST
|
|
scale down medium/mdpi assets by a factor of 0.75.</li>
|
|
<li>When operating on a "high" density screen, device implementations MUST
|
|
scale up medium/mdpi assets by a factor of 1.5.</li>
|
|
<li>Device implementations MUST NOT scale assets within a density range, and
|
|
MUST scale assets by exactly these factors between density ranges.</li>
|
|
</ul>
|
|
|
|
<h4>8.1.2. Non-Standard Display Configurations</h4>
|
|
<p>Display configurations that do not match one of the standard configurations
|
|
listed in Section 8.1.1 require additional consideration and work to be
|
|
compatible. Device implementers MUST contact Android Compatibility Team as
|
|
provided for in Section 12 to obtain classifications for screen-size bucket,
|
|
density, and scaling factor. When provided with this information, device
|
|
implementations MUST implement them as specified.</p>
|
|
<p>Note that some display configurations (such as very large or very small
|
|
screens, and some aspect ratios) are fundamentally incompatible with Android
|
|
2.1; therefore device implementers are encouraged to contact Android
|
|
Compatibility Team as early as possible in the development process.</p>
|
|
<h4>8.1.3. Display Metrics</h4>
|
|
<p>Device implementations MUST report correct valuesfor all display metrics
|
|
defined in <code>android.util.DisplayMetrics</code> [<a
|
|
href="#resources25">Resources, 25</a>].</p>
|
|
|
|
<h3>8.2. Keyboard</h3>
|
|
<p>Device implementations:</p>
|
|
<ul>
|
|
<li>MUST include support for the Input Management Framework (which allows third party developers to create Input Management Engines -- i.e. soft keyboard) as detailed at developer.android.com</li>
|
|
<li>MUST provide at least one soft keyboard implementation (regardless of whether a hard keyboard is present)</li>
|
|
<li>MAY include additional soft keyboard implementations</li>
|
|
<li>MAY include a hardware keyboard</li>
|
|
<li>MUST NOT include a hardware keyboard that does not match one of the
|
|
formats specified in <code>android.content.res.Configuration.keyboard</code>
|
|
[<a href="#resources24">Resources, 24</a>] (that is, QWERTY, or 12-key)</li>
|
|
</ul>
|
|
<h3>8.3. Non-touch Navigation</h3>
|
|
<p>Device implementations:</p>
|
|
<ul>
|
|
<li>MAY omit a non-touch navigation options (that is, may omit a trackball, d-pad, or wheel)</li>
|
|
<li>MUST report the correct value for
|
|
<code>android.content.res.Configuration.navigation</code> [<a href="#resources24">Resources, 24</a>]</li>
|
|
</ul>
|
|
<h3>8.4. Screen Orientation</h3>
|
|
<p>Compatible devices MUST support dynamic orientation by applications to
|
|
either portrait or landscape screen orientation. That is, the device must
|
|
respect the application's request for a specific screen orientation. Device
|
|
implementations MAY select either portrait or landscape orientation as the
|
|
default.</p>
|
|
<p>Devices MUST report the correct value for the device's current orientation,
|
|
whenever queried via the android.content.res.Configuration.orientation,
|
|
android.view.Display.getOrientation(), or other APIs.</p>
|
|
|
|
<h3>8.5. Touchscreen input</h3>
|
|
<p>Device implementations:</p>
|
|
<ul>
|
|
<li>MUST have a touchscreen</li>
|
|
<li>MAY have either capacative or resistive touchscreen</li>
|
|
<li>MUST report the value of <code>android.content.res.Configuration</code>
|
|
[<a href="#resources24">Resources, 24</a>]
|
|
reflecting corresponding to the type of the specific touchscreen on the
|
|
device</li>
|
|
</ul>
|
|
|
|
<h3>8.6. USB</h3>
|
|
<p>Device implementations:</p>
|
|
<ul>
|
|
<li>MUST implement a USB client, connectable to a USB host with a standard
|
|
USB-A port</li>
|
|
<li>MUST implement the Android Debug Bridge over USB (as described in Section
|
|
7)</li>
|
|
<li>MUST implement the USB mass storage specification, to allow a host
|
|
connected to the device to access the contents of the /sdcard volume </li>
|
|
<li>SHOULD use the micro USB form factor on the device side</li>
|
|
<li>MAY include a non-standard port on the device side, but if so MUST ship
|
|
with a cable capable of connecting the custom pinout to standard USB-A
|
|
port</li>
|
|
</ul>
|
|
|
|
<h3>8.7. Navigation keys</h3>
|
|
<p>The Home, Menu and Back functions are essential to the Android navigation
|
|
paradigm. Device implementations MUST make these functions available to the
|
|
user at all times, regardless of application state. These functions SHOULD be
|
|
implemented via dedicated buttons. They MAY be implemented using software,
|
|
gestures, touch panel, etc., but if so they MUST be always accessible and not
|
|
obscure or interfere with the available application display area.</p>
|
|
<p>Device implementers SHOULD also provide a dedicated search key. Device
|
|
implementers MAY also provide send and end keys for phone calls.</p>
|
|
|
|
<h3>8.8. Wireless Data Networking</h3>
|
|
<p>Device implementations MUST include support for wireless high-speed data
|
|
networking. Specifically, device implementations MUST include support for at
|
|
least one wireless data standard capable of 200Kbit/sec or greater. Examples of
|
|
technologies that satisfy this requirement include EDGE, HSPA, EV-DO, 802.11g, etc.</p>
|
|
<p>If a device implementation includes a particular modality for which the
|
|
Android SDK includes an API (that is, WiFi, GSM, or CDMA), the implementation
|
|
MUST support the API.</p>
|
|
<p>Devices MAY implement more than one form of wireless data connectivity.
|
|
Devices MAY implement wired data connectivity (such as Ethernet), but MUST
|
|
nonetheless include at least one form of wireless connectivity, as above.</p>
|
|
<h3>8.9. Camera</h3>
|
|
<p>Device implementations MUST include a camera. The included camera:</p>
|
|
<ul>
|
|
<li>MUST have a resolution of at least 2 megapixels</li>
|
|
<li>SHOULD have either hardware auto-focus, or software auto-focus implemented
|
|
in the camera driver (transparent to application software)</li>
|
|
<li>MAY have fixed-focus or EDOF (extended depth of field) hardware</li>
|
|
<li>MAY include a flash. If the Camera includes a flash, the flash lamp MUST
|
|
NOT be lit while an android.hardware.Camera.PreviewCallback instance has been
|
|
registered on a Camera preview surface, unless the application has explicitly
|
|
enabled the flash by enabling the <code>FLASH_MODE_AUTO</code> or
|
|
<code>FLASH_MODE_ON</code> attributes of a <code>Camera.Parameters</code>
|
|
object. Note that this constraint does not apply to the device's built-in
|
|
system camera application, but only to third-party applications using
|
|
<code>Camera.PreviewCallback</code>.</li>
|
|
</ul>
|
|
<p>Device implementations MUST implement the following behaviors for the
|
|
camera-related APIs:</p>
|
|
<ol>
|
|
<li>If an application has never called
|
|
android.hardware.Camera.Parameters.setPreviewFormat(int), then the device MUST
|
|
use android.hardware.PixelFormat.YCbCr_420_SP for preview data provided to
|
|
application callbacks.</li>
|
|
<li>If an application registers an android.hardware.Camera.PreviewCallback
|
|
instance and the system calls the onPreviewFrame() method when the preview
|
|
format is YCbCr_420_SP, the data in the byte[] passed into onPreviewFrame()
|
|
must further be in the NV21 encoding format. (This is the format used natively
|
|
by the 7k hardware family.) That is, NV21 MUST be the default.</li>
|
|
</ol>
|
|
<p>Device implementations MUST implement the full Camera API included in the
|
|
Android 2.1 SDK documentation [<a href="#resources26">Resources, 26</a>]),
|
|
regardless of whether the device includes hardware autofocus or other
|
|
capabilities. For instance, cameras that lack autofocus MUST still call any
|
|
registered <code>android.hardware.Camera.AutoFocusCallback</code> instances (even though
|
|
this has no relevance to a non-autofocus camera.)</p>
|
|
<p>Device implementations MUST recognize and honor each parameter name defined
|
|
as a constant on the <code>android.hardware.Camera.Parameters</code> class, if the
|
|
underlying hardware supports the feature. If the device hardware does not
|
|
support a feature, the API must behave as documented. Conversely, Device
|
|
implementations MUST NOT honor or recognize string constants passed
|
|
to the <code>android.hardware.Camera.setParameters()</code> method other than
|
|
those documented as constants on the
|
|
<code>android.hardware.Camera.Parameters</code>, unless the constants are
|
|
prefixed with a string indicating the name of the device implementer. That is,
|
|
device implementations MUST support all standard Camera parameters if the
|
|
hardware allows, and MUST NOT support custom Camera parameter types unless
|
|
the parameter names are clearly indicated via a string prefix to be non-standard.</p>
|
|
|
|
<h3>8.10. Accelerometer</h3>
|
|
<p>Device implementations MUST include a 3-axis accelerometer and MUST be able
|
|
to deliver events at 50 Hz or greater. The coordinate system used by the
|
|
accelerometer MUST comply with the Android sensor coordinate system as detailed
|
|
in the Android APIs (see [<a href="#resources27">Resources, 27</a>]).</p>
|
|
|
|
<h3>8.11. Compass</h3>
|
|
<p>Device implementations MUST include a 3-axis compass and MUST be able to
|
|
deliver events 10 Hz or greater. The coordinate system used by the compass
|
|
MUST comply with the Android sensor coordinate system as defined in the Android
|
|
API (see [<a href="#resources27">Resources, 27</a>]).</p>
|
|
|
|
<h3>8.12. GPS</h3>
|
|
<p>Device implementations MUST include a GPS, and SHOULD include some form of
|
|
"assisted GPS" technique to minimize GPS lock-on time.</p>
|
|
|
|
<h3>8.13. Telephony</h3>
|
|
<p>Android 2.1 MAY be used on devices that do not include telephony hardware.
|
|
That is, Android 2.1 is compatible with devices that are not phones.
|
|
However, if a device implementation does include GSM or CDMA telephony, it
|
|
MUST implement the full support for the API for that technology. Device
|
|
implementations that do not include telephony hardware MUST implement the full
|
|
APIs as no-ops.</p>
|
|
<p>See also Section 8.8, Wireless Data Networking.</p>
|
|
|
|
<h3>8.14. Memory and Storage</h3>
|
|
<p>Device implementations MUST have at least 92MB of memory available to the
|
|
kernel and userspace. The 92MB MUST be in addition to any memory dedicated to
|
|
hardware components such as radio, memory, and so on that is not under the
|
|
kernel's control.</p>
|
|
<p>Device implementations MUST have at least 150MB of non-volatile storage
|
|
available for user data. That is, the <code>/data</code> partition must be at
|
|
least 150MB.</p>
|
|
<div class="cdd-erratum">Note: this section was modified by Erratum EX6580.</div>
|
|
|
|
<h3>8.15. Application Shared Storage</h3>
|
|
<p>Device implementations MUST offer shared storage for applications. The
|
|
shared storage provided MUST be at least 2GB in size.</p>
|
|
<p>Device implementations MUST be configured with shared storage mounted by
|
|
default, "out of the box". If the shared storage is not mounted on the Linux
|
|
path <code>/sdcard</code>, then the device MUST include a Linux symbolic link
|
|
from <code>/sdcard</code> to the actual mount point.</p>
|
|
<p>Device implementations MUST enforce as documented the
|
|
<code>android.permission.WRITE_EXTERNAL_STORAGE</code> permission on this
|
|
shared storage. Shared storage MUST otherwise be writable by any application
|
|
that obtains that permission.</p>
|
|
<p>Device implementations MAY have hardware for user-accessible removable
|
|
storage, such as a Secure Digital card. Alternatively, device implementations
|
|
MAY allocate internal (non-removable) storage as shared storage for apps.</p>
|
|
<p>Regardless of the form of shared storage used, the shared storage MUST
|
|
implement USB mass storage, as described in Section 8.6. As shipped out of the
|
|
box, the shared storage MUST be mounted with the FAT filesystem.</p>
|
|
<p>It is illustrative to consider two common examples. If a device
|
|
implementation includes an SD card slot to satisfy the shared storage
|
|
requirement, a FAT-formatted SD card 2GB in size or larger MUST be included
|
|
with the device as sold to users, and MUST be mounted by default.
|
|
Alternatively, if a device implementation uses internal fixed storage to
|
|
satisfy this requirement, that storage MUST be 2GB in size or larger and
|
|
mounted on <code>/sdcard</code> (or <code>/sdcard</code> MUST be a symbolic
|
|
link to the physical location if it is mounted elsewhere.)</p>
|
|
<div class="cdd-erratum">Note: this section was added by Erratum EX6580.</div>
|
|
|
|
<h3>8.16. Bluetooth</h3>
|
|
<p>Device implementations MUST include a Bluetooth transceiver. Device
|
|
implementations MUST enable the RFCOMM-based Bluetooth API as described in the
|
|
SDK documentation [<a href="#resources29">Resources, 29</a>]. Device
|
|
implementations SHOULD implement relevant Bluetooth profiles, such as A2DP,
|
|
AVRCP, OBEX, etc. as appropriate for the device.</p>
|
|
<div class="cdd-erratum">Note: this section was added by Erratum EX6580.</div>
|
|
|
|
<h2>9. Performance Compatibility</h2>
|
|
<p>One of the goals of the Android Compatibility Program is to enable
|
|
consistent application experience to consumers. Compatible implementations
|
|
must ensure not only that applications simply run correctly on the device, but
|
|
that they do so with reasonable performance and overall good user experience.
|
|
Device implementations MUST meet the key performance metrics of an Android 2.1
|
|
compatible device defined in the table below:</p>
|
|
<table><tbody><tr>
|
|
<td><b>Metric</b></td>
|
|
<td><b>Performance Threshold</b></td>
|
|
<td><b>Comments</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Application Launch Time</td>
|
|
<td>The following applications should launch within the specified time.<ul>
|
|
<li>Browser: less than 1300ms</li>
|
|
<li>MMS/SMS: less than 700ms</li>
|
|
<li>AlarmClock: less than 650ms</li>
|
|
</ul></td>
|
|
<td>The launch time is measured as the total time to
|
|
complete loading the default activity for the application, including the time
|
|
it takes to start the Linux process, load the Android package into the Dalvik
|
|
VM, and call onCreate.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Simultaneous Applications</td>
|
|
<td>When multiple applications have been launched, re-launching an
|
|
already-running application after it has been launched must take less than the
|
|
original launch time.</td>
|
|
<td> </td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h2>10. Security Model Compatibility</h2>
|
|
<p>Device implementations MUST implement a security model consistent with the
|
|
Android platform security model as defined in Security and Permissions
|
|
reference document in the APIs [<a href="#resources28">Resources, 28</a>] in the
|
|
Android developer documentation. Device implementations MUST support
|
|
installation of self-signed applications without requiring any additional
|
|
permissions/certificates from any third parties/authorities. Specifically,
|
|
compatible devices MUST support the security mechanisms described in the
|
|
follow sub-sections.</p>
|
|
<h3>10.1. Permissions</h3>
|
|
<p>Device implementations MUST support the Android permissions model as
|
|
defined in the Android developer documentation [<a
|
|
href="#resources28">Resources, 28</a>]. Specifically,
|
|
implementations MUST enforce each permission defined as described in the SDK
|
|
documentation; no permissions may be omitted, altered, or ignored.
|
|
Implementations MAY add additional permissions, provided the new permission ID
|
|
strings are not in the android.* namespace.</p>
|
|
<h3>10.2. UID and Process Isolation</h3>
|
|
<p>Device implementations MUST support the Android application sandbox model,
|
|
in which each application runs as a unique Unix-style UID and in a separate
|
|
process. Device implementations MUST support running multiple applications as
|
|
the same Linux user ID, provided that the applications are properly signed and
|
|
constructed, as defined in the Security and Permissions reference [<a
|
|
href="#resources28">Resources, 28</a>].</p>
|
|
<h3>10.3. Filesystem Permissions</h3>
|
|
<p>Device implementations MUST support the Android file access permissions
|
|
model as defined in as defined in the Security and Permissions reference [<a
|
|
href="#resources28">Resources, 28</a>].</p>
|
|
|
|
<h2>11. Compatibility Test Suite</h2>
|
|
<p>Device implementations MUST pass the Android Compatibility Test Suite (CTS)
|
|
[<a href="#resources02">Resources, 2</a>] available from the Android Open Source
|
|
Project, using the final shipping software on the device. Additionally, device
|
|
implementers SHOULD use the reference implementation in the Android Open
|
|
Source tree as much as possible, and MUST ensure compatibility in cases of
|
|
ambiguity in CTS and for any reimplementations of parts of the reference
|
|
source code.</p>
|
|
<p>The CTS is designed to be run on an actual device. Like any software, the
|
|
CTS may itself contain bugs. The CTS will be versioned independently of this
|
|
Compatibility Definition, and multiple revisions of the CTS may be released
|
|
for Android 2.1. Device implementations MUST pass the latest CTS version
|
|
available at the time the device software is completed.</p>
|
|
|
|
<h2>12. Updatable Software</h2>
|
|
<p>Device implementations MUST include a mechanism to replace the entirety of
|
|
the system software. The mechanism need not perform "live" upgrades -- that
|
|
is, a device restart MAY be required.</p>
|
|
<p>Any method can be used, provided that it can replace the entirety of the
|
|
software preinstalled on the device. For instance, any of the following
|
|
approaches will satisfy this requirement:</p>
|
|
<ul>
|
|
<li>Over-the-air (OTA) downloads with offline update via reboot</li>
|
|
<li>"Tethered" updates over USB from a host PC</li>
|
|
<li>"Offline" updates via a reboot and update from a file on removable
|
|
storage</li>
|
|
</ul>
|
|
<p>The update mechanism used MUST support updates without wiping user data.
|
|
Note that the upstream Android software includes an update mechanism that
|
|
satisfies this requirement.</p>
|
|
<p>If an error is found in a device implementation after it has been released
|
|
but within its reasonable product lifetime that is determined in consultation
|
|
with the Android Compatibility Team to affect the compatibility of thid-party
|
|
applications, the device implementer MUST correct the error via a software
|
|
update available that can be applied per the mechanism just described.</p>
|
|
|
|
<h2>13. Contact Us</h2>
|
|
<p>You can contact the document authors at <a
|
|
href="mailto:compatibility@android.com">compatibility@android.com</a> for
|
|
clarifications and to bring up any issues that you think the document does not
|
|
cover.</p>
|
|
</body>
|
|
</html>
|