fuquan/allwinner_a64
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

upload android base code part8

Browse source
This commit is contained in:
August 2018-08-08 20:10:12 +08:00
parent 841ae54672
commit 5425409085
57075 changed files with 9846578 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

125
android/docs/source.android.com/en/devices/tech/admin/enterprise-telephony.html Normal file
View file

@ -0,0 +1,125 @@
<html devsite>
<head>
<title>Implementing Enterprise Telephony</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>
This document outlines the changes made to the telephony-related parts of the
Android framework in the 7.0 release to support enterprise use cases. This
document is targeted at manufacturers and focuses entirely on framework-related
telephony changes. In addition, this document outlines the changes that OEMs
will need to make to their preloaded applications that handle telephony-related
functions.
</p>
<p>
Android 7.0 introduces several new features to support enterprise telephony use
cases, in particular:
</p>
<ul>
<li>Cross profile contact search - Allows applications in the personal profile
to search for contacts that are supplied by the managed profile contacts
provider, which can be backed by any datastore, for example local to the device
or perhaps within an enterprise directory
<li>Cross profile contact badging - Allows work contacts to be clearly
distinguished from personal contacts
<li>Making Connection Service managed profile aware - Allows applications within
the Managed Profile to offer telephony features, such as to provide a separate
work dialer and work ConnectionService</li>
</ul>
<h2 id="examples-and-source">Examples and source</h2>
<p>
The Android Open Source Project (AOSP) implementations of Dialer, Contacts, and
Messaging apps have integrated the cross profile contact search and badging
capability.
</p>
<p>
Examples:
</p><ul>
<li><strong>Adding badge to work contacts</strong>: see
<code>packages/apps/ContactsCommon</code> <em>f3eb5a207bfe0ff3b4ed2350ae5865ed8bc59798</em>
<li><strong>Cross profile search</strong>: see <code>packages/apps/ContactsCommon</code> <em>cd0b29ddbf3648e48f048196c62245d545bc6122</em></li>
</ul>
<h2 id="implementation">Implementation</h2>
<p>
Device implementers must implement cross-profile, search, lookup and badging
for contacts in their Dialer Contacts and SMS/MMS Messaging apps.</p>
<h3 id="cross-profile-contact-search">Cross-profile contact search</h3>
<p>
Cross profile contact search should be implemented using the Enterprise Contacts
API (<code>ContactsContract.Contacts.ENTERPRISE_CONTENT_FILTER_URI</code> etc.)
see <a
href="http://developer.android.com/preview/features/afw.html#contacts">http://developer.android.com/preview/features/afw.html#contacts</a>
</p>
<h3 id="work-profile-contact-badging">Work profile contact badging</h3>
<p>
Work profile contact badging can be implemented by checking
<code>ContactsContract.Directory.isEntepriseDirectoryId() </code>if available or
<a
href="http://developer.android.com/reference/android/provider/ContactsContract.Contacts.html#isEnterpriseContactId(long)">http://developer.android.com/reference/android/provider/ContactsContract.Contacts.html#isEnterpriseContactId(long)</a>
<code> </code>
</p>
<h3 id="managed-profile-aware-connectionservice">Managed Profile Aware
ConnectionService</h3>
<p>
Manufacturers should not need to modify the framework code to support this
functionality, but should be aware of it’s impact on the Telecomm service and
other telephony features.
</p>
<h2 id="validation">Validation</h2>
<p>
The cross profile contact search and badging feature can be validated by:
</p>
<ol>
<li>Setting up a managed profile on a test device using <a
href="https://github.com/googlesamples/android-testdpc">TestDPC</a>.
<li>Enabling cross profile contact search.
<li>Adding a local work contact within the managed profile.
<li>Searching for that contact within the system Dialer Contacts and SMS/MMS
Messaging Apps within the personal profile, checking that this contact is found
and it is correctly badged.</li>
</ol>
<p>
CTS tests have been added to ensure the underlying cross profile contact search
API has been implemented in
<code>com/android/cts/managedprofile/ContactsTest.java</code>.
</p>
</body>
</html>

BIN
android/docs/source.android.com/en/devices/tech/admin/images/multi-user-perms.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 27 KiB

201
android/docs/source.android.com/en/devices/tech/admin/implement.html Normal file
View file

