Android 2.1 兼容性定义

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

版权所有 © 2010,Google Inc. 保留所有权利。
compatibility@android.com

1. 简介

本文档列出了与 Android 2.1 兼容的手机必须满足的要求。

本文档按照 RFC2119 [资源 1] 中定义的 IETF 标准使用“必须”“不得”“必需”“会”“不会”“应”“不应”“建议”“可以”和“可选”字样。

在本文档中,“设备实现者”或“实现者”指的是开发搭载 Android 2.1 的硬件/软件解决方案的个人或组织。“设备实现”或“实现”指的是所开发的硬件/软件解决方案。

设备实现必须满足以下要求,才会被视为与 Android 2.1 兼容:

  • 本兼容性定义文档(包括通过提及纳入的任何文档)中列出的要求。
  • 通过在设备实现的软件完成时提供的最新版本 Android 兼容性测试套件 (CTS) 的测试。(CTS 作为 Android 开源项目 [资源 2] 的一部分提供)。CTS 会测试本文档中列出的很多(但非全部)组件。

本定义或 CTS 未提及、含糊不清或不完整之处,设备实现者需负责确保与现有实现兼容。因此,Android 开源项目 [资源 3] 既是参考 Android 实现,也是首选 Android 实现。强烈建议设备实现者使其实现基于 Android 开源项目提供的“上游”源代码。虽然从理论上来说某些组件可以替换为替代实现,但强烈建议不要这样做,否则通过 CTS 测试的难度会大大增加。实现者需负责确保行为与标准 Android 实现(包括兼容性测试套件及其他内容)完全兼容。最后请注意,本文档明确禁止替换和修改某些组件。

2. 资源

  1. IETF RFC2119 要求级别:http://www.ietf.org/rfc/rfc2119.txt
  2. Android 兼容性计划概述:http://source.android.com/compatibility/index.html
  3. Android 开源项目:http://source.android.com/
  4. API 定义和文档:http://developer.android.com/reference/packages.html
  5. Android 权限参考:http://developer.android.com/reference/android/Manifest.permission.html
  6. android.os.Build 参考:http://developer.android.com/reference/android/os/Build.html
  7. 允许的 Android 2.1 版本字符串:http://source.android.com/compatibility/2.1/versions.html
  8. android.webkit.WebView 类:http://developer.android.com/reference/android/webkit/WebView.html
  9. HTML5:http://www.whatwg.org/specs/web-apps/current-work/multipage/
  10. Dalvik 虚拟机规范:可在 Android 源代码中的 dalvik/docs 下找到
  11. AppWidget:http://developer.android.com/guide/practices/ui_guidelines/widget_design.html
  12. 通知:http://developer.android.com/guide/topics/ui/notifiers/notifications.html
  13. 应用资源:http://code.google.com/android/reference/available-resources.html
  14. 状态栏图标样式指南:http://developer.android.com/guide/practices/ui_guideline /icon_design.html#statusbarstructure
  15. 搜索管理器:http://developer.android.com/reference/android/app/SearchManager.html
  16. 消息框:http://developer.android.com/reference/android/widget/Toast.html
  17. 动态壁纸:http://developer.android.com/resources/articles/live-wallpapers.html
  18. Android 应用:http://code.google.com/p/apps-for-android
  19. 参考工具文档(适用于 adb、aapt、ddms):http://developer.android.com/guide/developing/tools/index.html
  20. Android apk 文件说明:http://developer.android.com/guide/topics/fundamentals.html
  21. 清单文件:http://developer.android.com/guide/topics/manifest/manifest-intro.html
  22. Monkey 测试工具:http://developer.android.com/guide/developing/tools/monkey.html
  23. 支持多种屏幕:http://developer.android.com/guide/practices/screens_support.html
  24. android.content.res.Configuration:http://developer.android.com/reference/android/content/res/Configuration.html
  25. android.util.DisplayMetrics:http://developer.android.com/reference/android/util/DisplayMetrics.html
  26. android.hardware.Camera:http://developer.android.com/reference/android/hardware/Camera.html
  27. 传感器坐标空间:http://developer.android.com/reference/android/hardware/SensorEvent.html
  28. Android 安全和权限参考:http://developer.android.com/guide/topics/security/security.html
  29. 蓝牙 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) 是一组 Android 平台接口,可供在受管理虚拟机环境中运行的应用使用。设备实现必须提供 Android 2.1 SDK 所提供的所有已载述 API 的完整实现(包括所有已载述的行为)[资源 4]。

除非本兼容性定义中明确许可,否则设备实现不得省略任何受管理 API,不得更改 API 接口或签名,不得违背已载述的行为,也不得包含空操作。

3.2. 软 API 兼容性

除了第 3.1 节中的受管理 API 之外,Android 还包含一个非常重要的运行时专用“软”API,该 API 采用 intent、权限,以及 Android 应用中在应用编译期间无法被强制执行的其他类似方面等形式。本节详细介绍了与 Android 2.1 兼容所需的“软”API 和系统行为。设备实现必须满足本节中所述的所有要求。

3.2.1. 权限

设备实现者必须支持并强制执行“权限”参考页面 [资源 5] 中所述的所有权限常量。请注意,第 10 节列出了与 Android 安全模型相关的其他要求。

3.2.2. build 参数

