版权所有 © 2010，谷歌公司。保留所有权利。
兼容性@android.com
一、简介
本文档列举了为使手机与 Android 2.1 兼容而必须满足的要求。
“必须”、“不得”、“要求”、“应”、“不应”、“应该”、“不应”、“推荐”、“可能”和“可选”的使用符合 IETF 标准在 RFC2119 [资源，1 ] 中定义。
在本文档中，“设备实施者”或“实施者”是指开发运行 Android 2.1 的硬件/软件解决方案的个人或组织。 “设备实现”或“实现”是这样开发的硬件/软件解决方案。
要被视为与 Android 2.1 兼容，设备实现：
- 必须满足本兼容性定义中提出的要求，包括通过引用并入的任何文档。
- 必须通过设备实施软件完成时可用的最新版本的 Android 兼容性测试套件 (CTS)。 （CTS 作为 Android 开源项目 [资源，2 ] 的一部分提供。）CTS 测试了本文档中列出的许多（但不是全部）组件。
如果此定义或 CTS 不明确、模棱两可或不完整，则设备实现者有责任确保与现有实现的兼容性。出于这个原因，Android 开源项目 [ Resources, 3 ] 既是 Android 的参考实现，也是首选实现。强烈建议设备实施者基于 Android 开源项目提供的“上游”源代码实现其实施。虽然假设某些组件可以替换为替代实现，但强烈建议不要这样做，因为通过 CTS 测试将变得更加困难。实施者有责任确保与标准 Android 实施的行为完全兼容，包括和超越兼容性测试套件。最后，请注意，本文档明确禁止某些组件替换和修改。
2. 资源
- IETF RFC2119 要求级别： http ://www.ietf.org/rfc/rfc2119.txt
- Android 兼容性计划概述：http: //source.android.com/compatibility/index.html
- Android 开源项目：http: //source.android.com/
- API 定义和文档：http: //developer.android.com/reference/packages.html
- Android 权限参考：http: //developer.android.com/reference/android/Manifest.permission.html
- android.os.Build 参考：http: //developer.android.com/reference/android/os/Build.html
- Android 2.1 允许的版本字符串：http: //source.android.com/compatibility/2.1/versions.html
- android.webkit.WebView 类：http: //developer.android.com/reference/android/webkit/WebView.html
- HTML5：http: //www.whatwg.org/specs/web-apps/current-work/multipage/
- Dalvik 虚拟机规范：可在 Android 源代码中找到，位于 dalvik/docs
- AppWidgets：http: //developer.android.com/guide/practices/ui_guidelines/widget_design.html
- 通知：http: //developer.android.com/guide/topics/ui/notifiers/notifications.html
- 应用资源： http ://code.google.com/android/reference/available-resources.html
- 状态栏图标样式指南：http: //developer.android.com/guide/practices/ui_guideline/icon_design.html#statusbarstructure
- 搜索管理器：http: //developer.android.com/reference/android/app/SearchManager.html
- 祝酒词：http: //developer.android.com/reference/android/widget/Toast.html
- 动态壁纸：http: //developer.android.com/resources/articles/live-wallpapers.html
- 适用于 Android 的应用程序： http ://code.google.com/p/apps-for-android
- 参考工具文档（用于 adb、aapt、ddms）：http: //developer.android.com/guide/developing/tools/index.html
- Android apk 文件说明：http: //developer.android.com/guide/topics/fundamentals.html
- 清单文件：http: //developer.android.com/guide/topics/manifest/manifest-intro.html
- 猴子测试工具：http: //developer.android.com/guide/developing/tools/monkey.html
- 支持多屏：http: //developer.android.com/guide/practices/screens_support.html
- android.content.res.Configuration：http: //developer.android.com/reference/android/content/res/Configuration.html
- android.util.DisplayMetrics：http: //developer.android.com/reference/android/util/DisplayMetrics.html
- android.hardware.Camera：http://developer.android.com/reference/android/hardware/Camera.html
- 传感器坐标空间：http: //developer.android.com/reference/android/hardware/SensorEvent.html
- Android 安全和权限参考：http: //developer.android.com/guide/topics/security/security.html
- 蓝牙 API：http: //developer.android.com/reference/android/bluetooth/package-summary.html
其中许多资源直接或间接源自 Android 2.1 SDK，并且在功能上与该 SDK 文档中的信息相同。在此兼容性定义或兼容性测试套件与 SDK 文档不一致的任何情况下，SDK 文档被视为权威。上述参考文献中提供的任何技术细节都被视为包含在本兼容性定义中。
3. 软件
Android 平台包括一组托管 API、一组原生 API 和一组所谓的“软”API，例如 Intent 系统和 Web 应用程序 API。本节详细介绍了兼容性不可或缺的硬 API 和软 API，以及某些其他相关的技术和用户界面行为。设备实现必须符合本节中的所有要求。
3.1。托管 API 兼容性
托管（基于 Dalvik）的执行环境是 Android 应用程序的主要工具。 Android 应用程序编程接口 (API) 是向在托管 VM 环境中运行的应用程序公开的一组 Android 平台接口。设备实现必须提供 Android 2.1 SDK [资源，4 ] 公开的任何已记录 API 的完整实施，包括所有已记录的行为。
设备实现不得省略任何托管 API、更改 API 接口或签名、偏离记录的行为或包含无操作，除非此兼容性定义特别允许。
3.2.软 API 兼容性
除了第 3.1 节中的托管 API 之外，Android 还包括一个重要的仅运行时“软”API，其形式为诸如 Intent、权限和 Android 应用程序的类似方面等无法在应用程序编译时强制执行的方面。本节详细介绍了与 Android 2.1 兼容所需的“软”API 和系统行为。设备实现必须满足本节中提出的所有要求。
3.2.1。权限
设备实现者必须支持并强制执行权限参考页 [资源，5 ] 中记录的所有权限常量。请注意，第 10 节列出了与 Android 安全模型相关的其他要求。
3.2.2.构建参数
Android API 在android.os.Build类 [ Resources, 6 ] 上包含许多常量，用于描述当前设备。为了在设备实现中提供一致、有意义的值，下表包含了对设备实现必须遵守的这些值的格式的额外限制。
| 范围 | 注释 |
| android.os.Build.VERSION.RELEASE | 当前执行的 Android 系统的版本，采用人类可读的格式。该字段必须具有 [ Resources, 7 ] 中定义的字符串值之一。 |
| android.os.Build.VERSION.SDK | 当前执行的 Android 系统的版本，采用第三方应用程序代码可访问的格式。对于 Android 2.1，此字段必须具有整数值 7。 |
| android.os.Build.VERSION.INCREMENTAL | 设备实现者选择的值，以人类可读的格式指定当前执行的 Android 系统的特定构建。此值不得重复用于交付给最终用户的不同构建。此字段的典型用途是指示使用哪个构建号或源代码控制更改标识符来生成构建。该字段的具体格式没有要求，但不能为空或空字符串（“”）。 |
| android.os.Build.BOARD | 设备实现者选择的一个值，用于标识设备使用的特定内部硬件，采用人类可读的格式。该字段的一个可能用途是指示为设备供电的电路板的特定版本。该字段的具体格式没有要求，但不能为空或空字符串（“”）。 |
| android.os.Build.BRAND | 由设备实施者选择的值，以人类可读的格式标识生产设备的公司、组织、个人等的名称。此字段的一种可能用途是指明销售设备的 OEM 和/或运营商。该字段的具体格式没有要求，但不能为空或空字符串（“”）。 |
| android.os.Build.DEVICE | 由设备实施者选择的一个值，用于标识设备主体的特定配置或修订（有时称为“工业设计”）。该字段的具体格式没有要求，但不能为空或空字符串（“”）。 |
| android.os.Build.FINGERPRINT | 唯一标识此构建的字符串。它应该是合理的人类可读的。它必须遵循这个模板：$(BRAND)/$(PRODUCT)/$(DEVICE)/$(BOARD):$(VERSION.RELEASE)/$(ID)/$(VERSION.INCREMENTAL):$(TYPE)/$(TAGS)例如： acme/mydevice/generic/generic:2.1-update1/ERC77/3359:userdebug/test-keys指纹不得包含空格。如果上述模板中包含的其他字段有空格，则应将它们替换为指纹中的 ASCII 下划线（“_”）字符。 |
| android.os.Build.HOST | 一个字符串，以人类可读的格式唯一标识构建所基于的主机。该字段的具体格式没有要求，但不能为空或空字符串（“”）。 |
| android.os.Build.ID | 设备实现者选择的标识符，用于引用特定版本，采用人类可读的格式。此字段可以与 android.os.Build.VERSION.INCREMENTAL 相同，但应该是一个足以让最终用户区分软件构建的值。该字段的具体格式没有要求，但不能为空或空字符串（“”）。 |
| android.os.Build.MODEL | 由设备实现者选择的一个值，其中包含最终用户已知的设备名称。这应该与设备销售和销售给最终用户的名称相同。该字段的具体格式没有要求，但不能为空或空字符串（“”）。 |
| android.os.Build.PRODUCT | 设备实现者选择的一个值，包含设备的开发名称或代码名称。必须是人类可读的，但不一定供最终用户查看。该字段的具体格式没有要求，但不能为空或空字符串（“”）。 |
| android.os.Build.TAGS | 由设备实现者选择的以逗号分隔的标签列表，用于进一步区分构建。例如，“未签名，调试”。此字段不得为 null 或空字符串 ("")，但可以使用单个标签（例如 "release"）。 |
| android.os.Build.TIME | 表示构建发生时间的时间戳的值。 |
| android.os.Build.TYPE | 设备实现者选择的值，指定构建的运行时配置。该字段应该具有对应于三个典型 Android 运行时配置的值之一：“user”、“userdebug”或“eng”。 |
| android.os.Build.USER | 生成构建的用户（或自动用户）的名称或用户 ID。该字段的具体格式没有要求，但不能为空或空字符串（“”）。 |
3.2.3。意图兼容性
Android 使用 Intents 来实现应用程序之间的松耦合集成。本节描述了与设备实现必须遵守的 Intent 模式相关的要求。 “尊敬”是指设备实现者必须提供一个 Android 活动或服务，该活动或服务指定一个匹配的 Intent 过滤器，并绑定到每个指定的 Intent 模式并实现正确的行为。
3.2.3.1。核心应用意图
Android 上游项目定义了一些核心应用，例如电话拨号器、日历、通讯录、音乐播放器等。设备实施者可以用替代版本替换这些应用程序。
但是，任何此类替代版本都必须遵循上游项目提供的相同 Intent 模式。例如，如果设备包含替代音乐播放器，它仍必须遵循第三方应用程序发布的 Intent 模式来挑选歌曲。
- 台钟
- 浏览器
- 日历
- 计算器
- 相机
- 联系人
- 电子邮件
- 画廊
- 全球搜索
- 启动器
- LivePicker（即动态壁纸选择器应用程序；如果设备不支持动态壁纸，则可以省略，根据第 3.8.5 节。）
- 消息（又名“彩信”）
- 音乐
- 电话
- 设置
- 录音机
核心 Android 系统应用程序包括各种被视为“公共”的 Activity 或 Service 组件。也就是说，属性“android:exported”可能不存在，或者可能具有值“true”。
对于在核心 Android 系统应用之一中定义的每个 Activity 或 Service 未通过值为“false”的 android:exported 属性标记为非公共，设备实现必须包含实现相同 Intent 过滤器的相同类型的组件模式作为核心的Android系统应用程序。
换句话说，设备实现可能会取代核心的 Android 系统应用程序；但是，如果支持，设备实现必须支持每个被替换的核心 Android 系统应用程序定义的所有 Intent 模式。
3.2.3.2。意图覆盖
由于 Android 是一个可扩展的平台，设备实现者必须允许在核心系统应用程序中定义的每个 Intent 模式被第三方应用程序覆盖。上游 Android 开源项目默认允许这样做；设备实现者不得将特殊权限附加到系统应用程序对这些 Intent 模式的使用，或阻止第三方应用程序绑定并控制这些模式。该禁止具体包括但不限于禁用“选择器”用户界面，该界面允许用户在所有处理相同意图模式的多个应用程序之间进行选择。
3.2.3.3。意图命名空间
设备实现者不得包含任何使用 android.* 命名空间中的 ACTION、CATEGORY 或其他键字符串来支持任何新 Intent 或 Broadcast Intent 模式的 Android 组件。设备实施者不得在属于另一个组织的包空间中包含任何使用 ACTION、CATEGORY 或其他键字符串来尊重任何新 Intent 或 Broadcast Intent 模式的 Android 组件。设备实现者不得更改或扩展第 3.2.3.1 节中列出的核心应用程序使用的任何 Intent 模式。
这种禁止类似于第 3.6 节中为 Java 语言类指定的禁止。
3.2.3.4。广播意图
第三方应用程序依靠平台广播某些 Intent 来通知他们硬件或软件环境的变化。 Android 兼容设备必须广播公共广播 Intent 以响应适当的系统事件。广播意图在 SDK 文档中进行了描述。
3.3.原生 API 兼容性
在 Dalvik 中运行的托管代码可以调用应用程序 .apk 文件中提供的本机代码，作为为适当的设备硬件架构编译的 ELF .so 文件。设备实现必须包括对在托管环境中运行的代码的支持，以调用本机代码，使用标准的 Java 本机接口 (JNI) 语义。以下 API 必须可用于本机代码：
设备实现必须支持 OpenGL ES 1.0。缺乏硬件加速的设备必须使用软件渲染器实现 OpenGL ES 1.0。设备实现应该尽可能多地实现设备硬件支持的 OpenGL ES 1.1。如果硬件能够在这些 API 上提供合理的性能，设备实现应该为 OpenGL ES 2.0 提供实现。
这些库必须与 Android 开源项目在 Bionic 中提供的版本源兼容（即标头兼容）和二进制兼容（对于给定的处理器架构）。由于 Bionic 实现与 GNU C 库等其他实现不完全兼容，因此设备实现者应该使用 Android 实现。如果设备实现者使用这些库的不同实现，他们必须确保标头、二进制和行为兼容性。
设备实现必须通过android.os.Build.CPU_ABI API 准确报告设备支持的本机应用二进制接口 (ABI)。 ABI 必须是最新版本的 Android NDK 中记录的条目之一，位于文件docs/CPU-ARCH-ABIS.txt中。请注意，Android NDK 的其他版本可能会引入对其他 ABI 的支持。
本机代码兼容性具有挑战性。出于这个原因，应该重申的是，强烈鼓励设备实现者使用上面列出的库的上游实现，以帮助确保兼容性。
3.4. Web API 兼容性
许多开发人员和应用程序的用户界面依赖于android.webkit.WebView类 [资源，8 ] 的行为，因此 WebView 实现必须在 Android 实现之间兼容。 Android 开源实现使用 WebKit 渲染引擎来实现 WebView。
因为为 Web 浏览器开发一个全面的测试套件是不可行的，设备实现者必须在 WebView 实现中使用特定的上游构建的 WebKit。具体来说：
- WebView 必须使用来自 Android 2.1 的上游 Android 开源树的 530.17 WebKit 构建。此版本包括一组特定的 WebView 功能和安全修复程序。
- WebView 报告的用户代理字符串必须采用以下格式：
Mozilla/5.0 (Linux; U; Android $(VERSION); $(LOCALE); $(MODEL) Build/$(BUILD)) AppleWebKit/530.17 (KHTML, like Gecko) Version/4.0 Mobile Safari/530.17
实现可以在独立的浏览器应用程序中提供自定义用户代理字符串。更重要的是，独立浏览器可能基于替代浏览器技术（如 Firefox、Opera 等）。但是，即使交付了替代浏览器应用程序，提供给第三方应用程序的 WebView 组件也必须基于 WebKit，如上。
WebView 配置必须包括对 HTML5 数据库、应用程序缓存和地理定位 API [资源，9 ] 的支持。 WebView 必须以某种形式包含对 HTML5 <video>标记的支持。独立的浏览器应用程序（无论是基于上游 WebKit 浏览器应用程序还是第三方替代品）必须包含对刚刚为 WebView 列出的相同 HTML5 功能的支持。
3.5. API 行为兼容性
每种 API 类型（托管、软、本机和 Web）的行为必须与上游 Android 开源项目 [参考资料，3 ] 的首选实现一致。一些特定的兼容性领域是：
上面的列表并不全面，设备实现者有责任确保行为兼容性。出于这个原因，设备实现者应该尽可能使用通过 Android 开源项目提供的源代码，而不是重新实现系统的重要部分。
兼容性测试套件 (CTS) 测试平台的重要部分的行为兼容性，但不是全部。实施者有责任确保与 Android 开源项目的行为兼容性。
3.6. API 命名空间
Android 遵循 Java 编程语言定义的包和类命名空间约定。为确保与第三方应用程序的兼容性，设备实施者不得对这些包命名空间进行任何禁止的修改（见下文）：
- 设备实现不得通过更改任何方法或类签名或删除类或类字段来修改 Android 平台上公开的 API。
- 设备实现者可以修改 API 的底层实现，但此类修改不得影响任何公开公开的 API 的声明行为和 Java 语言签名。
- 设备实现者不得将任何公开暴露的元素（例如类或接口，或现有类或接口的字段或方法）添加到上述 API。
“公开暴露的元素”是上游 Android 源代码中未使用“@hide”标记修饰的任何构造。换句话说，设备实现者不得公开新的 API 或更改上述命名空间中的现有 API。设备实施者可以进行仅限内部的修改，但不得向开发人员宣传或以其他方式公开这些修改。
设备实现者可以添加自定义 API，但任何此类 API 不得位于其他组织拥有或引用的命名空间中。例如，设备实现者不得将 API 添加到 com.google.* 或类似命名空间；只有谷歌可以这样做。同样，Google 不得将 API 添加到其他公司的命名空间。
如果设备实现者提议改进上述包命名空间之一（例如通过向现有 API 添加有用的新功能，或添加新 API），则实现者应该访问 source.android.com 并开始贡献更改和代码，根据该网站上的信息。
请注意，上述限制对应于 Java 编程语言中命名 API 的标准约定；本节旨在通过包含在此兼容性定义中来加强这些约定并使其具有约束力。
3.7.虚拟机兼容性
设备实现必须支持完整的 Dalvik Executable (DEX) 字节码规范和 Dalvik 虚拟机语义 [资源，10 ]。
设备实现必须配置 Dalvik 为屏幕分类为中密度或低密度的设备上的每个应用程序分配至少 16MB 的内存。设备实现必须配置 Dalvik 为屏幕分类为高密度的设备上的每个应用程序分配至少 24MB 内存。请注意，设备实现可以分配比这些数字更多的内存，但不是必须的。
3.8.用户界面兼容性
Android 平台包含一些开发人员 API，允许开发人员连接到系统用户界面。设备实现必须将这些标准 UI API 合并到他们开发的自定义用户界面中，如下所述。
3.8.1.小部件
Android 定义了一个组件类型和相应的 API 和生命周期，允许应用程序向最终用户公开一个“AppWidget”[参考资料，11 ]。 Android 开源参考版本包括一个 Launcher 应用程序，该应用程序包含用户界面元素，允许用户从主屏幕添加、查看和删除 AppWidget。
设备实施者可以替代参考启动器（即主屏幕）的替代方案。替代启动器应该包含对 AppWidgets 的内置支持，并公开用户界面元素以直接在启动器中添加、配置、查看和删除 AppWidgets。替代启动器可以省略这些用户界面元素；但是，如果它们被省略，设备实现者必须提供一个可从 Launcher 访问的单独应用程序，允许用户添加、配置、查看和删除 AppWidget。
3.8.2.通知
Android 包含允许开发人员通知用户重要事件的 API [参考资料，12 ]。设备实现者必须为如此定义的每一类通知提供支持；具体来说：声音、振动、灯光和状态栏。
此外，实现必须正确呈现 API [资源，13 ] 或状态栏图标样式指南 [资源，14 ] 中提供的所有资源（图标、声音文件等）。设备实现者可以为通知提供一种替代的用户体验，而不是参考 Android 开源实现提供的体验；然而，这样的替代通知系统必须支持现有的通知资源，如上所述。
3.8.3.搜索
Android 包含 API [参考资料，15 ]，允许开发人员将搜索合并到他们的应用程序中，并将他们的应用程序数据公开到全局系统搜索中。一般而言，此功能由一个单一的、系统范围的用户界面组成，允许用户输入查询、在用户键入时显示建议并显示结果。 Android API 允许开发人员重用此接口以在他们自己的应用程序中提供搜索，并允许开发人员将结果提供给通用的全局搜索用户界面。
设备实现必须包括一个单一的、共享的、系统范围的搜索用户界面，该界面能够响应用户输入提供实时建议。设备实现必须实现允许开发人员重用此用户界面以在他们自己的应用程序中提供搜索的 API。设备实现必须实现允许第三方应用程序在全局搜索模式下运行时向搜索框添加建议的 API。如果没有安装使用此功能的第三方应用程序，则默认行为应该是显示网络搜索引擎结果和建议。
设备实现可以提供替代的搜索用户界面，但应该包括一个硬或软专用搜索按钮，可以在任何应用程序中随时使用它来调用搜索框架，其行为在 API 文档中提供。
3.8.4.敬酒
应用程序可以使用“Toast”API（在 [参考资料，16 ] 中定义）向最终用户显示简短的非模态字符串，这些字符串会在短暂的一段时间后消失。设备实现必须以某种高可见度的方式从应用程序向最终用户显示 Toast。
3.8.5。动态壁纸
Android 定义了一种组件类型和相应的 API 和生命周期，允许应用程序向最终用户公开一个或多个“动态壁纸”[参考资料，17 ]。动态壁纸是具有有限输入功能的动画、图案或类似图像，在其他应用程序后面显示为壁纸。
如果硬件能够以合理的帧速率运行所有动态壁纸，并且没有功能限制，并且对其他应用程序没有不利影响，则认为硬件能够可靠地运行动态壁纸。如果硬件限制导致壁纸和/或应用程序崩溃、故障、消耗过多的 CPU 或电池电量，或以不可接受的低帧速率运行，则认为硬件无法运行动态壁纸。例如，一些动态壁纸可能使用 Open GL 1.0 或 2.0 上下文来呈现其内容。动态壁纸无法在不支持多个 OpenGL 上下文的硬件上可靠运行，因为使用 OpenGL 上下文的动态壁纸可能会与也使用 OpenGL 上下文的其他应用程序发生冲突。
如上所述，能够可靠运行动态壁纸的设备实现应该实现动态壁纸。如上所述确定不能可靠运行动态壁纸的设备实现不得实现动态壁纸。
4. 参考软件兼容性
- 计算器（包含在 SDK 中）
- 月球着陆器（包含在 SDK 中）
- “Android 应用程序”应用程序 [资源，18 ]。
上面的每个应用程序都必须在实现上启动并正确运行，才能使实现被认为是兼容的。
此外，设备实现必须测试每个冒烟测试应用程序的每个菜单项（包括所有子菜单）：
5. 应用程序封装兼容性
设备实现必须安装并运行由官方 Android SDK [资源，19 ] 中包含的“aapt”工具生成的 Android“.apk”文件。
设备实现不得扩展 .apk [ Resources, 20 ]、Android Manifest [ Resources, 21 ] 或 Dalvik 字节码 [ Resources, 10 ] 格式，以防止这些文件在其他兼容设备上正确安装和运行.设备实现者应该使用 Dalvik 的参考上游实现，以及参考实现的包管理系统。
6. 多媒体兼容性
设备实现必须支持以下多媒体编解码器。所有这些编解码器都作为软件实现在 Android 开源项目的首选 Android 实现中提供。
请注意，Google 和开放手机联盟均未声明这些编解码器不受第三方专利的约束。建议那些打算在硬件或软件产品中使用此源代码的人，此代码的实现（包括在开源软件或共享软件中）可能需要相关专利持有人的专利许可。
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.
7. Developer Tool Compatibility
Device implemenations MUST support the Android Developer Tools provided in the Android SDK. Specifically, Android-compatible devices MUST be compatible with:
- Android Debug Bridge (known as adb) [ Resources, 19 ]
Device implementations MUST support alladbfunctions as documented in the Android SDK. The device-sideadbdaemon SHOULD be inactive by default, but there MUST be a user-accessible mechanism to turn on the Android Debug Bridge. - Dalvik Debug Monitor Service (known as ddms) [ Resources, 19 ]
Device implementations MUST support allddmsfeatures as documented in the Android SDK. Asddmsusesadb, support forddmsSHOULD be inactive by default, but MUST be supported whenever the user has activated the Android Debug Bridge, as above. - Monkey [ Resources, 22 ]
Device implementations MUST include the Monkey framework, and make it available for applications to use.
8. Hardware Compatibility
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.
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:
- class definitions for the component's APIs MUST be present
- the API's behaviors MUST be implemented as no-ops in some reasonable fashion
- API methods MUST return null values where permitted by the SDK documentation
- API methods MUST return no-op implementations of classes where null values are not permitted by the SDK documentation
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.
Device implementations MUST accurate report accurate hardware configuration information via the getSystemAvailableFeatures() and hasSystemFeature(String) methods on the android.content.pm.PackageManager class.
8.1. Display
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 [ Resources, 23 ]. Devices MUST properly implement these behaviors, as detailed in this section.
For Android 2.1, this are the most common display configurations:
Device implementations corresponding to one of the standard configurations above MUST be configured to report the indicated screen size to applications via the android.content.res.Configuration [ Resources, 24 ] class.
Some .apk packages have manifests that do not identify them as supporting a specific density range. When running such applications, the following constraints apply:
- Device implementations MUST interpret resources in a .apk that lack a density qualifier as defaulting to "medium" (known as "mdpi" in the SDK documentation.)
- When operating on a "low" density screen, device implementations MUST scale down medium/mdpi assets by a factor of 0.75.
- When operating on a "high" density screen, device implementations MUST scale up medium/mdpi assets by a factor of 1.5.
- Device implementations MUST NOT scale assets within a density range, and MUST scale assets by exactly these factors between density ranges.
8.1.2. Non-Standard Display Configurations
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.
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.
8.1.3. Display Metrics
Device implementations MUST report correct valuesfor all display metrics defined in android.util.DisplayMetrics [ Resources, 25 ].
8.2. Keyboard
- MUST include support for the Input Management Framework (which allows third party developers to create Input Management Engines -- ie soft keyboard) as detailed at developer.android.com
- MUST provide at least one soft keyboard implementation (regardless of whether a hard keyboard is present)
- MAY include additional soft keyboard implementations
- MAY include a hardware keyboard
- MUST NOT include a hardware keyboard that does not match one of the formats specified in
android.content.res.Configuration.keyboard[ Resources, 24 ] (that is, QWERTY, or 12-key)
8.3. Non-touch Navigation
- MAY omit a non-touch navigation options (that is, may omit a trackball, d-pad, or wheel)
- MUST report the correct value for
android.content.res.Configuration.navigation[ Resources, 24 ]
8.4. Screen Orientation
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.
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.
8.5. Touchscreen input
- MUST have a touchscreen
- MAY have either capacative or resistive touchscreen
- MUST report the value of
android.content.res.Configuration[ Resources, 24 ] reflecting corresponding to the type of the specific touchscreen on the device
8.6. USB
- MUST implement a USB client, connectable to a USB host with a standard USB-A port
- MUST implement the Android Debug Bridge over USB (as described in Section 7)
- MUST implement the USB mass storage specification, to allow a host connected to the device to access the contents of the /sdcard volume
- SHOULD use the micro USB form factor on the device side
- 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
8.7. Navigation keys
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.
Device implementers SHOULD also provide a dedicated search key. Device implementers MAY also provide send and end keys for phone calls.
8.8. Wireless Data Networking
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.
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.
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.
8.9. Camera
Device implementations MUST include a camera. The included camera:
- MUST have a resolution of at least 2 megapixels
- SHOULD have either hardware auto-focus, or software auto-focus implemented in the camera driver (transparent to application software)
- MAY have fixed-focus or EDOF (extended depth of field) hardware
- 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
FLASH_MODE_AUTOorFLASH_MODE_ONattributes of aCamera.Parametersobject. Note that this constraint does not apply to the device's built-in system camera application, but only to third-party applications usingCamera.PreviewCallback.
Device implementations MUST implement the following behaviors for the camera-related APIs:
- 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.
- 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.
Device implementations MUST implement the full Camera API included in the Android 2.1 SDK documentation [ Resources, 26 ]), regardless of whether the device includes hardware autofocus or other capabilities. For instance, cameras that lack autofocus MUST still call any registered android.hardware.Camera.AutoFocusCallback instances (even though this has no relevance to a non-autofocus camera.)
Device implementations MUST recognize and honor each parameter name defined as a constant on the android.hardware.Camera.Parameters 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 android.hardware.Camera.setParameters() method other than those documented as constants on the android.hardware.Camera.Parameters , 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.
8.10. Accelerometer
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 [ Resources, 27 ]).
8.11. Compass
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 [ Resources, 27 ]).
8.12. GPS
Device implementations MUST include a GPS, and SHOULD include some form of "assisted GPS" technique to minimize GPS lock-on time.
8.13. Telephony
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.
See also Section 8.8, Wireless Data Networking.
8.14. Memory and Storage
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.
Device implementations MUST have at least 150MB of non-volatile storage available for user data. That is, the /data partition must be at least 150MB.
8.15. Application Shared Storage
Device implementations MUST offer shared storage for applications. The shared storage provided MUST be at least 2GB in size.
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 /sdcard , then the device MUST include a Linux symbolic link from /sdcard to the actual mount point.
Device implementations MUST enforce as documented the android.permission.WRITE_EXTERNAL_STORAGE permission on this shared storage. Shared storage MUST otherwise be writable by any application that obtains that permission.
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.
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.
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 /sdcard (or /sdcard MUST be a symbolic link to the physical location if it is mounted elsewhere.)
8.16.蓝牙
Device implementations MUST include a Bluetooth transceiver. Device implementations MUST enable the RFCOMM-based Bluetooth API as described in the SDK documentation [ Resources, 29 ]. Device implementations SHOULD implement relevant Bluetooth profiles, such as A2DP, AVRCP, OBEX, etc. as appropriate for the device.
9. Performance Compatibility
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:
10. Security Model Compatibility
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 [ Resources, 28 ] 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.
10.1. Permissions
Device implementations MUST support the Android permissions model as defined in the Android developer documentation [ Resources, 28 ]. 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.
10.2. UID and Process Isolation
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 [ Resources, 28 ].
10.3. Filesystem Permissions
Device implementations MUST support the Android file access permissions model as defined in as defined in the Security and Permissions reference [ Resources, 28 ].
11. Compatibility Test Suite
Device implementations MUST pass the Android Compatibility Test Suite (CTS) [ Resources, 2 ] 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.
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.
12. Updatable Software
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.
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:
- Over-the-air (OTA) downloads with offline update via reboot
- "Tethered" updates over USB from a host PC
- "Offline" updates via a reboot and update from a file on removable storage
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.
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.
13. Contact Us
You can contact the document authors at compatibility@android.com for clarifications and to bring up any issues that you think the document does not cover.