@ -0,0 +1,201 @@
<html devsite>
<head>
<title>Implementing Device Administration</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>This section describes how to enable and validate device administration
features required to prepare devices for managed profiles. It also covers device
owner user cases that are essential in a corporate environment.</p>
<p>In addition to AOSP code, a device requires the following components to function with managed
profiles.</p>
<h2 id=requirements>General requirements</h2>
<p>Devices intending to support device administration must meet the following
general requirements.</p>
<h3 id=HAL_values>Thermal HAL values</h3>
<p>Android 7.0 and later includes support for HardwarePropertiesManager API, a device
monitoring and health reporting API that enables applications to query the state
of device hardware. This API is exposed via
<code>android.os.HardwarePropertiesManager</code> and makes calls through
<code>HardwarePropertiesManagerService</code> to the hardware thermal HAL
(<code>hardware/libhardware/include/hardware/thermal.h</code>). It is a
protected API, meaning only device/profile owner Device Policy Controller (DPC)
applications and the current <code>VrListenerService</code> can call it.</p>
<p>To support the HardwarePropertiesManager API, the device thermal HAL
implementation must be able to report the following values:</p>
<table>
<tr>
<th width="32%">Value</th>
<th>Reporting Scale</th>
<th>Enables</th>
</tr>
<tr>
<td>Temperature of [CPU|GPU|Battery|Device Skin]</td>
<td>Temperature of component in degrees Celsius</td>
<td>Apps can check device temperatures and component throttling/shutdown
temperatures</td>
</tr>
<tr>
<td>CPU active/total enabled times</td>
<td>Time in milliseconds</td>
<td>Apps can check CPU usage per core</td>
</tr>
<tr>
<td>Fan speed</td>
<td>RPM</td>
<td>Apps can check fan speed</td>
</tr>
</table>
<p>Implementations should correctly handle reporting values situations when a
core (or GPU, battery, fan) goes offline or is plugged/unplugged.</p>
<h3 id=low_ram>No low-RAM</h3>
<p>Device should not be a low-RAM device, meaning <code>ro.config.low_ram</code>
should not be defined. The framework automatically limits the number of users
to 1 when the <code>low_ram</code> flag is defined.</p>
<h3 id=uses-feature>Uses-feature</h3>
<p>Devices must define the following <code>uses-feature</code>:</p>
<pre class="devsite-click-to-copy">
android.software.managed_users
android.software.device_admin
</pre>
<p>To confirm these <code>uses-feature</code> values have been defined on a
device, run: <code>adb shell pm list features</code>.</p>
<h3 id=required_apps>Essential apps only</h3>
<p>By default, only applications essential for correct operation of the profile
should be enabled as part of provisioning a managed device. OEMs must ensure the
managed profile or device has all required applications by modifying:</p>
<pre class="devsite-click-to-copy">
vendor_required_apps_managed_profile.xml
vendor_required_apps_managed_device.xml
</pre>
<p>Examples from a Nexus device:</p>
<pre class="devsite-click-to-copy">
packages/apps/ManagedProvisioning/res/values/vendor_required_apps_managed_device.xml
</pre>
<pre class="devsite-click-to-copy">
&lt;resources&gt;
&lt;!-- A list of apps to be retained on the managed device --&gt;
&lt;string-array name="vendor_required_apps_managed_device"&gt;
&lt;item&gt;com.android.vending&lt;/item&gt; &lt;!--­Google Play --&gt;
&lt;item&gt;com.google.android.gms&lt;/item&gt; &lt;!--­Required by Play --&gt;
&lt;item&gt;com.google.android.contacts&lt;/item&gt; &lt;!--­Google or OEM Contacts­--&gt;
&lt;item&gt;com.google.android.googlequicksearchbox&lt;/item&gt; &lt;!--­Google Launcher --&gt;
&lt;item&gt;com.google.android.launcher&lt;/item&gt; &lt;!--­Google Launcher or OEM Launcher --&gt;
&lt;item&gt;com.google.android.dialer&lt;/item&gt; &lt;!--­Google or OEM dialer to enable making phone calls --&gt;
&lt;/string-array&gt;
&lt;/resources&gt;
</pre>
<pre class="devsite-click-to-copy">
packages/apps/ManagedProvisioning/res/values/vendor_required_apps_managed_profile.xml
</pre>
<pre class="devsite-click-to-copy">
&lt;resources&gt;
&lt;!-- A list of apps to be retained in the managed profile. This includes any Google experience apps required. --&gt;
&lt;string-array name="vendor_required_apps_managed_profile"&gt;
&lt;item&gt;com.android.vending&lt;/item&gt; &lt;!-- Google Play --&gt;
&lt;item&gt;com.google.android.gms&lt;/item&gt; &lt;!-- Required by Play --&gt;
&lt;item&gt;com.google.android.contacts&lt;/item&gt; &lt;!-- Google or OEM Contacts --&gt;
&lt;/string-array&gt;
&lt;/resources&gt;
</pre>
<h2 id=launcher>Launcher requirements</h2>
<p>You must update the Launcher to support badging applications with the icon
badge (provided in AOSP to represent the managed applications) and other badge
user interface elements such as recents and notifications. If you use
<a href="https://android.googlesource.com/platform/packages/apps/Launcher3/">launcher3</a>
in AOSP without modifications, then you likely already support this badging
feature.</p>
<h2 id=nfc>NFC requirements</h2>
<p>Devices with NFC must enable NFC during the out-of-the-box experience (i.e.,
setup wizard) and be configured to accept managed provisioning intents:</p>
<pre class="devsite-click-to-copy">
packages/apps/Nfc/res/values/provisioning.xml
</pre>
<pre class="devsite-click-to-copy">
&lt;bool name="enable_nfc_provisioning"&gt;true&lt;/bool&gt;
&lt;item>application/com.android.managedprovisioning&lt;/item&gt;
</pre>
<h2 id=setup_wizard>Setup requirements</h2>
<p>Devices that include an out-of-box experience (i.e., setup wizard)
should implement device owner provisioning. When the out-of-box experience
opens, it should check if another process (such as device owner provisioning)
has already finished the user setup and, if so, it should fire a home intent
and finish the setup. This intent is caught by the provisioning application,
which then hands control to the newly-set device owner.</p>
<p>To meet setup requirements, add the following code to the device setup's main
activity:</p>
<pre class="devsite-click-to-copy">
&#64;Override
protected void onStart() {
super.onStart();
// When returning to a setup wizard activity, check to see if another setup process
// has intervened and, if so, complete an orderly exit
boolean completed = Settings.Secure.getInt(getContentResolver(),
Settings.Secure.USER_SETUP_COMPLETE, 0) != 0;
if (completed) {
startActivity(new Intent(Intent.ACTION_MAIN, null)
.addCategory(Intent.CATEGORY_HOME)
.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK
| Intent.FLAG_ACTIVITY_CLEAR_TASK
| Intent.FLAG_ACTIVITY_RESET_TASK_IF_NEEDED));
finish();
}
...
}
</pre>
</body>
</html>

64
android/docs/source.android.com/en/devices/tech/admin/index.html Normal file
View file

@ -0,0 +1,64 @@
<html devsite>
<head>
<title>Device Administration</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>Devices running Android 5.0 and later with the managed_users feature
declared can be used in a <a href="http://www.android.com/work/">corporate
environment</a> under the auspices of each company’s information technology (IT)
department. This is possible with the introduction of <a href="multi-user.html">multiple
users</a>, <a href="managed-profiles.html">managed profiles</a>, and enterprise
mobility management (EMM) applications, as well as enhancements to default
<a
href="/security/encryption/index.html">encryption</a>,
<a
href="/security/verifiedboot/index.html">verified
boot</a>, and <a
href="/security/selinux/index.html">SELinux</a>.</p>
<p>With these enhancements, either users or their IT departments may create
managed profiles that separate corporate employer data from personal user
information. Follow the documents within this section of the site to properly
implement corporate device administration.</p>
<h2 id=summary>Summary</h2>
<p>Follow this flow to employ device administration:</p>
<ol>
<li>Gain an understanding of key concepts, such as <a
href="multi-user.html">multiple users</a> and <a
href="managed-profiles.html">managed profiles</a>.
<li><a href="implement.html">Implement device administration</a> via custom
overlay files.
<li><a href="testing-setup.html">Test</a> and validate your devices with EMM providers and applications.
</ol>
<h2 id=supporting_documentation>Supporting documentation</h2>
<p><a href="http://developer.android.com/guide/topics/admin/device-admin.html">Device Administration API</a></p>
<p><a href="https://developer.android.com/training/enterprise/index.html">Building Apps for Work</a></p>
</body>
</html>

183
android/docs/source.android.com/en/devices/tech/admin/managed-profiles.html Normal file
View file

