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. There are 56 no requirements on the specific format of this field, except that it MUST 57 NOT be null or the empty string ("").</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. If other fields 124 included in the template above have whitespace characters, they MUST be 125 replaced in the build fingerprint with another character, such as the 126 underscore ("_") character. The value of this field MUST be encodable as 127 7-bit ASCII.</p></td> 128 </tr> 129 <tr> 130 <td>HARDWARE</td> 131 <td>The name of the hardware (from the kernel command line or /proc). It 132 SHOULD be reasonably human-readable. The value of this field MUST be 133 encodable as 7-bit ASCII and match the regular expression 134 “^[a-zA-Z0-9_-]+$”.</td> 135 </tr> 136 <tr> 137 <td>HOST</td> 138 <td>A string that uniquely identifies the host the build was built on, in 139 human-readable format. There are no requirements on the specific format of 140 this field, except that it MUST NOT be null or the empty string ("").</td> 141 </tr> 142 <tr> 143 <td>ID</td> 144 <td>An identifier chosen by the device implementer to refer to a specific 145 release, in human-readable format. This field can be the same as 146 android.os.Build.VERSION.INCREMENTAL, but SHOULD be a value sufficiently 147 meaningful for end users to distinguish between software builds. The value 148 of this field MUST be encodable as 7-bit ASCII and match the regular 149 expression “^[a-zA-Z0-9._-]+$”.</td> 150 </tr> 151 <tr> 152 <td>MANUFACTURER</td> 153 <td>The trade name of the Original Equipment Manufacturer (OEM) of the 154 product. There are no requirements on the specific format of this field, 155 except that it MUST NOT be null or the empty string (""). This field 156 MUST NOT change during the lifetime of the product.</td> 157 </tr> 158 <tr> 159 <td>MODEL</td> 160 <td>A value chosen by the device implementer containing the name of the 161 device as known to the end user. This SHOULD be the same name under which 162 the device is marketed and sold to end users. There are no requirements on 163 the specific format of this field, except that it MUST NOT be null or the 164 empty string (""). This field MUST NOT change during the 165 lifetime of the product.</td> 166 </tr> 167 <tr> 168 <td>PRODUCT</td> 169 <td>A value chosen by the device implementer containing the development name 170 or code name of the specific product (SKU) that MUST be unique within the 171 same brand. MUST be human-readable, but is not necessarily intended for view 172 by end users. The value of this field MUST be encodable as 7-bit ASCII and 173 match the regular expression “^[a-zA-Z0-9_-]+$”. This product 174 name MUST NOT change during the lifetime of the product.</td> 175 </tr> 176 <tr> 177 <td>SERIAL</td> 178 <td>A hardware serial number, which MUST be available and unique across 179 devices with the same MODEL and MANUFACTURER. The value of this field MUST 180 be encodable as 7-bit ASCII and match the regular expression 181 “^([a-zA-Z0-9]{6,20})$”.</td> 182 </tr> 183 <tr> 184 <td>TAGS</td> 185 <td>A comma-separated list of tags chosen by the device implementer that 186 further distinguishes the build. This field MUST have one of the values 187 corresponding to the three typical Android platform signing configurations: 188 release-keys, dev-keys, test-keys.</td> 189 </tr> 190 <tr> 191 <td>TIME</td> 192 <td>A value representing the timestamp of when the build occurred.</td> 193 </tr> 194 <tr> 195 <td>TYPE</td> 196 <td>A value chosen by the device implementer specifying the runtime 197 configuration of the build. This field MUST have one of the values 198 corresponding to the three typical Android runtime configurations: user, 199 userdebug, or eng.</td> 200 </tr> 201 <tr> 202 <td>USER</td> 203 <td>A name or user ID of the user (or automated user) that generated the 204 build. There are no requirements on the specific format of this field, 205 except that it MUST NOT be null or the empty string ("").</td> 206 </tr> 207 <tr> 208 <td>SECURITY_PATCH</td> 209 <td>A value indicating the security patch level of a build. It MUST signify 210 that the build is not in any way vulnerable to any of the issues described 211 up through the designated Android Public Security Bulletin. It MUST be in 212 the format [YYYY-MM-DD], matching a defined string documented in the 213 <a href="source.android.com/security/bulletin"> Android Public Security 214 Bulletin</a> or in the <a href="http://source.android.com/security/advisory"> 215 Android Security Advisory</a>, for example "2015-11-01".</td> 216 </tr> 217 <tr> 218 <td>BASE_OS</td> 219 <td>A value representing the FINGERPRINT parameter of the build that is 220 otherwise identical to this build except for the patches provided in the 221 Android Public Security Bulletin. It MUST report the correct value and if 222 such a build does not exist, report an empty string ("").</td> 223 </tr> 224 <tr> 225 <td><a href="https://developer.android.com/reference/android/os/Build.html#BOOTLOADER">BOOTLOADER</a></td> 226 <td> A value chosen by the device implementer identifying the specific 227 internal bootloader version used in the device, in human-readable format. 228 The value of this field MUST be encodable as 7-bit ASCII and match the 229 regular expression “^[a-zA-Z0-9._-]+$”.</td> 230 </tr> 231 <tr> 232 <td><a href="https://developer.android.com/reference/android/os/Build.html#getRadioVersion()">getRadioVersion()</a></td> 233 <td> MUST (be or return) a value chosen by the device implementer 234 identifying the specific internal radio/modem version used in the device, 235 in human-readable format. If a device does not have any internal 236 radio/modem it MUST return NULL. The value of this field MUST be 237 encodable as 7-bit ASCII and match the regular expression 238 “^[a-zA-Z0-9._-,]+$”.</td> 239 </tr> 240</table> 241 242### 3.2.3\. Intent Compatibility 243 244#### 3.2.3.1\. Core Application Intents 245 246Android intents allow application components to request functionality from 247other Android components. The Android upstream project includes a list of 248applications considered core Android applications, which implements several 249intent patterns to perform common actions. 250 251* [C-0-1] Device implementations MUST preload one or more applications or 252service components with an intent handler, for all the public intent filter 253patterns defined by the following core android applications in AOSP: 254 255 * Desk Clock 256 * Browser 257 * Calendar 258 * Contacts 259 * Gallery 260 * GlobalSearch 261 * Launcher 262 * Music 263 * Settings 264 265#### 3.2.3.2\. Intent Resolution 266 267* [C-0-1] As Android is an extensible platform, device implementations MUST 268allow each intent pattern referenced in [section 3.2.3.1](#3_2_3_1_core_application_intents) 269to be overridden by third-party applications. The upstream Android open source 270implementation allows this by default. 271* [C-0-2] Dvice implementers MUST NOT attach special privileges to system 272applications' use of these intent patterns, or prevent third-party applications 273from binding to and assuming control of these patterns. This prohibition 274specifically includes but is not limited to disabling the “Chooser” user 275interface that allows the user to select between multiple applications that all 276handle the same intent pattern. 277 278* [C-0-3] Device implementations MUST provide a user interface for users to 279modify the default activity for intents. 280 281* However, device implementations MAY provide default activities for specific 282URI patterns (e.g. http://play.google.com) when the default activity provides a 283more specific attribute for the data URI. For example, an intent filter pattern 284specifying the data URI “http://www.android.com” is more specific than the 285browser's core intent pattern for “http://”. 286 287Android also includes a mechanism for third-party apps to declare an 288authoritative default [app linking behavior](https://developer.android.com/training/app-links) 289for certain types of web URI intents. When such authoritative declarations are 290defined in an app's intent filter patterns, device implementations: 291 292* [C-0-4] MUST attempt to validate any intent filters by performing the 293validation steps defined in the [Digital Asset Links specification](https://developers.google.com/digital-asset-links) 294as implemented by the Package Manager in the upstream Android Open Source 295Project. 296* [C-0-5] MUST attempt validation of the intent filters during the installation of 297the application and set all successfully validated URI intent filters as 298default app handlers for their URIs. 299* MAY set specific URI intent filters as default app handlers for their URIs, 300if they are successfully verified but other candidate URI filters fail 301verification. If a device implementation does this, it MUST provide the 302user appropriate per-URI pattern overrides in the settings menu. 303* MUST provide the user with per-app App Links controls in Settings as 304follows: 305 * [C-0-6] The user MUST be able to override holistically the default app 306 links behavior for an app to be: always open, always ask, or never open, 307 which must apply to all candidate URI intent filters equally. 308 * [C-0-7] The user MUST be able to see a list of the candidate URI intent 309 filters. 310 * The device implementation MAY provide the user with the ability to 311 override specific candidate URI intent filters that were successfully 312 verified, on a per-intent filter basis. 313 * [C-0-8] The device implementation MUST provide users with the ability to 314 view and override specific candidate URI intent filters if the device 315 implementation lets some candidate URI intent filters succeed 316 verification while some others can fail. 317 318#### 3.2.3.3\. Intent Namespaces 319 320* [C-0-1] Device implementations MUST NOT include any Android component that 321honors any new intent or broadcast intent patterns using an ACTION, CATEGORY, or 322other key string in the android.* or com.android.* namespace. 323* [C-0-2] Device implementers MUST NOT include any Android components that 324honor any new intent or broadcast intent patterns using an ACTION, CATEGORY, or 325other key string in a package space belonging to another organization. 326* [C-0-3] Device implementers MUST NOT alter or extend any of the intent 327patterns used by the core apps listed in [section 3.2.3.1](#3_2_3_1_core_application_intents). 328* Device implementations MAY include intent patterns using namespaces clearly 329and obviously associated with their own organization. This prohibition is 330analogous to that specified for Java language classes in [section 3.6](#3_6_api_namespaces). 331 332#### 3.2.3.4\. Broadcast Intents 333 334Third-party applications rely on the platform to broadcast certain intents to 335notify them of changes in the hardware or software environment. 336 337Device implementations: 338 339* [C-0-1] MUST broadcast the public broadcast intents in response to 340 appropriate system events as described in the SDK documentation. Note that 341 this requirement is not conflicting with section 3.5 as the limitation for 342 background applications are also described in the SDK documentation. 343 344#### 3.2.3.5\. Default App Settings 345 346Android includes settings that provide users an easy way to select their 347default applications, for example for Home screen or SMS. 348 349Where it makes sense, device implementations MUST provide a similar settings 350menu and be compatible with the intent filter pattern and API methods described 351in the SDK documentation as below. 352 353If device implementations report `android.software.home_screen`, they: 354 355* [C-1-1] MUST honor the [`android.settings.HOME_SETTINGS`]( 356http://developer.android.com/reference/android/provider/Settings.html#ACTION_HOME_SETTINGS) 357intent to show a default app settings menu for Home Screen. 358 359If device implementations report `android.hardware.telephony`, they: 360 361* [C-2-1] MUST provide a settings menu that will call the 362[`android.provider.Telephony.ACTION_CHANGE_DEFAULT`]( 363http://developer.android.com/reference/android/provider/Telephony.Sms.Intents.html) 364intent to show a dialog to change the default SMS application. 365 366* [C-2-2] MUST honor the [`android.telecom.action.CHANGE_DEFAULT_DIALER`]( 367https://developer.android.com/reference/android/telecom/TelecomManager.html#ACTION_CHANGE_DEFAULT_DIALER) 368intent to show a dialog to allow the user to change the default Phone 369application. 370 371* [C-2-3] MUST honor the [android.telecom.action.CHANGE_PHONE_ACCOUNTS]( 372https://developer.android.com/reference/android/telecom/TelecomManager.html#ACTION_CHANGE_PHONE_ACCOUNTS) 373intent to provide user affordance to configure the [`ConnectionServices`]( 374https://developer.android.com/reference/android/telecom/ConnectionService.html) 375associated with the [`PhoneAccounts`]( 376https://developer.android.com/reference/android/telecom/PhoneAccount.html), as 377well as a default PhoneAccount that the telecommunications service provider will 378use to place outgoing calls. The AOSP implementation meets this requirement by 379including a "Calling Accounts option" menu within the "Calls" settings menu. 380 381If device implementations report `android.hardware.nfc.hce`, they: 382 383* [C-3-1] MUST honor the [android.settings.NFC_PAYMENT_SETTINGS]( 384http://developer.android.com/reference/android/provider/Settings.html#ACTION_NFC_PAYMENT_SETTINGS) 385intent to show a default app settings menu for Tap and Pay. 386 387If device implementations support the `VoiceInteractionService` and have more 388than one application using this API installed at a time, they: 389 390* [C-4-1] MUST honor the [`android.settings.ACTION_VOICE_INPUT_SETTINGS`]( 391 https://developer.android.com/reference/android/provider/Settings.html#ACTION_VOICE_INPUT_SETTINGS) 392 intent to show a default app settings menu for voice input and assist. 393 394### 3.2.4\. Activities on secondary displays 395 396If device implementations allow launching normal [Android Activities]( 397https://developer.android.com/reference/android/app/Activity.html) on secondary 398displays, they: 399 400* [C-1-1] MUST set the `android.software.activities_on_secondary_displays` 401 feature flag. 402* [C-1-2] MUST guarantee API compatibility similar to an activity running on 403 the primary display. 404* [C-1-3] MUST land the new activity on the same display as the activity that 405 launched it, when the new activity is launched without specifying a target 406 display via the [`ActivityOptions.setLaunchDisplayId()`]( 407 https://developer.android.com/reference/android/app/ActivityOptions.html#setLaunchDisplayId%28int%29) 408 API. 409* [C-1-4] MUST destory all activities, when a display with the 410 [`Display.FLAG_PRIVATE`](http://developer.android.com/reference/android/view/Display.html#FLAG_PRIVATE) 411 flag is removed. 412* [C-1-5] MUST resize accordingly all activities on a [`VirtualDisplay`]( 413 https://developer.android.com/reference/android/hardware/display/VirtualDisplay.html) 414 if the display itself is resized. 415* MAY show an IME (input method editor, a user control that enables users to 416 enter text) on the primary display, when a text input field becomes focused 417 on a secondary display. 418* SHOULD implement the input focus on the secondary display independently of 419 the primary display, when touch or key inputs are supported. 420* SHOULD have [`android.content.res.Configuration`]( 421 https://developer.android.com/reference/android/content/res/Configuration.html) 422 which corresponds to that display in order to be displayed, operate 423 correctly, and maintain compatibility if an activity is launched on 424 secondary display. 425 426If device implementations allow launching normal [Android Activities]( 427https://developer.android.com/reference/android/app/Activity.html) on secondary 428displays and primary and secondary displays have different 429[android.util.DisplayMetrics](https://developer.android.com/reference/android/util/DisplayMetrics.html): 430 431* [C-2-1] Non-resizeable activities (that have `resizeableActivity=false` in 432 `AndroidManifest.xml`) and apps targeting API level 23 or lower MUST NOT be 433 allowed on secondary displays. 434 435If device implementations allow launching normal [Android Activities]( 436https://developer.android.com/reference/android/app/Activity.html) on secondary 437displays and a secondary display has the [android.view.Display.FLAG_PRIVATE]( 438https://developer.android.com/reference/android/view/Display.html#FLAG_PRIVATE) 439flag: 440 441* [C-3-1] Only the owner of that display, system, and activities that are 442 already on that display MUST be able to launch to it. Everyone can launch to 443 a display that has [android.view.Display.FLAG_PUBLIC](https://developer.android.com/reference/android/view/Display.html#FLAG_PUBLIC) 444 flag. 445