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 &ldquo;^[a-zA-Z0-9_-]+$&rdquo;.</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 &ldquo;^[a-zA-Z0-9_-]+$&rdquo;.</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    &ldquo;^[a-zA-Z0-9_-]+$&rdquo;. 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        &nbsp;&nbsp;&nbsp;&nbsp;$(DEVICE):$(VERSION.RELEASE)/$(ID)/$(VERSION.INCREMENTAL):$(TYPE)/$(TAGS)</p>
120    <p>For example:</p>
121<p class="small">acme/myproduct/<br>
122      &nbsp;&nbsp;&nbsp;&nbsp;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    &ldquo;^[a-zA-Z0-9_-]+$&rdquo;.</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 &ldquo;^[a-zA-Z0-9._-]+$&rdquo;.</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 &ldquo;^[a-zA-Z0-9_-]+$&rdquo;. 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    &ldquo;^([a-zA-Z0-9]{6,20})$&rdquo;.</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 &ldquo;^[a-zA-Z0-9._-]+$&rdquo;.</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    &ldquo;^[a-zA-Z0-9._-,]+$&rdquo;.</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