@ -0,0 +1,183 @@
<html devsite>
<head>
<title>Employing Managed Profiles</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>A <em>managed profile</em> or <em>work profile</em> is an Android <a
href="multi-user.html">user</a> with additional special properties around
management and visual aesthetic.</p>
<p>The primary goal of a managed profile is to create a segregated and secure
space for managed data (such as corporate data) to reside. The administrator of
the profile has full control over scope, ingress, and egress of data as well as
its lifetime. These policies offer great powers and therefore fall upon the
managed profile instead of the device administrator.</p>
<ul>
<li><strong>Creation</strong>. Managed profiles can be created by any
application in the primary user. The user is notified of managed profile
behaviors and policy enforcement before creation.</li>
<li><strong>Management</strong>. Management is performed by applications that
programmatically invoke APIs in the
<a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html">DevicePolicyManager</a>
class to restrict use. Such applications are referred to as <em>profile
owners</em> and are defined at initial profile setup. Policies unique to
managed profile involve app restrictions, updatability, and intent behaviors.
</li>
<li><strong>Visual treatment</strong>. Applications, notifications, and
widgets from the managed profile are always badged and typically made
available inline with user interface (UI) elements from the primary user.</li>
</ul>
<h2 id=data_segregation>Data segregation</h2>
<p>Managed profiles use the following data segregation rules.</p>
<h3 id=applications>Applications</h3>
<p>Applications are scoped with their own segregated data when the same app
exists in the primary user and managed profile. Generally, applications act
independently of one another and cannot communicate directly with one another
across the profile-user boundary.</p>
<h3 id=accounts>Accounts</h3>
<p>Accounts in the managed profile are distinctly unique from the primary user.
There is no way to access credentials across the profile-user boundary. Only
apps in their respective context are able to access their respective accounts.</p>
<h3 id=intents>Intents</h3>
<p>The administrator controls whether intents are resolved in/out of managed
profile or not. Applications from the managed profile are default scoped to
stay within the managed profile exception of the Device Policy API.</p>
<h3 id=settings>Settings</h3>
<p>Enforcement of settings is generally scoped to the managed profile, with
exceptions for lockscreen and encryption settings that are still scoped
to the device and shared between the primary user and managed profile.
Otherwise, a profile owner does not have any device administrator privileges
outside the managed profile.</p>
<p>Managed profiles are implemented as a new kind of secondary user, such that:</p>
<pre class="devsite-click-to-copy">
uid = 100000 * userid + appid
</pre>
<p>They have separate app data like regular users:</p>
<pre class="devsite-click-to-copy">
/data/user/&lt;userid&gt;
</pre>
<p>The UserId is calculated for all system requests using
<code>Binder.getCallingUid()</code>, and all system state and responses are
separated by userId. You may consider instead using
<code>Binder.getCallingUserHandle</code> rather than <code>getCallingUid</code>
to avoid confusion between uid and userId.</p>
<p>The AccountManagerService maintains a separate list of accounts for each
user. The main differences between a managed profile and a regular secondary
user are as follows:</p>
<ul>
<li>The managed profile is associated with its parent user and started
alongside the primary user at boot time.</li>
<li>Notifications for managed profiles are enabled by ActivityManagerService
allowing the managed profile to share the activity stack with the primary
user.</li>
<li>Other shared system services include IME, A11Y services, Wi-Fi, and NFC.
</li>
<li>New Launcher APIs allow launchers to display badged apps and whitelisted
widgets from the managed profile alongside apps in the primary profile without
switching users.</li>
</ul>
<h2 id=device_administration>Device administration</h2>
<p>Android device administration includes the following types of device
administrators for enterprises:</p>
<ul>
<li><em>Profile owner</em>. Designed for bring your own device (BYOD)
environments</li>
<li><em>Device Owner</em>. Designed for corp-liable environments</li>
</ul>
<p>The majority of the new device administrator APIs added for Android 5.0 are
available only to profile or device owners. Traditional device administrators
remain but are applicable to the simpler consumer-only case (e.g., find my
device).</p>
<h3 id=profile_owners>Profile owners</h3>
<p>A Device Policy Client (DPC) app typically functions as the profile owner.
The DPC app is typically provided by an enterprise mobility management (EMM)
partner, such as Google Apps Device Policy.</p>
<p>The profile owner app creates a managed profile on the device by sending the
<code>ACTION_PROVISION_MANAGED_PROFILE</code> intent. This profile is
distinguished by the appearance of badged instances of
apps, as well as personal instances. That badge, or Android device
administration icon, identifies which apps are work apps.</p>
<p>The EMM has control only over the managed profile (not personal space) with
some exceptions, such as enforcing the lock screen.</p>
<h3 id=device_owners>Device owners</h3>
<p>The device owner can be set only in an unprovisioned device:</p>
<ul>
<li>Can be provisioned only at initial device setup</li>
<li>Enforced disclosure always displayed in quick-settings</li>
</ul>
<p>Device owners can conduct some tasks profile owners cannot, such as:</p>
<ul>
<li>Wipe device data</li>
<li>Disable Wi-Fi/Bluetooth</li>
<li>Control <code>setGlobalSetting</code></li>
<li><code>setLockTaskPackages</code> (the ability to whitelist packages that
can pin themselves to the foreground)</li>
<li>Set <code>DISALLOW_MOUNT_PHYSICAL_MEDIA</code> (<code>FALSE</code> by
default). When <code>TRUE</code>, physical media, both portable and adoptable,
cannot be mounted.</li>
</ul>
<h3 id=dpm_api>DevicePolicyManager APIs</h3>
<p>Android 5.0 and higher offers a greatly improved DevicePolicyManager with
dozens of new APIs to support both corporate-owned and bring your own device
(BYOD) administration use cases. Examples include app restrictions, silent
installation of certificates, and cross-profile sharing intent access control.
Use the sample Device Policy Client (DPC) app
<a href="https://developer.android.com/samples/BasicManagedProfile/index.html">BasicManagedProfile.apk</a>
as a starting point. For details, refer to
<a href="https://developer.android.com/training/enterprise/work-policy-ctrl.html">Building
a Work Policy Controller</a>.</p>
</body>
</html>

195
android/docs/source.android.com/en/devices/tech/admin/multi-user.html Normal file
View file