Android API 在 android.os.Build 类 [资源 6] 中包含一些用于描述当前设备的常量。为了在设备实现之间提供一致且有意义的值,下表列出了对这些值的格式的其他限制,设备实现必须遵守这些限制。

参数 注释
android.os.Build.VERSION.RELEASE 当前正在执行的 Android 系统的版本,采用人类可读懂的格式。此字段的值必须是 [资源 7] 中定义的字符串之一。
android.os.Build.VERSION.SDK 当前正在执行的 Android 系统的版本,采用第三方应用代码可访问的格式。对于 Android 2.1,此字段的值必须为整数 7。
android.os.Build.VERSION.INCREMENTAL 由设备实现者选择的值,用于指定当前正在执行的 Android 系统的具体 build,采用人类可读懂的格式。此值不得重复用于提供给最终用户的不同 build。此字段的一个典型用途是,指明使用哪个 build 号或源代码控制更改标识符来生成 build。此字段不得为 null,也不得为空字符串 (""),除此之外,对此字段的具体格式没有任何其他要求。
android.os.Build.BOARD 由设备实现者选择的值,用于标识设备所使用的具体内部硬件,采用人类可读懂的格式。此字段的一个可能用途是,指明设备主板的具体修订版本。此字段不得为 null,也不得为空字符串 (""),除此之外,对此字段的具体格式没有任何其他要求。
android.os.Build.BRAND 由设备实现者选择的值,用于标识生产设备的公司、组织、人员等的名称,采用人类可读懂的格式。此字段的一个可能用途是,指明销售设备的 OEM 和/或运营商。此字段不得为 null,也不得为空字符串 (""),除此之外,对此字段的具体格式没有任何其他要求。
android.os.Build.DEVICE 由设备实现者选择的值,用于标识设备主体的具体配置或修订版本(有时称为“工业设计”)。此字段不得为 null,也不得为空字符串 (""),除此之外,对此字段的具体格式没有任何其他要求。
android.os.Build.FINGERPRINT 一个唯一标识相应 build 的字符串。应采用人类可读懂的格式,且必须遵从以下模板:
$(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 一个独一无二地标识构建相应 build 时所用主机的字符串,采用人类可读懂的格式。此字段不得为 null,也不得为空字符串 (""),除此之外,对此字段的具体格式没有任何其他要求。
android.os.Build.ID 由设备实现者选择的标识符,用于指代特定版本,采用人类可读懂的格式。此字段可与 android.os.Build.VERSION.INCREMENTAL 相同,但应是对最终用户来说有充分意义的值,以便他们区分各软件 build。此字段不得为 null,也不得为空字符串 (""),除此之外,对此字段的具体格式没有任何其他要求。
android.os.Build.MODEL 由设备实现者选择的值,其中包含最终用户所熟知的设备名称。此名称应与设备在营销时以及出售给最终用户时所使用的名称相同。此字段不得为 null,也不得为空字符串 (""),除此之外,对此字段的具体格式没有任何其他要求。
android.os.Build.PRODUCT 由设备实现者选择的值,其中包含设备的开发名称或代号。必须采用人类可读懂的格式,但不一定可供最终用户查看。此字段不得为 null,也不得为空字符串 (""),除此之外,对此字段的具体格式没有任何其他要求。
android.os.Build.TAGS 由设备实现者选择的一系列标记(用于进一步区分 build),各个标记之间以英文逗号分隔。例如“unsigned,debug”。此字段不能为 null,也不得为空字符串 (""),但可以为单个标记(例如“release”)。
android.os.Build.TIME 一个用于表示生成相应 build 时的时间戳的值。
android.os.Build.TYPE 由设备实现者选择的值,用于指定相应 build 的运行时配置。此字段的值应是与以下三种典型 Android 运行时配置对应的值之一:“user”“userdebug”或“eng”。
android.os.Build.USER 生成相应 build 的用户(或自动用户)的名称或用户 ID。此字段不得为 null,也不得为空字符串 (""),除此之外,对此字段的具体格式没有任何其他要求。

3.2.3. intent 兼容性

Android 使用 intent 在应用之间实现松散耦合的集成。本节介绍了与设备实现必须支持的 intent 模式相关的要求。“支持”意味着设备实现者必须提供一个 Android activity 或 Service,用于为每个指定的 intent 模式指定匹配的 intent 过滤器,并为这些模式绑定并实现正确的行为。

3.2.3.1. 核心应用 intent

Android 上游项目定义了很多核心应用,例如电话拨号器、日历、通讯录、音乐播放器等。设备实现者可以将这些应用替换为替代版本。

不过,任何此类替代版本都必须支持上游项目提供的相同 intent 模式。例如,如果设备包含替代音乐播放器,它仍必须支持第三方应用发出的用于挑选歌曲的 intent 模式。

以下应用被视为核心 Android 系统应用:

  • 桌面时钟
  • 浏览器
  • 日历
  • 计算器
  • 相机
  • 通讯录
  • 电子邮件
  • 图库
  • GlobalSearch
  • 启动器
  • LivePicker(即动态壁纸选择器应用;根据第 3.8.5 节的规定,如果设备不支持动态壁纸,则可以省略该应用。)
  • 消息功能(也称为“彩信”)
  • 音乐
  • 手机
  • 设置
  • 录音机

核心 Android 系统应用包含各种被视为“公开”组件的 activity 或 Service 组件。也就是说,属性“android:exported”可能不存在,也可能具有“true”值。

对于在一个核心 Android 系统应用中定义的每个 activity 或 Service,如果未通过将属性“android:exported”的值设为“false”来将该应用标记为“非公开”,则设备实现必须包含一个实现与该核心 Android 系统应用相同 intent 过滤器模式的同类型组件。

换言之,设备实现可以更换核心 Android 系统应用;不过,如果进行此类更换,设备实现必须支持由被更换的每个核心 Android 系统应用所定义的所有 intent 模式。

3.2.3.2. intent 替换

由于 Android 是一个可扩展的平台,因此设备实现者必须允许使用第三方应用替换核心系统应用中定义的每种 intent 模式。上游 Android 开源项目默认允许这么做;设备实现者不得为系统应用使用这些 intent 模式的情况附加特殊权限,也不得阻止第三方应用绑定到这些模式并取得对这些模式的控制权。具体而言,此项规定包括但不限于停用“选择器”界面(用户可通过该界面在多个均可处理相同 intent 模式的应用之间进行选择)。

注意:本节是由 Erratum EX6580 修改。

3.2.3.3. intent 命名空间

设备实现者不得添加任何符合以下条件的 Android 组件:支持任何使用 ACTION、CATEGORY 或使用 android.* 命名空间中的其他键字符串的新 intent 模式或广播 intent 模式。设备实现者不得添加任何符合以下条件的 Android 组件:支持任何使用 ACTION、CATEGORY 或使用属于其他组织的软件包空间中的其他键字符串的新 intent 模式或广播 intent 模式。设备实现者不得更改或扩展第 3.2.3.1 节列出的核心应用使用的任何 intent 模式。

此项规定类似于第 3.6 节中针对 Java 语言类的规定。

3.2.3.4. 广播 intent

第三方应用依赖平台广播某些 intent 来获悉硬件或软件环境中发生的变化。与 Android 兼容的设备必须广播公共广播 intent 来响应相应的系统事件。如需关于广播 intent 的介绍,请参阅 SDK 文档。

3.3. 原生 API 兼容性

在 Dalvik 中运行的受管理代码可以调用应用 .apk 文件中提供的原生代码,作为针对相应设备硬件架构编译的 ELF .so 文件。设备实现必须支持在受管理环境中运行的代码,以使用标准 Java 原生接口 (JNI) 语义调用原生代码。以下 API 必须可供原生代码使用:

  • libc(C 库)
  • libm(数学库)
  • JNI 接口
  • libz(Zlib 压缩)
  • liblog(Android 日志记录)
  • 对 C++ 的最基本支持
  • 对 OpenGL 的支持(如下所述)

设备实现必须支持 OpenGL ES 1.0。没有硬件加速的设备必须使用软件渲染程序实现 OpenGL ES 1.0。设备实现应实现设备硬件支持的尽可能多的 OpenGL ES 1.1 功能。设备实现应提供 OpenGL ES 2.0 实现(如果硬件能够在这些 API 上实现合理的性能)。

这些库必须与 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。

由于无法为网络浏览器开发综合测试套件,因此设备实现者必须在 WebView 实现中使用 WebKit 的特定上游 build。具体而言:

  • WebView 必须使用面向 Android 2.1 的上游 Android 开源树中的 530.17 WebKit build。该 build 包含一组针对 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
    • $(VERSION) 字符串的值必须与 android.os.Build.VERSION.RELEASE 的值相同
    • $(LOCALE) 字符串的值应遵循国家/地区代码和语言的 ISO 规范,并且应引用设备当前配置的语言区域
    • $(MODEL) 字符串的值必须与 android.os.Build.MODEL 的值相同
    • $(BUILD) 字符串的值必须与 android.os.Build.ID 的值相同

实现可以在独立的浏览器应用中附带自定义用户代理字符串。此外,独立的浏览器可以基于替代浏览器技术(例如 Firefox、Opera 等)。不过,即使交付的是替代浏览器应用,向第三方应用提供的 WebView 组件也必须基于 WebKit(如上文所述)。

WebView 配置必须支持 HTML5 数据库、应用缓存和地理定位 API [资源 9]。WebView 必须以某种形式支持 HTML5 <video> 标记。独立的浏览器应用(无论是基于上游 WebKit 浏览器应用,还是基于第三方替代应用)必须支持刚刚为 WebView 列出的相同 HTML5 功能。

3.5. API 行为兼容性

每种 API 类型(受管理 API、软 API、原生 API 和网页 API)的行为都必须与上游 Android 开源项目 [资源 3] 的首选实现一致。兼容性的一些具体方面如下:

  • 设备不得更改标准 intent 的行为或含义
  • 设备不得更改特定类型的系统组件(例如 Service、activity、ContentProvider 等)的生命周期或生命周期语义
  • 设备不得更改特定权限的语义

上述列表并不详尽,设备实现者需负责确保行为兼容性。为此,设备实现者应尽可能使用通过 Android 开源项目获得的源代码,而不是重新实现系统的重要部分。

兼容性测试套件 (CTS) 用于测试平台重要部分的行为兼容性,而不是测试整个平台的行为兼容性。实现者需负责确保与 Android 开源项目保持行为兼容。

3.6. API 命名空间

Android 遵循 Java 编程语言定义的软件包和类命名空间惯例。为了确保与第三方应用兼容,设备实现者不得对以下软件包命名空间进行任何禁止执行的修改(见下文):

  • java.*
  • javax.*
  • sun.*
  • android.*
  • com.android.*

禁止执行的修改包括:

  • 设备实现不得通过更改任何方法或类签名或者通过移除类或类字段的方式,修改 Android 平台上公开提供的 API。
  • 设备实现者可以修改 API 的底层实现,但此类修改不得影响任何公开提供的 API 的规定行为和 Java 语言签名。
  • 设备实现者不得将任何公开提供的元素(例如类或接口,或者现有类或接口的字段或方法)添加到上述 API。

“公开提供的元素”是指上游 Android 源代码中不带“@hide”标记的任何构造。换言之,设备实现者不得在上述命名空间中提供新的 API 或更改现有的 API。设备实现者可以执行仅限于内部的修改,但不得向开发者通告或以其他方式公开这些修改。

设备实现者可以添加自定义 API,但任何此类 API 均不得位于归其他组织拥有或表示其他组织的命名空间内。例如,设备实现者不得向 com.google.* 或类似命名空间添加 API;只有 Google 可以向此类命名空间添加 API。同样,Google 也不得向其他公司的命名空间添加 API。

如果设备实现者提议改进上述某个软件包命名空间(例如向现有 API 添加实用的新功能,或添加新的 API),实现者应访问 source.android.com,并按照该网站上的信息开始贡献更改和代码。

请注意,上述限制对应于 Java 编程语言中命名 API 的标准惯例;本节只是强调这些惯例,并通过将其纳入本兼容性定义来使其具有约束力。

3.7. 虚拟机兼容性

设备实现必须支持完整的 Dalvik 可执行文件 (DEX) 字节码规范和 Dalvik 虚拟机语义 [资源 10]。

设备实现必须配置 Dalvik,以便向屏幕被归类为中密度或低密度的设备上的每个应用分配至少 16MB 的内存。设备实现必须配置 Dalvik,以便向屏幕被归类为高密度的设备上的每个应用分配至少 24MB 的内存。请注意,设备实现可以分配比这些数字更多的内存,但并非必须如此。

3.8. 界面兼容性

Android 平台包含一些开发者 API,允许开发者接入系统界面。设备实现必须将这些标准界面 API 整合到他们开发的自定义界面中,具体如下文所述。

3.8.1. widget

Android 定义了一种组件类型以及对应的 API 和生命周期,供应用向最终用户提供“AppWidget”[资源 11]。Android 开源参考版本包含一个启动器应用,该应用包含可让用户从主屏幕添加、查看和移除 AppWidget 的界面元素。

设备实现者可以用替代启动器替换参考启动器(即主屏幕)。替代启动器应包含对 AppWidget 的内置支持,并提供用于直接在启动器中添加、配置、查看和移除 AppWidget 的界面元素。替代启动器可以省略这些界面元素;不过,如果省略这些界面元素,设备实现者必须提供可从启动器访问的单独应用,以便用户添加、配置、查看和移除 AppWidget。

3.8.2. 通知

Android 包含一些可供开发者通知用户值得注意的事件的 API [资源 12]。设备实现者必须为如此定义的每类通知(具体而言是声音、振动、指示灯和状态栏)提供支持。

此外,实现必须正确渲染 API [资源 13] 或状态栏图标样式指南 [资源 14] 中提供的所有资源(图标、声音文件等)。设备实现者可以为用户提供替代通知体验,而不使用参考 Android 开源实现提供的体验;不过,此类替代通知系统必须支持现有的通知资源(如上所述)。

Android 包含一些可让开发者在其应用中纳入搜索功能以及将其应用数据提供给全局系统搜索使用的 API [资源 15]。一般来说,此功能会包括一个系统级界面,以便用户输入查询、在用户输入时显示建议,以及显示搜索结果。这些 Android API 可让开发者重复使用此界面,以在其应用内提供搜索功能,还可让开发者向通用的全局搜索界面提供搜索结果。

设备实现必须包含单个共享的系统级搜索界面,并且该界面能够在用户输入内容时实时提供建议。设备实现必须实现,可让开发者重复使用此界面在其自己的应用中提供搜索功能的 API。设备实现必须实现,在搜索框以全局搜索模式运行时,可让第三方应用向搜索框中添加建议的 API。如果没有安装任何可利用此功能的第三方应用,则默认行为应为显示网页搜索引擎的搜索结果和建议。

设备实现可以附带替代搜索界面,但应包含专用的硬或软搜索按钮(可以随时使用该按钮在任何应用中调用搜索框架),其行为在 API 文档中提供。

3.8.4. 消息框

应用可以使用“消息框”API(定义见 [资源 16])向最终用户显示简短的非模态字符串,这些字符串会在短暂显示后消失。设备实现必须以某种可见性非常高的方式向最终用户显示来自应用的消息框。

3.8.5. 动态壁纸

Android 定义了一种组件类型以及对应的 API 和生命周期,供应用向最终用户提供一个或多个“动态壁纸”[资源 17]。动态壁纸是具备有限输入功能且作为壁纸显示在其他应用之后的动画、图案或类似图片。

如果硬件能够在不限制功能且不会对其他应用造成负面影响的情况下,以合理的帧速率运行所有动态壁纸,则会被视为能够可靠地运行动态壁纸。如果硬件中的限制会导致壁纸和/或应用崩溃、无法正常运行、占用过多 CPU/消耗过多电池电量,或者运行时的帧速率低得令人无法接受,相应硬件会被视为无法运行动态壁纸。例如,有些动态壁纸可能会利用 Open GL 1.0 或 2.0 上下文来渲染其内容。动态壁纸将无法在不支持多个 OpenGL 上下文的硬件上可靠地运行,因为使用 OpenGL 上下文的动态壁纸可能会与其他同样使用 OpenGL 上下文的应用发生冲突。

如果设备实现能够可靠地运行动态壁纸(如上所述),则应实现动态壁纸。如果设备实现被判定为无法可靠地运行动态壁纸(如上所述),则不得实现动态壁纸。

4. 参考软件兼容性

设备实现者必须使用以下开源应用测试实现兼容性:

  • 计算器(包含在 SDK 中)
  • Lunar Lander(包含在 SDK 中)
  • “Android 应用”参考应用 [资源 18]。

实现必须能够正确启动并运行上述每个应用,才会被视为兼容实现。

此外,设备实现必须测试以下每个冒烟测试应用的每个菜单项(包括所有子菜单):

  • ApiDemos(包含在 SDK 中)
  • ManualSmokeTests(包含在 CTS 中)

上述应用中的每个测试用例必须在设备实现中正常运行。

5. 应用打包兼容性

设备实现必须安装并运行官方 Android SDK 中包含的“aapt”工具生成的 Android“.apk”文件 [资源 19]。

设备实现不得通过会导致相应文件无法在其他兼容设备上正确安装和运行的方式,扩展 .apk [资源 20]、Android 清单 [资源 21] 或 Dalvik 字节码 [资源 10] 格式。设备实现者应使用 Dalvik 的参考上游实现,以及该参考实现的软件包管理系统。

6. 多媒体兼容性

设备实现必须支持以下多媒体编解码器。在 Android 开源项目的首选 Android 实现中,所有这些编解码器都是作为软件实现提供的。

请注意,Google 和开放手机联盟 (Open Handset Alliance) 均未做过任何关于这些编解码器中没有使用第三方专利的声明。打算在硬件或软件产品中使用此源代码的用户请注意,实现此代码(包括在开源软件或共享软件中实现)可能需要获得相关专利持有者的专利许可。

音频
名称 编码器 解码器 详细信息 文件/容器格式
AAC LC/LTP   X 采用标准比特率的任意组合的单声道/立体声内容,最高可达 160 kbps,采样率为 8kHz 至 48kHz 3GPP (.3gp) 和 MPEG-4(.mp4、.m4a)。不支持原始 AAC (.aac)
HE-AACv1 (AAC+)   X
HE-AACv2(增强型 AAC+)   X
AMR-NB X X 4.75-12.2 kbps,采样率为 8 kHz 3GPP (.3gp)
AMR-WB   X 有 9 个比特率(介于 6.60-23.85 kbit/s 之间)可供选择,采样率为 16kHz 3GPP (.3gp)
MP3   X 单声道/立体声 8-320Kbps 恒定 (CBR) 或可变比特率 (VBR) MP3 (.mp3)
MIDI   X MIDI 类型 0 和 1。DLS 版本 1 和 2。XMF 和 Mobile XMF。支持铃声格式 RTTTL/RTX、OTA 和 iMelody 类型 0 和 1(.mid、.xmf、.mxmf)。以及 RTTTL/RTX(.rtttl、.rtx)、OTA (.ota) 和 iMelody (.imy)
Ogg Vorbis   X   Ogg (.ogg)
PCM   X 8 位和 16 位线性 PCM(比特率最高可达到硬件上限) WAVE (.wav)
图片
JPEG X X 基准式 + 渐进式  
GIF   X    
PNG X X    
BMP   X    
视频
H.263 X X   3GPP (.3gp) 文件
H.264   X   3GPP (.3gp) 和 MPEG-4 (.mp4) 文件
MPEG4 Simple Profile   X   3GPP (.3gp) 文件

请注意,上表并未列出大多数视频编解码器的特定比特率要求。这是因为,在实践中,当前的设备硬件支持的比特率未必正好就是相关标准指定的所需比特率。设备实现应支持硬件上可行的最高比特率,但不超过规范规定的上限。

7. 开发者工具兼容性

设备实现必须支持 Android SDK 中提供的 Android 开发者工具。具体而言,与 Android 兼容的设备必须兼容:

  • Android 调试桥(简称 adb)[资源 19]
    设备实现必须支持 Android SDK 中载述的所有 adb 函数。默认情况下,设备端 adb 守护程序应处于非活跃状态,但必须有一种可供用户使用的 Android 调试桥开启机制。
  • Dalvik 调试监控服务(简称 ddms)[资源 19]
    设备实现必须支持 Android SDK 中载述的所有 ddms 功能。由于 ddms 使用 adb,因此对 ddms 的支持应默认处于停用状态,但只要用户如上所述启用了 Android 调试桥,设备实现就必须提供这种支持。
  • Monkey [资源 22]
    设备实现必须包含 Monkey 框架,并使其可供应用使用。

8. 硬件兼容性

Android 旨在为设备实现者打造创新的外形规格和配置提供支持。同时,Android 开发者希望某些硬件、传感器和 API 能在所有 Android 设备上使用。本节列出了所有 Android 2.1 兼容设备都必须支持的硬件功能。

如果设备包含特定的硬件组件,而该组件具有针对第三方开发者的相应 API,该设备实现必须实现该 API(如 Android SDK 文档中所定义)。如果 SDK 中的某个 API 需要与某个被规定为可选组件的硬件组件互动,但设备实现不具备该组件,那么:

  • 必须存在该组件 API 的类定义
  • 该 API 的行为必须以某种合理的方式实现为空操作
  • 在 SDK 文档允许的情况下,API 方法必须返回 null 值
  • 在 SDK 文档不允许返回 null 值的情况下,API 方法必须返回类的空操作实现

这些要求的一个典型适用情况示例就是电话 API:即使在非手机设备上,这些 API 也必须实现为合理的空操作。

设备实现必须通过 android.content.pm.PackageManager 类中的 getSystemAvailableFeatures()hasSystemFeature(String) 方法准确报告准确的硬件配置信息。

8.1. 显示

Android 2.1 包含一些可在某些情况下执行某些自动扩缩和转换操作的功能,以确保第三方应用能够在各种硬件配置上正常运行 [资源 23]。设备必须正确实现本节中详细说明的这些行为。

对于 Android 2.1,以下是最常见的屏幕配置:

屏幕类型 宽度(像素) 高度(像素) 对角线长度范围(英寸) 屏幕尺寸组 屏幕密度组
QVGA 240 320 2.6 - 3.0
WQVGA 240 400 3.2 - 3.5 标准
FWQVGA 240 432 3.5 - 3.8 标准
HVGA 320 480 3.0 - 3.5 标准
WVGA 480 800 3.3 - 4.0 标准
FWVGA 480 854 3.5 - 4.0 标准
WVGA 480 800 4.8 - 5.5
FWVGA 480 854 5.0 - 5.8

与上述某个标准配置对应的设备实现必须配置为通过 android.content.res.Configuration [资源 24] 类向应用报告指定的屏幕尺寸。

某些 .apk 软件包的清单没有将它们标识为支持特定的密度范围。运行此类应用时,应遵循以下限制条件:

  • 设备实现必须将 .apk 中缺少密度限定符的资源解读为默认为“中”(在 SDK 文档中称为“mdpi”)。
  • 在“低”密度屏幕上运行时,设备实现必须根据因子 0.75 缩容中/mdpi 资源。
  • 在“高”密度屏幕上运行时,设备实现必须根据因子 1.5 扩容中/mdpi 资源。
  • 设备实现不得在密度范围内扩缩资源,并且必须根据密度范围内的这些因子来扩缩资源。

8.1.2. 非标准屏幕配置

与第 8.1.1 节中列出的任一标准配置不匹配的屏幕配置需要额外考虑,并具有兼容性。设备实现者必须与第 12 节中提供的 Android 兼容性团队联系,以获取关于屏幕尺寸范围、密度和缩放比例的分类。获得这些信息后,设备实现必须按指定方式实现它们。

请注意,某些屏幕配置(例如超大或超小的屏幕以及某些宽高比)与 Android 2.1 根本不兼容;因此,建议设备实现者在开发过程中尽早与 Android 兼容性团队联系。

8.1.3. 显示指标

设备实现必须为 android.util.DisplayMetrics [资源 25] 中定义的所有显示指标报告正确的值。

8.2. 键盘

设备实现:

  • 必须支持输入管理框架(可让第三方开发者创建输入管理引擎,即软键盘),详见 developer.android.com
  • 必须提供至少一个软键盘实现(无论是否存在硬键盘)
  • 可以包含额外的软键盘实现
  • 可以包含硬件键盘
  • 不得包含与 android.content.res.Configuration.keyboard [资源 24] 中指定的任何格式(即,QWERTY 键盘或 12 键)都不匹配的硬件键盘

8.3. 非触摸导航

设备实现:

  • 可以省略非触摸导航选项(即可以省略轨迹球、方向键或滚轮)
  • 必须针对 android.content.res.Configuration.navigation 报告正确的值 [资源 24]

8.4. 屏幕方向

兼容的设备必须支持按应用动态设置屏幕方向(纵向或横向)。也就是说,如果应用请求使用特定屏幕方向,设备必须遵从该请求。设备实现可以选择纵向或横向作为默认屏幕方向。

无论何时通过 android.content.res.Configuration.orientation、android.view.Display.getOrientation() 或其他 API 查询设备当前屏幕方向,设备都必须报告正确的值。

8.5. 触摸屏输入

设备实现:

  • 必须具有触摸屏
  • 可以有电容式触摸屏或电阻式触摸屏
  • 必须报告 android.content.res.Configuration 的值 [资源 24],其值应与设备上特定触摸屏的类型相对应

8.6. USB

设备实现:

  • 必须实现 USB 客户端,该客户端可通过标准 USB-A 端口连接到 USB 主机
  • 必须通过 USB 实现 Android 调试桥(如第 7 节所述)
  • 必须实现 USB 大容量存储规范,以允许连接到设备的主机访问 /sdcard 卷的内容
  • 应使用设备端的 Micro USB 外形规格
  • 可以在设备端包含非标准端口,但如果是这样,则必须附带能够用于将自定义引脚连接到标准 USB-A 端口的数据线

8.7. 导航键

主屏幕、菜单和返回功能对于 Android 导航范式至关重要。设备实现必须随时为用户提供这些功能,无论应用状态为何。应通过专用按钮实现这些功能,也可以使用专用软件按键、手势、触摸板等来实现。但如果是这样,这些功能必须始终可以访问,并且不得遮住或影响可用的应用显示区域。

设备实现者还应提供专用的搜索键。设备实现者还可以为通话提供发送键和结束键。

8.8. 无线数据网络

设备实现必须支持无线高速数据网络。具体而言,设备实现必须支持至少一种能够达到 200Kbit/sec 或更高传输速率的无线数据标准。满足此要求的技术包括 EDGE、HSPA、EV-DO、802.11g 等。

如果设备实现包含一种特定模态,而 Android SDK 包含一个用于该模态的 API(即 Wi-Fi、GSM 或 CDMA),那么该实现必须支持此 API。

设备可以实现多种形式的无线数据连接。设备可以实现有线数据连接(例如以太网),但必须至少包含上述一种形式的无线连接。

8.9. 相机

设备实现必须包含相机。随附的相机:

  • 分辨率必须至少为 200 万像素
  • 应在相机驱动程序中实现硬件自动对焦或软件自动对焦(对应用软件透明)
  • 可以具有固定焦距硬件或 EDOF(扩展景深)硬件
  • 可以包含闪光灯。如果相机包含闪光灯,当已在相机预览 surface 上注册 android.hardware.Camera.PreviewCallback 实例时,闪光灯不得亮起,除非应用已通过启用 Camera.Parameters 对象的 FLASH_MODE_AUTOFLASH_MODE_ON 属性明确启用闪光灯。请注意,此项限制不适用于设备的内置系统相机应用,而是仅适用于使用 Camera.PreviewCallback 的第三方应用。

设备实现必须为相机相关 API 实现以下行为:

  1. 如果应用从未调用过 android.hardware.Camera.Parameters.setPreviewFormat(int),设备必须使用 android.hardware.PixelFormat.YCbCr_420_SP 获取提供给应用回调的预览数据。
  2. 如果应用注册了 android.hardware.Camera.PreviewCallback 实例,并且系统在预览格式为 YCbCr_420_SP 时调用 onPreviewFrame() 方法,那么传递到 onPreviewFrame() 的 byte[] 中的数据必须进一步采用 NV21 编码格式。(这是 7k 硬件系列原生采用的格式。)也就是说,NV21 必须是默认设置。

无论设备是否包含硬件自动对焦或其他功能,设备实现都必须实现 Android 2.1 SDK 文档 [资源 26] 中包含的完整相机 API。例如,没有自动对焦功能的相机仍必须调用所有已注册的 android.hardware.Camera.AutoFocusCallback 实例(即使这与非自动对焦相机无关)。

如果底层硬件支持相应功能,设备实现必须识别并遵从 android.hardware.Camera.Parameters 类中定义为常量的每个参数名称。如果设备硬件不支持某项功能,API 的行为方式必须与载述的行为方式一致。反之,设备实现不得遵从或识别传递给 android.hardware.Camera.setParameters() 方法的字符串常量(在 android.hardware.Camera.Parameters 中载述为常量的字符串常量除外),除非这些常量以表示设备实现者名称的字符串作为前缀。也就是说,设备实现必须支持所有标准相机参数(如果硬件允许),且不得支持自定义相机参数类型,除非参数名称通过字符串前缀明确表示为非标准。

8.10. 加速度计

设备实现必须包含 3 轴加速度计,并且必须能够以 50 Hz 或更高的频率传递事件。加速度计使用的坐标系必须符合 Android API 中所述的 Android 传感器坐标系(请参阅 [资源 27])。

8.11. 罗盘

设备实现必须包含 3 轴罗盘,并且必须能够以 10 Hz 或更高的频率传递事件。罗盘使用的坐标系必须符合 Android API 中定义的 Android 传感器坐标系(请参阅 [资源 27])。

8.12. GPS

设备实现必须包含 GPS,并且应包含某种形式的“辅助 GPS”技术,以便最大限度地缩短 GPS 锁定时间。

8.13. 电话

Android 2.1 可以在不包含电话硬件的设备上使用。也就是说,Android 2.1 可与非电话设备兼容。不过,如果设备实现包含 GSM 或 CDMA 电话,则必须全面支持针对该技术的 API。如果设备实现不包含电话硬件,则必须将所有相关 API 实现为空操作。

另请参阅第 8.8 节“无线数据网络”。

8.14. 内存和存储空间

设备实现必须有至少 92MB 的内存供内核和用户空间使用。这 92MB 不包括不在内核控制范围之内的所有专供硬件组件(例如无线装置、存储器等)使用的内存。

设备实现必须有至少 150MB 的非易失性存储空间可用于存储用户数据。也就是说,/data 分区必须至少为 150MB。

注意:本节是由 Erratum EX6580 修改。

8.15. 应用共享的存储空间

设备实现必须为应用提供共享存储空间。提供的共享存储空间不得小于 2GB。

设备实现必须配有默认装载且可直接使用的共享存储空间。如果共享存储空间未装载在 Linux 路径 /sdcard 下,则设备必须包含从 /sdcard 指向实际装载点的 Linux 符号链接。

设备实现必须按照文档中所述,对该共享存储空间强制授予 android.permission.WRITE_EXTERNAL_STORAGE 权限。必须允许任何获得该权限的应用对共享存储空间执行写入操作。

设备实现可以具有相应的硬件来安装可供用户使用的可移动存储设备,例如安全数字卡。或者,设备实现可以将内部(不可移动的)存储空间分配为应用的共享存储空间。

无论使用何种形式的共享存储空间,共享存储空间都必须实现 USB 大容量存储,如第 8.6 节所述。共享存储空间是出厂时随附的,必须装载 FAT 文件系统。

下面列举了两个常见示例。如果设备实现包含 SD 卡插槽以满足共享存储空间要求,则设备在出售给用户时必须包含至少为 2GB 的 FAT 格式的 SD 卡,并且必须默认装载该卡。或者,如果设备实现使用内部固定存储空间来满足此要求,则该存储空间必须至少为 2GB,并且必须装载在 /sdcard 上(如果装载在其他位置,则 /sdcard 必须是指向实际位置的符号链接)。

注意:本节是由 Erratum EX6580 添加。

8.16. 蓝牙

设备实现必须包含蓝牙收发器。设备实现必须支持基于 RFCOMM 的蓝牙 API(如 SDK 文档中所述)[资源 29]。设备实现应实现适合设备的相关蓝牙配置文件,例如 A2DP、AVRCP、OBEX 等。

注意:本节是由 Erratum EX6580 添加。

9. 性能兼容性

Android 兼容性计划的其中一个目标就是为消费者提供一致的应用体验。兼容的实现不仅必须确保应用能够在设备上运行正常,还必须保证应用以合理的性能正常运行,并提供良好的整体用户体验。设备实现必须满足下表中定义的 Android 2.1 兼容设备关键性能指标:

指标 性能阈值 注释
应用启动时间 以下应用应在指定时间内完成启动。
  • 浏览器:不到 1300 毫秒
  • 彩信/短信:不到 700 毫秒
  • AlarmClock:不到 650 毫秒
启动时间是指完成应用默认 activity 加载所用的总时间,包括启动 Linux 进程、将 Android 软件包加载到 Dalvik 虚拟机以及调用 onCreate 所用的时间。
并发应用 在启动了多个应用的情况下,如果重新启动已启动且已在运行的应用,所用时间不得超过原来的启动时间。  

10. 安全模型兼容性

设备实现必须实现与 Android 平台安全模型(具体定义请参见 Android 开发者文档 > API 指南 > 安全和权限参考文档 [资源 28])一致的安全模型。设备实现必须支持安装自签名应用,而且无需从任何第三方/权威机构获得任何额外的权限/证书。具体来说,兼容的设备必须支持下面几个小节中介绍的安全机制。

10.1. 权限

设备实现必须支持 Android 开发者文档中定义的 Android 权限模型 [资源 28]。具体来说,实现必须如 SDK 文档中所述,强制授予所定义的每项权限;不得省略、更改或忽略任何权限。只要新的权限 ID 字符串不是位于 android.* 命名空间内,实现便可以添加额外的权限。

10.2. UID 和进程隔离

设备实现必须支持 Android 应用沙盒模型。在该模型中,每个应用都是在单独的进程中作为独一无二的 Unix 样式 UID 运行。设备实现必须支持以同一 Linux 用户 ID 运行多个应用,但前提是这些应用已经过适当签名和构建(具体定义请参见安全和权限参考文档 [资源 28])。

10.3. 文件系统权限

设备实现必须支持 Android 文件访问权限模型(具体定义请参见安全和权限参考文档 [资源 28])。

11. 兼容性测试套件

设备实现必须通过 Android 开源项目提供的 Android 兼容性测试套件 (CTS) [资源 2] 的测试(使用设备上最终交付的软件)。此外,设备实现者应尽可能多地使用 Android 开源树中的参考实现,并且对于 CTS 中不明确的情况,以及参考源代码中部分内容的任何重新实现,都必须确保兼容性。

CTS 能够在实际设备上运行。与所有软件一样,CTS 自身也可能包含 bug。CTS 的版本发布独立于本兼容性定义,我们可能会针对 Android 2.1 发布多个 CTS 修订版本。设备实现必须通过设备软件发布时可用的最新 CTS 版本的测试。

12. 可更新软件

设备实现必须包含可用于替换整个系统软件的机制。该机制不需要执行“实时”升级 - 也就是说,可能需要重启设备。

可以使用任何方法,但前提是相应方法可以替换设备上的整个预安装软件。例如,以下任何方法都可以满足此要求:

  • 无线下载 (OTA)(通过重新启动进行离线更新)
  • 从主机 PC 上通过 USB 进行“网络共享”更新
  • 通过重新启动进行“离线”更新,以及通过可移动存储设备中的文件进行更新

使用的更新机制必须支持在不擦除用户数据的情况下进行更新。请注意,上游 Android 软件包含满足此要求的更新机制。

在设备实现发布后,如果在其合理的产品生命周期内发现其中存在错误,并且经与 Android 兼容性团队磋商后确定该错误会影响第三方应用的兼容性,设备实现者必须通过可按上述机制应用的可用软件更新来更正该错误。

13. 与我们联系

如需澄清说明以及提出您认为本文档未涵盖的任何问题,请通过 compatibility@android.com 与文档作者联系。