1 2## 3.2\. Soft API Compatibility 3 4In addition to the managed APIs from [section 3.1](#3_1_managed_api_compatibility), 5Android also includes a significant runtime-only “soft” API, in the form of such 6things as intents, permissions, and similar aspects of Android applications that 7cannot be enforced at application compile time. 8 9### 3.2.1\. Permissions 10 11* [C-0-1] Device implementers MUST support and enforce all permission 12constants as documented by the [Permission reference page](http://developer.android.com/reference/android/Manifest.permission.html). 13Note that [section 9](#9_security_model_compatibility) lists additional 14requirements related to the Android security model. 15 16### 3.2.2\. Build Parameters 17 18The Android APIs include a number of constants on the 19[android.os.Build class](http://developer.android.com/reference/android/os/Build.html) 20that are intended to describe the current device. 21 22* [C-0-1] To provide consistent, meaningful values across device 23implementations, the table below includes additional restrictions on the formats 24of these values to which device implementations MUST conform. 25 26<table> 27 <tr> 28 <th>Parameter</th> 29 <th>Details</th> 30 </tr> 31 <tr> 32 <td>VERSION.RELEASE</td> 33 <td>The version of the currently-executing Android system, in human-readable 34 format. This field MUST have one of the string values defined in 35 <a href="http://source.android.com/compatibility/ANDROID_VERSION/versions.html">ANDROID_VERSION</a>.</td> 36 </tr> 37 <tr> 38 <td>VERSION.SDK</td> 39 <td>The version of the currently-executing Android system, in a format 40 accessible to third-party application code. For Android ANDROID_VERSION, 41 this field MUST have the integer value ANDROID_VERSION_INT.</td> 42 </tr> 43 <tr> 44 <td>VERSION.SDK_INT</td> 45 <td>The version of the currently-executing Android system, in a format 46 accessible to third-party application code. For Android ANDROID_VERSION, 47 this field MUST have the integer value ANDROID_VERSION_INT.</td> 48 </tr> 49 <tr> 50 <td>VERSION.INCREMENTAL</td> 51 <td>A value chosen by the device implementer designating the specific build 52 of the currently-executing Android system, in human-readable format. This 53 value MUST NOT be reused for different builds made available to end users. A 54 typical use of this field is to indicate which build number or 55 source-control change identifier was used to generate the build. The value 56 of this field MUST be encodable as printable 7-bit ASCII and match the 57 regular expression “^[^ :\/~]+$”.</td> 58 </tr> 59 <tr> 60 <td>BOARD</td> 61 <td>A value chosen by the device implementer identifying the specific 62 internal hardware used by the device, in human-readable format. A possible 63 use of this field is to indicate the specific revision of the board powering 64 the device. The value of this field MUST be encodable as 7-bit ASCII and 65 match the regular expression “^[a-zA-Z0-9_-]+$”.</td> 66 </tr> 67 <tr> 68 <td>BRAND</td> 69 <td>A value reflecting the brand name associated with the device as known to 70 the end users. MUST be in human-readable format and SHOULD represent the 71 manufacturer of the device or the company brand under which the device is 72 marketed. The value of this field MUST be encodable as 7-bit ASCII and match 73 the regular expression “^[a-zA-Z0-9_-]+$”.</td> 74 </tr> 75 <tr> 76 <td>SUPPORTED_ABIS</td> 77 <td>The name of the instruction set (CPU type + ABI convention) of native 78 code. See <a href="#3_3_native_api_compatibility">section 3.3. Native API 79 Compatibility</a>.</td> 80 </tr> 81 <tr> 82 <td>SUPPORTED_32_BIT_ABIS</td> 83 <td>The name of the instruction set (CPU type + ABI convention) of native 84 code. See <a href="#3_3_native_api_compatibility">section 3.3. Native API 85 Compatibility</a>.</td> 86 </tr> 87 <tr> 88 <td>SUPPORTED_64_BIT_ABIS</td> 89 <td>The name of the second instruction set (CPU type + ABI convention) of 90 native code. See <a href="#3_3_native_api_compatibility">section 3.3. Native 91 API Compatibility</a>.</td> 92 </tr> 93 <tr> 94 <td>CPU_ABI</td> 95 <td>The name of the instruction set (CPU type + ABI convention) of native 96 code. See <a href="#3_3_native_api_compatibility">section 3.3. Native API 97 Compatibility</a>.</td> 98 </tr> 99 <tr> 100 <td>CPU_ABI2</td> 101 <td>The name of the second instruction set (CPU type + ABI convention) of 102 native code. See <a href="#3_3_native_api_compatibility">section 3.3. Native 103 API Compatibility</a>.</td> 104 </tr> 105 <tr> 106 <td>DEVICE</td> 107 <td>A value chosen by the device implementer containing the development name 108 or code name identifying the configuration of the hardware features and 109 industrial design of the device. The value of this field MUST be encodable 110 as 7-bit ASCII and match the regular expression 111 “^[a-zA-Z0-9_-]+$”. This device name MUST NOT change during the 112 lifetime of the product.</td> 113 </tr> 114 <tr> 115 <td>FINGERPRINT</td> 116 <td>A string that uniquely identifies this build. It SHOULD be reasonably 117 human-readable. It MUST follow this template: 118 <p class="small">$(BRAND)/$(PRODUCT)/<br> 119 $(DEVICE):$(VERSION.RELEASE)/$(ID)/$(VERSION.INCREMENTAL):$(TYPE)/$(TAGS)</p> 120 <p>For example:</p> 121<p class="small">acme/myproduct/<br> 122 mydevice:ANDROID_VERSION/LMYXX/3359:userdebug/test-keys</p> 123 <p>The fingerprint MUST NOT include whitespace characters. The value of 124 this field MUST be encodable as 7-bit ASCII.</p></td> 125 </tr> 126 <tr> 127 <td>HARDWARE</td> 128 <td>The name of the hardware (from the kernel command line or /proc). It 129 SHOULD be reasonably human-readable. The value of this field MUST be 130 encodable as 7-bit ASCII and match the regular expression 131 “^[a-zA-Z0-9_-]+$”.</td> 132 </tr> 133 <tr> 134 <td>HOST</td> 135 <td>A string that uniquely identifies the host the build was built on, in 136 human-readable format. There are no requirements on the specific format of 137 this field, except that it MUST NOT be null or the empty string ("").</td> 138 </tr> 139 <tr> 140 <td>ID</td> 141 <td>An identifier chosen by the device implementer to refer to a specific 142 release, in human-readable format. This field can be the same as 143 android.os.Build.VERSION.INCREMENTAL, but SHOULD be a value sufficiently 144 meaningful for end users to distinguish between software builds. The value 145 of this field MUST be encodable as 7-bit ASCII and match the regular 146 expression “^[a-zA-Z0-9._-]+$”.</td> 147 </tr> 148 <tr> 149 <td>MANUFACTURER</td> 150 <td>The trade name of the Original Equipment Manufacturer (OEM) of the 151 product. There are no requirements on the specific format of this field, 152 except that it MUST NOT be null or the empty string (""). This field 153 MUST NOT change during the lifetime of the product.</td> 154 </tr> 155 <tr> 156 <td>MODEL</td> 157 <td>A value chosen by the device implementer containing the name of the 158 device as known to the end user. This SHOULD be the same name under which 159 the device is marketed and sold to end users. There are no requirements on 160 the specific format of this field, except that it MUST NOT be null or the 161 empty string (""). This field MUST NOT change during the 162 lifetime of the product.</td> 163 </tr> 164 <tr> 165 <td>PRODUCT</td> 166 <td>A value chosen by the device implementer containing the development name 167 or code name of the specific product (SKU) that MUST be unique within the 168 same brand. MUST be human-readable, but is not necessarily intended for view 169 by end users. The value of this field MUST be encodable as 7-bit ASCII and 170 match the regular expression “^[a-zA-Z0-9_-]+$”. This product 171 name MUST NOT change during the lifetime of the product.</td> 172 </tr> 173 <tr> 174 <td>SERIAL</td> 175 <td>MUST return "UNKNOWN".</td> 176 </tr> 177 <tr> 178 <td>TAGS</td> 179 <td>A comma-separated list of tags chosen by the device implementer that 180 further distinguishes the build. The tags MUST be encodable as 7-bit ASCII 181 and match the regular expression “^[a-zA-Z0-9._-]+” and MUST 182 have one of the values corresponding to the three typical Android platform 183 signing configurations: release-keys, dev-keys, and test-keys.</td> 184 </tr> 185 <tr> 186 <td>TIME</td> 187 <td>A value representing the timestamp of when the build occurred.</td> 188 </tr> 189 <tr> 190 <td>TYPE</td> 191 <td>A value chosen by the device implementer specifying the runtime 192 configuration of the build. This field MUST have one of the values 193 corresponding to the three typical Android runtime configurations: user, 194 userdebug, or eng.</td> 195 </tr> 196 <tr> 197 <td>USER</td> 198 <td>A name or user ID of the user (or automated user) that generated the 199 build. There are no requirements on the specific format of this field, 200 except that it MUST NOT be null or the empty string ("").</td> 201 </tr> 202 <tr> 203 <td>SECURITY_PATCH</td> 204 <td>A value indicating the security patch level of a build. It MUST signify 205 that the build is not in any way vulnerable to any of the issues described 206 up through the designated Android Public Security Bulletin. It MUST be in 207 the format [YYYY-MM-DD], matching a defined string documented in the 208 <a href="http://source.android.com/security/bulletin"> Android Public Security 209 Bulletin</a> or in the <a href="http://source.android.com/security/advisory"> 210 Android Security Advisory</a>, for example "2015-11-01".</td> 211 </tr> 212 <tr> 213 <td>BASE_OS</td> 214 <td>A value representing the FINGERPRINT parameter of the build that is 215 otherwise identical to this build except for the patches provided in the 216 Android Public Security Bulletin. It MUST report the correct value and if 217 such a build does not exist, report an empty string ("").</td> 218 </tr> 219 <tr> 220 <td><a href="https://developer.android.com/reference/android/os/Build.html#BOOTLOADER">BOOTLOADER</a></td> 221 <td> A value chosen by the device implementer identifying the specific 222 internal bootloader version used in the device, in human-readable format. 223 The value of this field MUST be encodable as 7-bit ASCII and match the 224 regular expression “^[a-zA-Z0-9._-]+$”.</td> 225 </tr> 226 <tr> 227 <td><a href="https://developer.android.com/reference/android/os/Build.html#getRadioVersion()">getRadioVersion()</a></td> 228 <td> MUST (be or return) a value chosen by the device implementer 229 identifying the specific internal radio/modem version used in the device, 230 in human-readable format. If a device does not have any internal 231 radio/modem it MUST return NULL. The value of this field MUST be 232 encodable as 7-bit ASCII and match the regular expression 233 “^[a-zA-Z0-9._-,]+$”.</td> 234 </tr> 235 <tr> 236 <td><a href="https://developer.android.com/reference/android/os/Build.html#getSerial()">getSerial()</a></td> 237 <td> MUST (be or return) a hardware serial number, which MUST be available 238 and unique across devices with the same MODEL and MANUFACTURER. The value of 239 this field MUST be encodable as 7-bit ASCII and match the regular expression 240 “^[a-zA-Z0-9._-,]+$”.</td> 241 </tr> 242</table> 243 244### 3.2.3\. Intent Compatibility 245 246#### 3.2.3.1\. Core Application Intents 247 248Android intents allow application components to request functionality from 249other Android components. The Android upstream project includes a list of 250applications considered core Android applications, which implements several 251intent patterns to perform common actions. 252 253* [C-0-1] Device implementations MUST preload one or more applications or 254service components with an intent handler, for all the public intent filter 255patterns defined by the following core android applications in AOSP: 256 257 * Desk Clock 258 * Browser 259 * Calendar 260 * Contacts 261 * Gallery 262 * GlobalSearch 263 * Launcher 264 * Music 265 * Settings 266 267#### 3.2.3.2\. Intent Resolution 268 269* [C-0-1] As Android is an extensible platform, device implementations MUST 270allow each intent pattern referenced in [section 3.2.3.1](#3_2_3_1_core_application_intents) 271, except for Settings, to be overridden by third-party applications. The 272upstream Android open source implementation allows this by default. 273 274* [C-0-2] Dvice implementers MUST NOT attach special privileges to system 275applications' use of these intent patterns, or prevent third-party applications 276from binding to and assuming control of these patterns. This prohibition 277specifically includes but is not limited to disabling the “Chooser” user 278interface that allows the user to select between multiple applications that all 279handle the same intent pattern. 280 281* [C-0-3] Device implementations MUST provide a user interface for users to 282modify the default activity for intents. 283 284* However, device implementations MAY provide default activities for specific 285URI patterns (e.g. http://play.google.com) when the default activity provides a 286more specific attribute for the data URI. For example, an intent filter pattern 287specifying the data URI “http://www.android.com” is more specific than the 288browser's core intent pattern for “http://”. 289 290Android also includes a mechanism for third-party apps to declare an 291authoritative default [app linking behavior](https://developer.android.com/training/app-links) 292for certain types of web URI intents. When such authoritative declarations are 293defined in an app's intent filter patterns, device implementations: 294 295* [C-0-4] MUST attempt to validate any intent filters by performing the 296validation steps defined in the [Digital Asset Links specification](https://developers.google.com/digital-asset-links) 297as implemented by the Package Manager in the upstream Android Open Source 298Project. 299* [C-0-5] MUST attempt validation of the intent filters during the installation of 300the application and set all successfully validated URI intent filters as 301default app handlers for their URIs. 302* MAY set specific URI intent filters as default app handlers for their URIs, 303if they are successfully verified but other candidate URI filters fail 304verification. If a device implementation does this, it MUST provide the 305user appropriate per-URI pattern overrides in the settings menu. 306* MUST provide the user with per-app App Links controls in Settings as 307follows: 308 * [C-0-6] The user MUST be able to override holistically the default app 309 links behavior for an app to be: always open, always ask, or never open, 310 which must apply to all candidate URI intent filters equally. 311 * [C-0-7] The user MUST be able to see a list of the candidate URI intent 312 filters. 313 * The device implementation MAY provide the user with the ability to 314 override specific candidate URI intent filters that were successfully 315 verified, on a per-intent filter basis. 316 * [C-0-8] The device implementation MUST provide users with the ability to 317 view and override specific candidate URI intent filters if the device 318 implementation lets some candidate URI intent filters succeed 319 verification while some others can fail. 320 321#### 3.2.3.3\. Intent Namespaces 322 323* [C-0-1] Device implementations MUST NOT include any Android component that 324honors any new intent or broadcast intent patterns using an ACTION, CATEGORY, or 325other key string in the android.* or com.android.* namespace. 326* [C-0-2] Device implementers MUST NOT include any Android components that 327honor any new intent or broadcast intent patterns using an ACTION, CATEGORY, or 328other key string in a package space belonging to another organization. 329* [C-0-3] Device implementers MUST NOT alter or extend any of the intent 330patterns used by the core apps listed in [section 3.2.3.1](#3_2_3_1_core_application_intents). 331* Device implementations MAY include intent patterns using namespaces clearly 332and obviously associated with their own organization. This prohibition is 333analogous to that specified for Java language classes in [section 3.6](#3_6_api_namespaces). 334 335#### 3.2.3.4\. Broadcast Intents 336 337Third-party applications rely on the platform to broadcast certain intents to 338notify them of changes in the hardware or software environment. 339 340Device implementations: 341 342* [C-0-1] MUST broadcast the public broadcast intents in response to 343 appropriate system events as described in the SDK documentation. Note that 344 this requirement is not conflicting with section 3.5 as the limitation for 345 background applications are also described in the SDK documentation. 346 347#### 3.2.3.5\. Default App Settings 348 349Android includes settings that provide users an easy way to select their 350default applications, for example for Home screen or SMS. 351 352Where it makes sense, device implementations MUST provide a similar settings 353menu and be compatible with the intent filter pattern and API methods described 354in the SDK documentation as below. 355 356If device implementations report `android.software.home_screen`, they: 357 358* [C-1-1] MUST honor the [`android.settings.HOME_SETTINGS`]( 359http://developer.android.com/reference/android/provider/Settings.html#ACTION_HOME_SETTINGS) 360intent to show a default app settings menu for Home Screen. 361 362If device implementations report `android.hardware.telephony`, they: 363 364* [C-2-1] MUST provide a settings menu that will call the 365[`android.provider.Telephony.ACTION_CHANGE_DEFAULT`]( 366http://developer.android.com/reference/android/provider/Telephony.Sms.Intents.html#ACTION_CHANGE_DEFAULT) 367intent to show a dialog to change the default SMS application. 368 369* [C-2-2] MUST honor the [`android.telecom.action.CHANGE_DEFAULT_DIALER`]( 370https://developer.android.com/reference/android/telecom/TelecomManager.html#ACTION_CHANGE_DEFAULT_DIALER) 371intent to show a dialog to allow the user to change the default Phone 372application. 373 * MUST use the user-selected default Phone app's UI for incoming and 374 outgoing calls except for emergency calls, which would use the 375 preinstalled Phone app. 376 377* [C-2-3] MUST honor the [android.telecom.action.CHANGE_PHONE_ACCOUNTS]( 378https://developer.android.com/reference/android/telecom/TelecomManager.html#ACTION_CHANGE_PHONE_ACCOUNTS) 379intent to provide user affordance to configure the [`ConnectionServices`]( 380https://developer.android.com/reference/android/telecom/ConnectionService.html) 381associated with the [`PhoneAccounts`]( 382https://developer.android.com/reference/android/telecom/PhoneAccount.html), as 383well as a default PhoneAccount that the telecommunications service provider will 384use to place outgoing calls. The AOSP implementation meets this requirement by 385including a "Calling Accounts option" menu within the "Calls" settings menu. 386 387* [C-2-4] MUST allow [`android.telecom.CallRedirectionService`]( 388 https://developer.android.com/reference/android/telecom/CallRedirectionService) for an app 389 that holds the [`android.app.role.CALL_REDIRECTION`]( 390 https://developer.android.com/reference/android/app/role/RoleManager#ROLE_CALL_REDIRECTION) 391 role. 392* [C-2-5] MUST provide the user affordance to choose an app 393 that holds the [`android.app.role.CALL_REDIRECTION`]( 394 https://developer.android.com/reference/android/app/role/RoleManager#ROLE_CALL_REDIRECTION) 395 role. 396 397If device implementations report `android.hardware.nfc.hce`, they: 398 399* [C-3-1] MUST honor the [android.settings.NFC_PAYMENT_SETTINGS]( 400http://developer.android.com/reference/android/provider/Settings.html#ACTION_NFC_PAYMENT_SETTINGS) 401intent to show a default app settings menu for Tap and Pay. 402 403If device implementations support the `VoiceInteractionService` and have more 404than one application using this API installed at a time, they: 405 406* [C-4-1] MUST honor the [`android.settings.ACTION_VOICE_INPUT_SETTINGS`]( 407 https://developer.android.com/reference/android/provider/Settings.html#ACTION_VOICE_INPUT_SETTINGS) 408 intent to show a default app settings menu for voice input and assist. 409 410### 3.2.4\. Activities on secondary/multiple displays 411 412If device implementations allow launching normal [Android Activities]( 413https://developer.android.com/reference/android/app/Activity.html) on more than 414one display, they: 415 416* [C-1-1] MUST set the `android.software.activities_on_secondary_displays` 417 feature flag. 418* [C-1-2] MUST guarantee API compatibility similar to an activity running on 419 the primary display. 420* [C-1-3] MUST land the new activity on the same display as the activity that 421 launched it, when the new activity is launched without specifying a target 422 display via the [`ActivityOptions.setLaunchDisplayId()`]( 423 https://developer.android.com/reference/android/app/ActivityOptions.html#setLaunchDisplayId%28int%29) 424 API. 425* [C-1-4] MUST destroy all activities, when a display with the 426 [`Display.FLAG_PRIVATE`](http://developer.android.com/reference/android/view/Display.html#FLAG_PRIVATE) 427 flag is removed. 428* [C-1-5] MUST securely hide content on all screens when the device is locked 429 with a secure lock screen, unless the app opts in to show on top of lock 430 screen using [`Activity#setShowWhenLocked()`]( 431 https://developer.android.com/reference/android/app/Activity#setShowWhenLocked%28boolean%29) 432 API. 433* SHOULD have [`android.content.res.Configuration`]( 434 https://developer.android.com/reference/android/content/res/Configuration.html) 435 which corresponds to that display in order to be displayed, operate 436 correctly, and maintain compatibility if an activity is launched on 437 secondary display. 438 439If device implementations allow launching normal [Android Activities]( 440https://developer.android.com/reference/android/app/Activity.html) on secondary 441displays and a secondary display has the [android.view.Display.FLAG_PRIVATE]( 442https://developer.android.com/reference/android/view/Display.html#FLAG_PRIVATE) 443flag: 444 445* [C-3-1] Only the owner of that display, system, and activities that are 446 already on that display MUST be able to launch to it. Everyone can launch to 447 a display that has [android.view.Display.FLAG_PUBLIC](https://developer.android.com/reference/android/view/Display.html#FLAG_PUBLIC) 448 flag. 449