@ -0,0 +1,195 @@
<html devsite>
<head>
<title>Supporting Multiple Users</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>Android supports multiple users on a single Android device by separating user
accounts and application data. For instance, parents may allow their children to
use the family tablet, or a critical response team might share a mobile device
for on-call duty.</p>
<h2 id=definitions>Terminology</h2>
<p>Android uses the following terms when describing Android users and accounts.</p>
<h3 id=general_defs>General</h3>
<p>Android device administration uses the following general terms.</p>
<ul>
<li><em>User</em>. Each user is intended to be used by a different physical
person. Each user has distinct application data and some unique settings, as
well as a user interface to explicitly switch between users. A user can run in
the background when another user is active; the system manages shutting down
users to conserve resources when appropriate. Secondary users can be created
either directly via the primary user interface or from a
<a href="https://developer.android.com/guide/topics/admin/device-admin.html">Device
Administration</a> application.</li>
<li><em>Account</em>. Accounts are contained within a user but are not defined
by a user, nor is a user defined by or linked to any given account. Users and
profiles contain their own unique accounts but are not required to have
accounts to be functional. The list of accounts differs by user. For details,
refer to the
<a href="https://developer.android.com/reference/android/accounts/Account.html">Account
class</a> definition.</li>
<li><em>Profile</em>. A profile has separated app data but shares some
system-wide settings (for example, Wi-Fi and Bluetooth). A profile is a subset
of and tied to the existence of a user. A user can have multiple profiles.
They are created through a
<a href="https://developer.android.com/guide/topics/admin/device-admin.html">Device
Administration</a> application. A profile always has an immutable association
to a parent user, defined by the user that created the profile. Profiles do not live beyond the lifetime of the creating user.</li>
<li><em>App</em>. An application’s data exists within each associated user.
App data is sandboxed from other applications within the same user. Apps
within the same user can interact with each other via IPC. For details, refer
to <a href="https://developer.android.com/training/enterprise/index.html">Building
Apps for Work</a>.</li>
</ul>
<h3 id=user_types>User types</h3>
<p>Android device administration uses the following user types.</p>
<ul>
<li><em>Primary</em>. First user added to a device. The primary user
cannot be removed except by factory reset and is always running even when
other users are in the foreground. This user also has special privileges and
settings only it can set.</li>
<li><em>Secondary</em>. Any user added to the device other than the primary
user. Secondary users can be removed (either by themselves or by the primary
user) and cannot impact other users on a device. These users can run in the
background and continue to have network connectivity.</li>
<li><em>Guest</em>. Temporary secondary user. Guest users have an explicit
option to quick delete the guest user when its usefulness is over. There can
be only one guest user at a time.</li>
</ul>
<h3 id=profile_types>Profile types</h3>
<p>Android device administration uses the following profile types.</p>
<ul>
<li><em>Managed</em>. Created by an application to contain work data
and apps. They are managed exclusively by the profile owner (the app that
created the corp profile). Launcher, notifications, and recent tasks are
shared by the primary user and the corp profile.</li>
<li><em>Restricted</em>. Uses accounts based off the primary user, who can
control what apps are available on the restricted profile. Available only on
tablets and television devices.</li>
</ul>
<h2 id=applying_the_overlay>Enabling multi-user</h2>
<p>As of Android 5.0, the multi-user feature is disabled by default. To
enable it, device manufacturers must define a resource overlay that replaces
the following values in <code>frameworks/base/core/res/res/values/config.xml</code>:
</p>
<pre class="devsite-click-to-copy">
&lt;!-- Maximum number of supported users --&gt;
&lt;integer name="config_multiuserMaximumUsers"&gt;1&lt;/integer&gt;
&lt;!-- Whether Multiuser UI should be shown --&gt;
&lt;bool name="config_enableMultiUserUI"&gt;false&lt;/bool&gt;
</pre>
<p>To apply this overlay and enable guest and secondary users on the device, use
the <code>DEVICE_PACKAGE_OVERLAYS</code> feature of the Android build system to:</p>
<ul>
<li>Replace the value for <code>config_multiuserMaximumUsers</code> with one
greater than 1</li>
<li>Replace the value of <code>config_enableMultiUserUI</code> with:
<code>true</code></li>
</ul>
<p>Device manufacturers may decide upon the maximum number of users. If device
manufacturers or others have modified settings, they must ensure SMS and
telephony work as defined in the
<a href="/compatibility/android-cdd.pdf">Android Compatibility
Definition Document</a> (CDD).</p>
<h2 id=managing_users>Managing multiple users</h2>
<p>Management of users and profiles (with the exception of restricted profiles)
is performed by applications that programmatically invoke API in the
<code>DevicePolicyManager</code> class to restrict use.</p>
<p>Schools and enterprises may employ users and profiles to manage the lifetime
and scope of apps and data on devices, using the types outlined above in
conjunction with the
<a href="http://developer.android.com/reference/android/os/UserManager.html">UserManager
API</a> to build unique solutions tailored to their use cases.</p>
<h2 id=effects>Multi-user system behavior</h2>
<p>When users are added to a device, some functionality is curtailed when
another user is in the foreground. Since app data is separated by user, the
state of those apps differs by user. For example, email destined for an account
of a user not currently in focus won’t be available until that user and account
are active on the device.</p>
<p>By default, only the primary user has full access to phone calls and texts.
The secondary user may receive inbound calls but cannot send or receive texts.
The primary user must enable these functions for others.</p>
<p class="note"><strong>Note</strong>: To enable or disable the phone and SMS
functions for a secondary user, go to <em>Settings > Users</em>, select the
user, and switch the <em>Allow phone calls and SMS</em> setting to off.</p>
<p>Some restrictions exist when a secondary user is in background. For instance,
the background secondary user cannot display the user interface or make
Bluetooth services active. In addition, the system process will halt background
secondary users if the device needs additional memory for operations in the
foreground user.</p>
<p>When employing multiple users on an Android device, keep the following
behavior in mind:</p>
<ul>
<li>Notifications appear for all accounts of a single user at once.</li>
<li>Notifications for other users do not appear until active.</li>
<li>Each user gets a workspace to install and place apps.</li>
<li>No user has access to the app data of another user.</li>
<li>Any user can affect the installed apps for all users.</li>
<li>The primary user can remove apps or even the entire workspace established
by secondary users.</li>
</ul>
<p>Android 7.0 includes several enhancements, including:</p>
<ul>
<li><em>Toggle work profile</em>. Users can disable their managed profile
(such as when not at work). This functionality is achieved by stopping the
user; UserManagerService calls <code>ActivityManagerNative#stopUser()</code>.
</li>
<li><em>Always-on VPN</em>. VPN applications can now be set to always-on by
the user, Device DPC, or Managed Profile DPC (applies only to Managed Profile
applications). When enabled, applications cannot access the public network
(access to network resources is stopped until the VPN has connected and
connections can be routed over it). Devices that report
<code>device_admin</code> must implement always-on VPN.</li>
</ul>
<p>For more details on Android 7.0 device administration features, refer to
<a href="https://developer.android.com/about/versions/nougat/android-7.0.html#android_for_work">Android
for Work</a>.</p>
</body>
</html>

129
android/docs/source.android.com/en/devices/tech/admin/multiuser-apps.html Normal file
View file

@ -0,0 +1,129 @@
<html devsite>
<head>
<title>Building Multiuser-Aware Apps</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>When a device supports <a href="multi-user.html">multiple users</a>, its apps must be made aware of these distinct users.</p>
<p>Certain apps need to have some components run as singletons and can accept
requests from any user. Only system apps can currently use this feature.</p>
<p>This facility:</p>
<ul>
<li>Conserves resources
<li>Arbitrates one or more shared resources across users
<li>Reduces network overhead by using a single server connection
</ul>
<p>See the diagram below for a depiction of permissions flow with multiple users.</p>
<p><img src="/devices/tech/admin/images/multi-user-perms.png" alt="Multiple users permissions flow" />
<p class="img-caption"><strong>Figure 1.</strong> Multiple users permissions</p>
<h2 id=enabling_a_singleton_component>Enabling a singleton component</h2>
<p>To identify an app as a singleton, Add <code>android:singleUser=”true”</code> to your service or provider in the Android manifest.</p>
<p>The system will instantiate that component in the process running as user 0
only. Any requests to connect to that provider or service from any user will be
routed to the process in user 0. If this is the only component in your app,
only one instance of your app will run.</p>
<p>Activities in your package will still be launched in a separate process for
each user, with the UID being in the UID range for that user (such as 1010034).</p>
<h2 id=interacting_with_users>Interacting with users</h2>
<h3 id=perms_required>Set permissions</h3>
<p>These permissions are required</p>
<pre class="devsite-click-to-copy">
INTERACT_ACROSS_USERS (signature|system)
INTERACT_ACROSS_USERS_FULL (signature)
</pre>
<h3 id=apis>Employ APIs</h3>
<p>Use the following APIs to make apps aware of multiple users.</p>
<ol>
<li> Extract the user handle from incoming Binder calls:
<ul>
<li> <code>int userHandle = UserHandle.getCallingUserId()</code>
</ul>
<li> Use new, protected APIs to start services, activities, broadcasts on a specific
user:
<ul>
<li><code>Context.startActivityAsUser(Intent, UserHandle)</code>
<li><code>Context.bindServiceAsUser(Intent, …, UserHandle)</code>
<li><code>Context.sendBroadcastAsUser(Intent, … , UserHandle)</code>
<li><code>Context.startServiceAsUser(Intent, …, UserHandle)
UserHandle</code> can be an explicit user or one of the special handles: <code>UserHandle.CURRENT</code> or <code>UserHandle.ALL</code>. <code>CURRENT</code> indicates the user that is currently in the foreground. You can use <code>ALL</code> when you want to send a broadcast to all users.
</ul>
<li>Communicate with components in your own app:
<code>(INTERACT_ACROSS_USERS)</code>
Or with components in other apps:
<code>(INTERACT_ACROSS_USERS_FULL)</code>
<li>You may need to create proxy components that run in the user’s process that
then access the <code>singleUser</code> component in user 0.
<li>Query users and their handles with the new <code>UserManager</code> system service:
<ul>
<li><code>UserManager.getUsers()</code>
<li><code>UserManager.getUserInfo()</code>
<li><code>UserManager.supportsMultipleUsers()</code>
<li><code>UserManager.getUserSerialNumber(int userHandle)</code> - a non-recycled number that corresponds to a user handle.
<li><code>UserManager.getUserHandle(int serialNumber)</code>
<li><code>UserManager.getUserProfiles() </code>- returns the collection of self and managed profiles, if any.
</ul>
<li>Register to listen to specific or all users and the callbacks with new APIs on
ContentObserver, PackageMonitor, BroadcastReceiver that provide additional
information about which user has caused the callback.
</ol>
<h3 id="work-profiles">Services in multiple users or profiles</h3>
<p>Not all services need to run an instance in another user or work profile. If your system service
only needs to run as user 0, disable the service's components when running under other users to
help preserve resources. The following example shows how you might do this at your service's entry
points:</p>
<pre class="devsite-click-to-copy">
// Add on all entry points such as boot_completed or other manifest-listed receivers and providers
if (!UserManager.isSystemUser()) {
// Disable the service
ComponentName targetServiceName = new ComponentName(this, TargetService.class);
context.getPackageManager().setComponentEnabledSetting(
targetServiceName, COMPONENT_ENABLED_STATE_DISABLED, 0);
}
</pre>
<p>The example could also use <code>PackageManager.setApplicationEnabledSetting()</code> to disable
the entire app.</p>
</body>
</html>

189
android/docs/source.android.com/en/devices/tech/admin/provision.html Normal file
View file

@ -0,0 +1,189 @@
<html devsite>
<head>
<title>Provisioning for Device Administration</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>This page describes the process for deploying devices to corporate users
using NFC or via cloud services (for a complete list of requirements, see
<a href="/devices/tech/admin/implement.html">Implementing Device
Administration</a>).</p>
<p>To get started, download the
<a href="https://github.com/googlesamples/android-NfcProvisioning">NfcProvisioning
APK</a>
and
<a href="https://github.com/googlesamples/android-DeviceOwner">Android-DeviceOwner
APK</a>.
</p>
<p class="caution"><strong>Caution:</strong> If provisioning has already
started, affected devices must be factory reset first.</p>
<h2 id=managed_provisioning>Managed provisioning</h2>
<p>Managed Provisioning is a framework UI flow to ensure users are adequately
informed of the implications of setting a device owner or managed profile. It is
designed to act as a setup wizard for managed profiles.</p>
<p class="note"><strong>Note:</strong> The device owner can be set only from an
unprovisioned device. If <code>Settings.Secure.USER_SETUP_COMPLETE</code> has
ever been set, the device is considered provisioned and the device owner cannot
be set.</p>
<p>Devices that enable default encryption offer a considerably simpler and
quicker device administration provisioning flow. The managed provisioning
component:</p>
<ul>
<li>Encrypts the device</li>
<li>Creates the managed profile</li>
<li>Disables non-required applications</li>
<li>Sets the enterprise mobility management (EMM) app as profile owner</li>
</ul>
<p>In turn, the EMM app:</p>
<ul>
<li>Adds user accounts</li>
<li>Enforces device compliance</li>
<li>Enables any additional system applications</li>
</ul>
<p>In this flow, managed provisioning triggers device encryption. The framework
copies the EMM app into the managed profile as part of managed provisioning. The
instance of the EMM app inside of the managed profile gets a callback from the
framework when provisioning is done. The EMM can then add accounts and enforce
policies; it then calls <code>setProfileEnabled()</code>, which makes the
launcher icons visible.</p>
<h2 id=profile_owner_provisioning>Profile owner provisioning</h2>
<p>Profile owner provisioning assumes the user of the device (and not a company
IT department) oversees device management. To enable profile owner provisioning,
you must send an intent with appropriate extras. For an example, use the TestDPC
application
(<a href="https://play.google.com/store/apps/details?id=com.afwsamples.testdpc&hl=en">Download
from Google Play</a> or <a href="https://github.com/googlesamples/android-testdpc/">Build
from GitHub</a>). Install TestDPC on the device, launch the app from the
launcher, then follow the app instructions. Provisioning is complete when badged
icons appear in the launcher drawer.</p>
<p>Mobile Device Management (MDM) applications trigger the creation of the
managed profile by sending an intent with action:
<a href="https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/app/admin/DevicePolicyManager.java">DevicePolicyManager.ACTION_PROVISION_MANAGED_PROFILE</a>
. Below is a sample intent that triggers the creation of the managed profile
and sets the DeviceAdminSample as the profile owner:</p>
<pre class="devsite-click-to-copy">
<code class="devsite-terminal">adb shell am start -a android.app.action.PROVISION_MANAGED_PROFILE \
-c android.intent.category.DEFAULT \
-e wifiSsid $(printf '%q' \"WifiSSID\") \
-e deviceAdminPackage "com.google.android.deviceadminsample" \
-e android.app.extra.deviceAdminPackageName $(printf '%q'
.DeviceAdminSample\$DeviceAdminSampleReceiver) \
-e android.app.extra.DEFAULT_MANAGED_PROFILE_NAME "My Organisation"</code>
</pre>
<h2 id=device_owner_provisioning_via_nfc>Device owner provisioning</h2>
<p>Use one of the following methods to set up device owner (DO)
provisioning.</p>
<h3 id=do_provision_nfc>Provisioning via NFC</h3>
<p>DO provisioning via NFC is similar to the profile owner method but requires
more bootstrapping. To use this method,
<a href="http://developer.android.com/guide/topics/connectivity/nfc/nfc.html">NFC
bump</a> the device during the initial setup step (i.e., first page of the setup
wizard). This low-touch flow configures Wi-Fi, installs the DPC, and sets the
DPC as device owner.</p>
<p>A typical NFC bundle includes the following:</p>
<pre class="devsite-click-to-copy">
EXTRA_PROVISIONING_DEVICE_ADMIN_PACKAGE_NAME
EXTRA_PROVISIONING_DEVICE_ADMIN_PACKAGE_LOCATION
EXTRA_PROVISIONING_DEVICE_ADMIN_PACKAGE_CHECKSUM
EXTRA_PROVISIONING_WIFI_SSID
EXTRA_PROVISIONING_WIFI_SECURITY_TYPE
</pre>
<p>Devices must have NFC configured to accept the managed provisioning
mimetype from the setup experience:</p>
<pre class="devsite-click-to-copy">
/packages/apps/Nfc/res/values/provisioning.xml
</pre>
<pre class="devsite-click-to-copy">
&lt;bool name="enable_nfc_provisioning"&gt;true&lt;/bool&gt;
&lt;item&gt;application/com.android.managedprovisioning&lt;/item&gt;
</pre>
<h3 id=do_provision_cs>Provisioning via Cloud Services</h3>
<p>Device owner provisioning via cloud services is another method through which
a device can be provisioned in device owner mode during out-of-the-box setup.
The device can collect credentials (or tokens) and use them to perform a lookup
to a cloud service, which can then be used to initiate the device owner
provisioning process.</p>
<h2 id=emm_benefits>EMM benefits</h2>
<p>An enterprise mobility management (EMM) app can help by conducting the
following tasks:</p>
<ul>
<li>Provision managed profile</li>
<li>Apply security policies
<ul>
<li>Set password complexity</li>
<li>Lockdowns: disable screenshots, sharing from managed profile, etc.</li>
</ul></li>
<li>Configure enterprise connectivity
<ul>
<li>Use WifiEnterpriseConfig to configure corporate Wi-Fi</li>
<li>Configure VPN on the device</li>
<li>Use <code>DPM.setApplicationRestrictions()</code> to configure corporate
VPN</li>
</ul></li>
<li>Enable corporate app Single Sign-On (SSO)
<ul>
<li>Install desired corporate apps
<li>Use <code>DPM.installKeyPair()</code> to silently install corp client
certs</li>
<li>Use <code>DPM.setApplicationRestrictions()</code> to configure
hostnames, cert alias’ of corporate apps</li>
</ul></li>
</ul>
<p>Managed provisioning is just one part of the EMM end-to-end workflow, with
the end goal of making corporate data accessible to apps in the managed
profile. For testing guidance, see
<a href="/devices/tech/admin/testing-setup.html">Setting up Device
Testing</a>.</p>
<h2 id=automate>Automated provisioning testing</h2>
<p>To automate the testing of enterprise provisioning processes, use
the Android for Work (AfW) Test Harness. For details, see
<a href="/devices/tech/admin/testing-provision.html">Testing Device
Provisioning</a>.</p>
</body>
</html>

350
android/docs/source.android.com/en/devices/tech/admin/testing-provision.html Normal file
View file

@ -0,0 +1,350 @@
<html devsite>
<head>
<title>Testing Device Provisioning</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>The Android for Work (AfW) Test Harness is a test suite for validating the
AfW compatibility of Android devices. It includes support apps, test cases,
configuration files, and a test runner (<code>afw-test-tradefed</code>) built on
<code>cts-tradefed</code>. You should setup and run the AfW Test Harness after
completing <a href="/devices/tech/admin/provision.html">Provisioning
for Device Administration</a>.</p>
<p class=note><strong>Note:</strong> Building and running the AfW Test Harness
is similar to building and running the Android
<a href="http://source.android.com/compatibility/cts/index.html">Compatibility
Test Suite (CTS)</a>.</p>
<h2 id=setup_env>Setting up a development environment</h2>
<p>The development environment for the AfW Test Harness is similar to Android
OS. Follow the steps in
<a href="/source/requirements.html">Requirements</a> to set up a
development machine.</p>
<h2 id=download_source>Downloading source code</h2>
<p>Download the AfW Test Harness source code using the steps in
<a href="/source/downloading.html">Downloading the Source</a>. The AfW
Test Harness source code is in the <code>./test/AfwTestHarness</code> project.
The branch name determines the version of AfW Test Harness to download (each
Android platform has a separate version of AfW Test Harness). For Android 7.0,
the branch name is <code>afw-test-harness-nougat-dev</code>. To initialize
the repo and download source code for this branch, use:</p>
<pre class="devsite-click-to-copy">
<code class="devsite-terminal">mkdir WORKING_DIRECTORY</code>
<code class="devsite-terminal">cd WORKING_DIRECTORY</code>
<code class="devsite-terminal">git config --global user.name "Your Name"</code>
<code class="devsite-terminal">git config --global user.email "you@example.com"</code>
<code class="devsite-terminal">repo init -u https://android.googlesource.com/platform/manifest -b afw-test-harness-nougat-dev</code>
<code class="devsite-terminal">repo sync -j24</code>
</pre>
<p>To check out the source code for a different version, specify the branch with
the corresponding tag. Available branches include:</p>
<table>
<tr>
<th>Branch Name</th>
<th>Supported Android Platform</th>
</tr>
<tr>
<td>afw-test-harness-nougat-dev</td>
<td>Android 7.0</td>
</tr>
<tr>
<td>afw-test-harness-2.1</td>
<td>Android 7.0</td>
</tr>
<tr>
<td>afw-test-harness-marshmallow-dev</td>
<td>Android 6.0</td>
</tr>
<tr>
<td>afw-test-harness-1.5</td>
<td>Android 6.0</td>
</tr>
</table>
<p>Other dependency projects required to build the harness are also downloaded
with the source code.</p>
<h3 id=view_studio>Viewing in Android Studio</h3>
<p>To view and edit AfW source code in Android Studio:</p>
<ol>
<li>Run the following commands
<pre class="devsite-click-to-copy">
<code class="devsite-terminal">make idegen</code>
<code class="devsite-terminal">development/tools/idegen/idegen.sh</code>
</pre>
</li>
<li>In Android Studio, open <code>android.ipr</code>.</li>
</ol>
<p>The AfW Test Harness source code is in <code>test/AfwTestHarness</code>.</p>
<h2 id=config_harness>Configuring the AfW Test Harness</h2>
<p>You can customize the harness by configuring
<code>test/AfwTestHarness/afw-test.props</code>. To run the harness
successfully, complete the following steps:</p>
<ol>
<li>Configure the Wi-Fi network in <code>afw-test.props</code> with the
following properties:
<pre class="devsite-click-to-copy">
wifi_ssid
wifi_password (optional)
wifi_security_type (optional, available options are: NONE, WEP or WPA)
</pre>
</li>
<li>Obtain at least one account from a domain that is bound to Test DPC as
its device policy controller. Specify the details in <code>afw-test.props</code>
with the following properties:
<pre class="devsite-click-to-copy">
work_account_username
work_account_password
</pre>
<p>The AfW Test Harness uses Test DPC to test provisioning flows, so accounts
<strong>must</strong> bind to Test DPC to run the test harness.</p>
</li>
</ol>
<h2 id=build_harness>Building the AfW Test Harness</h2>
<p>Initialize the build configuration using:</p>
<pre class="devsite-click-to-copy">
<code class="devsite-terminal">source build/envsetup.sh</code>
<code class="devsite-terminal">lunch</code>
</pre>
<p>Select a device type and press <strong>Enter</strong>.</p>
<p>Build the harness using:</p>
<pre class="devsite-terminal devsite-click-to-copy">
make afw-test-harness -j32
</pre>
<p>This creates a directory (<code>out/host/linux-x86/afw-th/android-cts</code>)
with all necessary binaries, configuration files, and tools to run the test
harness. This directory is also zipped into a file
(<code>out/host/linux-x86/afw-th/android-afw-test-harness.zip</code>)
for distribution.</p>
<h2 id=run_harness>Running the AfW Test Harness</h2>
<p>Use the following steps to run the AfW Test Harness:</p>
<ol>
<li>In your build environment, launch the test runner using:
<pre class="devsite-terminal devsite-click-to-copy">
afw-test-tradefed
</pre>
This starts the <code>cts-tf</code> console, loads test plans, test cases,
and <code>afw-test.props</code> from
<code>out/host/linux-x86/afw-th/android-cts</code>.</li>
<li>From the unzipped folder of <code>android-afw-test-harness.zip</code>,
launch the test runner using:
<pre class="devsite-click-to-copy">
cts-tf&gt; ./android‐cts/tools/afw-test‐tradefed
</pre>
This loads test plans, test cases, and <code>afw-test.props</code> from
<code>android-cts</code> directory. Ensure
<code>./android‐cts/repository/testcases/afw-test.props</code> has the work
account and Wi-Fi configuration.</li>
<li>Run a test plan. Each test plan is an XML file that contains a set of test
packages from the <code>AfwTestHarness/tests</code> test package directory.
Common plans include:
<ul>
<li><code><strong>afw-userdebug-build</strong></code>. Contains all test
packages that require a userdebug build.</li>
<li><code><strong>afw-user-build</strong></code>. Runs on a user build but
requires the test device to be set up properly, including completing the initial
setup and enabling USB debugging.</li>
</ul>
<br>To run the test plan <code>afw-userdebug-build</code>, use:
<pre class="devsite-click-to-copy">
cts-tf&gt; run cts --plan afw-userdebug-build
</pre>
To see all test plans, use the command <code>list plans</code>. To view plan
definitions, refer to
<code>out/host/linux-x86/afw-th/android-cts/repository/plans</code>.
<br>
</li>
<li>Run a test package. To run a single test package, use
<pre class="devsite-click-to-copy">
cts-tf&gt; run cts --package com.android.afwtest.NfcProvisioning
</pre>
To view all packages, use the command <code>list packages</code>. For more
options, use the command <code>run cts --help</code>.</li>
</ol>
<h2 id=debug_harness>Debugging the AfW Test Harness</h2>
<p>Run all commands in the afw-test-tradefed console (<code>cts-tf</code>),
which you can launch by running <code>afw-test-tradefed</code>.</p>
<ul>
<li>Display more information with the <code>-l INFO</code> or <code>-l
DEBUG</code> flags. Example:
<pre class="devsite-click-to-copy">
cts-tf&gt; run cts ‐‐plan afw-userdebug-build -l DEBUG
</pre>
</li>
<li>Run the test harness on a specific device with the <code>-s</code> flag.
Example:
<pre class="devsite-click-to-copy">
cts-tf&gt; run cts ‐‐plan afw-userdebug-build -l DEBUG -s device_sn
</pre>
</li>
<li>Run test harness on all connected devices with the
<code>--all-devices</code> flag. Example:
<pre class="devsite-click-to-copy">
cts-tf&gt; run cts ‐‐plan afw-userdebug-build -l DEBUG --all-devices
</pre>
</li>
<li>View current running executions using <code>list invocations</code> or
<code>l i</code>.</li>
<li>View summary of past test executions using <code>list results</code> or
<code>l r</code>.</li>
<li>View other <code>list</code> commands using <code>help list</code>.</li>
<li>Monitor real-time logcat with filter using <code>afwtest</code>, then open
another terminal and start logcat using: <code>adb logcat | grep afwtest</code>.
After a test completes:
<ul>
<li>View logs in
<code>out/host/linux-x86/afw-th/android-cts/repository/logs/<em>start-time</em></code>.
The full device logcat and host log (<code>afw-test-tradefed</code> logs) are
saved in separate zip files.</li>
<li>Find relevant information by searching the device logcat for
<strong>afwtest</strong>. Example: <code>zless
out/host/linux-x86/afw-th/android-cts/repository/logs/<em>start-time</em>/device_logcat_<em>random-number</em>.zip
| grep afwtest</code></li>
<li>To view the full afw-test-tradefed log, use: <code>zless
out/host/linux-x86/afw-th/android-cts/repository/logs/<em>start-time</em>/host_log_<em>random-number</em>.zip</code>
</li>
</ul>
</li>
<li>A test package automates an AfW provisioning flow by going through UI pages
and recording a navigation log in the device logcat file for each page.
Example: <code>afwtest.AutomationDriver:
Navigating:com.android.afwtest.uiautomator.pages.gms.AddAccountPage</code>
<br>UI pages for test package
<code>com.android.afwtest.NfcProvisioning</code> include:<ul>
<li>
<code>com.android.afwtest.uiautomator.pages.managedprovisioning.NfcProvisioningPage</code>
</li>
<li><code>com.android.afwtest.uiautomator.pages.PageSkipper</code></li>
<li><code>com.android.afwtest.uiautomator.pages.LandingPage</code></li>
</ul>
</li>
<li>If a test failed during the provisioning process, logcat contains an error
similar to:
<pre class="devsite-click-to-copy">
TestRunner: java.lang.RuntimeException: Failed to load page: com.android.afwtest.uiautomator.pages.packageinstaller.DeviceAccessPage
</pre>
This is typically caused by errors in a previous UI page or the page that
failed to load, so try to find other error messages in logcat before this error,
then try to reproduce it manually following the provisioning flow.</li>
<li>If a test package fails:
<ul>
<li>A screenshot is saved to
<code>out/host/linux-x86/afw-th/android-cts/repository/logs/<em>start-time</em></code>
using the following syntax:
<code>screenshot-test_<em>test_class_full_name</em>_<em>test_case_name</em>-<em>random_number</em>.png</code>.
This information is also logged in the host log.</li>
<li>A bug report is saved to
<code>out/host/linux-x86/afw-th/android-cts/repository/logs/<em>start-time</em></code>
as:
<code>bug-<em>test_class_full_name</em>_<em>test_case_name</em>-<em>random_number</em>.zip</code>.
</li>
</ul>
</li>
<li>After all test packages execute, a screenshot is taken and saved to
<code>out/host/linux-x86/afw-th/android-cts/repository/logs/<em>start-time</em></code>
as: <code>screenshot-<em>random_number</em>.png</code>.
This information is also logged in the host log.</li>
</ul>
<h2 id=faq>FAQ</h2>
<p>For help with questions not answered below, contact
<a href="mailto:afw-testharness-support@google.com">afw-testharness-support@google.com</a>.
</p>
<p><strong>Can I run test plan <code>afw-userdebug-build</code> on a device
flashed with user build?</strong></p>
<p><em>No. Test packages in the <code>afw-userdebug-build</code> plan factory
reset the testing device before running the actual test flow and require
<code>adb</code> debugging to be auto-enabled. With a user build,
<code>adb</code> debugging can be enabled only by manually changing the
setting in Developer options.</em></p>
<p><strong>Can I run test plan <code>afw-user-build</code> on a device flashed
with userdebug build?</strong></p>
<p><em>Yes, but we recommend that you run this test plan on a user build.</em></p>
<p><strong>Sometimes my test fails because UI loading takes too much time. How
can I fix this?</strong></p>
<p><em>Configure the <code>timeout_size</code> setting
in <code>./android-cts/repository/testcases/afw-test.props</code>. Valid
settings are: S, M, L, XL, XXL.</em></p>
<p><strong>The test package
<code>com.android.afwtest.NfcProvisioning</code> (or
<code>SuwDoProvisioning</code>) fails on my device because the installed initial
setup (i.e. Setup Wizard) shows customized UI (such as Term &amp; Conditions)
after provisioning is complete. How can I skip this customized UI?</strong></p>
<p><em>There should be minimal UI after the provisioning process. The test
harness will automatically skip such UI if the UI has a button that has
meaningful text or content description that contains any of the following words:
Skip, Finish, Done, Accept, Agree, Next, Continue, or Proceed. Alternatively,
you can define a button in <code>afw-test.props</code> to configure the test
harness to skip your UI. Example:</em></p>
<pre class="devsite-click-to-copy">
oem_widgets=your_btn
your_btn.text=your_customized_text
your_btn.package=your_package
your_btn.action=click
</pre>
<p><em>To define multiple widgets, separate using commas.</em></p>
<p><strong>The test package
<code>com.android.afwtest.NfcProvisioning</code> (or
<code>SuwDoProvisioning</code>) failed and the last UI screen is "Verify your
account." Why does this happen and how can I recover the testing device?
</strong></p>
<p><em>This failure occurs because the previous test package failed to clear
Factory Reset Protection at the end of the test. You must manually enter the
account to unlock the device.</em></p>
<p><strong>My device needs more time to factory reset. Can I extend the factory
reset timeout?</strong></p>
<p><em>Yes. Configure the <code>factory_reset_timeout_min</code> setting in
<code>afw-test.props</code>. Valid settings are in minutes; you can set to any
number of minutes that works with your device.</em></p>
</body>
</html>

117
android/docs/source.android.com/en/devices/tech/admin/testing-setup.html Normal file
View file

@ -0,0 +1,117 @@
<html devsite>
<head>
<title>Testing Device Administration</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>To ensure minimal support for managed profiles, OEM devices must contain the
following essential elements:</p>
<ul>
<li>Profile owner (as described in
<a href="https://developer.android.com/training/enterprise/app-compatibility.html">Ensuring
Compatibility with Managed Profiles</a>)</li>
<li>Device owner</li>
</ul>
<p>For a complete list of requirements, see
<a href="/devices/tech/admin/implement.html">Implementing Device
Administration</a>.</p>
<p>To test device administration features, device owners can use the TestDPC
application (described below); consider also working directly with other
enterprise mobility management (EMM) providers.</p>
<h2 id=set_up_the_device_owner_for_testing>Set up device owner for testing</h2>
<p>Use the following instructions to set up a device owner testing environment.</p>
<ol>
<li>Set up the device:
<ol>
<li style="list-style-type: lower-alpha">Factory reset the target device.</li>
<li style="list-style-type: lower-alpha">Ensure you do not add any user accounts
(e.g. those used to log into online services) to the device.
This can be checked in <em>Settings->Accounts</em>.</li>
</ol></li>
<li>Set up the testing application using one of the following methods:
<ul>
<li><a href="https://play.google.com/store/apps/details?id=com.afwsamples.testdpc&hl=en">Download
the TestDPC application</a> (available from Google Play).</li>
<li><a href="https://github.com/googlesamples/android-testdpc/">Build
the TestDPC application</a> (available from github.com).</li>
</ul>
</li>
<li>Set the TestDPC app as the device owner using the following command:<br>
<pre class="devsite-terminal devsite-click-to-copy">
adb shell dpm set-device-owner "com.afwsamples.testdpc/.DeviceAdminReceiver"
</pre>
</li>
<li>Go through device owner setup on the device (encrypt, select Wi-Fi, etc.)</li>
</ol>
<h2 id=verify_the_device_owner_was_correctly_setup>Verify device owner setup</h2>
<p>To verify the device owner was correctly setup, go to <em>Settings >
Security > Device Administrators</em> and confirm TestDPC is in the
list. Verify it cannot be disabled (this signifies it is a device owner).</p>
<h2 id=automate>Automated provisioning testing</h2>
<p>To automate the testing of enterprise provisioning processes, use
the Android for Work (AfW) Test Harness. For details, see
<a href="/devices/tech/admin/testing-provision.html">Testing Device
Provisioning</a>.</p>
<h2 id="troubleshooting">Bug reports and logs</h2>
<p>In Android 7.0, device owner Device Policy Client (DPCs) can get bug reports
and view logs for enterprise processes on a managed device.</p>
<p>To trigger a bug report (i.e., the equivalent data collected by <code>adb
bugreport</code> containing dumpsys, dumpstate, and logcat data), use
<code>DevicePolicyController.requestBugReport</code>. After the bug report is
collected, the user is prompted to give consent to send the bug report data.
Results are received by
<code>DeviceAdminReceiver.onBugreport[Failed|Shared|SharingDeclined]</code>. For
details on bug report contents, see
<a href="/source/read-bug-reports.html">Reading Bug Reports</a>.
<p>In addition, device owner DPCs can also collect logs related to actions a
user has taken on a managed device. Enterprise process logging is required for
all devices that report device_admin and enabled by a new log security buffer
readable only by the system server (i.e., <code>adb logcat -b security</code>
cannot read the buffer). ActivityManager service and Keyguard components log the
following events to the security buffer:</p>
<ul>
<li>Application processes starting</li>
<li>Keyguard actions (e.g., unlock failure and success)</li>
<li><code>adb</code> commands issued to the device</li>
</ul>
<p>To optionally retain logs across reboots (not cold boot) and make these logs
available to device owner DPCs, a device must have a kernel with
<code>pstore</code> and <code>pmsg</code> enabled, and DRAM powered and
refreshed through all stages of reboot to avoid corruption to the logs retained
in memory. To enable support, use the
<code>config_supportPreRebootSecurityLogs</code> setting in
<code>frameworks/base/core/res/res/values/config.xml</code>.</p>
</body>
</html>