Docs: Afw updates for N
Adding content for b/28942322
Removing setup wizard refs
Replacing testing app (now TestDPC)
Updating based on comments
Bug: 28315422, 28942322
Change-Id: I68d174f64f7edc8753688e3830ec91a828140b5b
diff --git a/src/devices/tech/admin/implement.jd b/src/devices/tech/admin/implement.jd
index 03ce93c..9c1d1b4 100644
--- a/src/devices/tech/admin/implement.jd
+++ b/src/devices/tech/admin/implement.jd
@@ -24,45 +24,92 @@
</div>
</div>
-<p>This page walks you through the many features in Android 5.0 and higher
-platform release that need to be enabled and validated on devices to make them
-ready for managed profile and device owner user cases that are essential to using
-them in a corporate environment. In addition to the related Android Open Source
-Project (AOSP) code, there are a number of additional components required for a
-device to function with managed profiles.</p>
+<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>
-<h2 id=requirements>Requirements</h2>
+<p>In addition to Android Open Source Project (AOSP) code, a device requires the
+following components to function with managed profiles.</p>
-<p>The following uses-feature need to be defined:</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 N includes support for HardwarePropertiesManager API, a new 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>
android.software.managed_users
android.software.device_admin
</pre>
-<p>Confirm with: <code>adb shell pm list features</code></p>
+<p>To confirm these <code>uses-feature</code> values have been defined on a
+device, run: <code>adb shell pm list features</code>.</p>
-<p>It 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=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>
-<p>By default, only applications that are essential for correct operation of the
-profile should be enabled as part of provisioning a managed device.</p>
-
-<p>OEMs must ensure the managed profile or device has all required applications by
-modifying:</p>
-
-<pre>
-vendor_required_apps_managed_profile.xml
+<pre>vendor_required_apps_managed_profile.xml
vendor_required_apps_managed_device.xml
</pre>
-<p>Here are examples from a Nexus device:</p>
+<p>Examples from a Nexus device:</p>
-<code>packages/apps/ManagedProvisioning/res/values/vendor_required_apps_managed_device.xml</code>
+<p><code>packages/apps/ManagedProvisioning/res/values/vendor_required_apps_managed_device.xml</code></p>
-<pre>
-<resources>
+<pre><resources>
<!-- A list of apps to be retained on the managed device -->
<string-array name="vendor_required_apps_managed_device">
<item>com.android.vending</item> <!--Google Play -->
@@ -75,9 +122,9 @@
</resources>
</pre>
-<code>
+<p><code>
packages/apps/ManagedProvisioning/res/values/vendor_required_apps_managed_profile.xml
-</code>
+</code></p>
<pre>
<resources>
@@ -90,42 +137,38 @@
</resources>
</pre>
-<h3 id=launcher>Launcher</h3>
+<h2 id=launcher>Launcher requirements</h2>
-<p>The launcher must support badging applications with the icon badge provided
-in the Android Open Source Project (AOSP) to represent the managed applications
-and other badge user interface elements such as recents and notifications.</p>
+<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>
-<p>Update the Launcher to support badging. If you use <a
-href="https://android.googlesource.com/platform/packages/apps/Launcher3/">launcher3</a>
-in AOSP as-is, then you likely already support this badging feature.
-</p>
+<h2 id=nfc>NFC requirements</h2>
-<h3 id=nfc>NFC</h3>
+<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>
-<p>On devices with NFC, NFC must be enabled in the Android Setup Wizard and
-configured to accept managed provisioning intents:</p>
-
-<code>packages/apps/Nfc/res/values/provisioning.xml</code>
-
-<pre>
-<bool name="enable_nfc_provisioning">true</bool>
+<p><code>packages/apps/Nfc/res/values/provisioning.xml</code></p>
+<pre><bool name="enable_nfc_provisioning">true</bool>
<item>application/com.android.managedprovisioning</item>
</pre>
-<h3 id=setup_wizard>Setup Wizard</h3>
+<h2 id=setup_wizard>Setup requirements</h2>
-<p>The Android Setup Wizard needs to support device owner provisioning. When it
-opens, it needs to check if another process (such as device owner provisioning)
-has already finished the user setup. If this is the case, it needs to fire a
-home intent and finish the setup wizard. </p>
+<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>This intent will be caught by the provisioning application, which will then
-hand over control to the newly set device owner. This can be achieved by adding
-the following to your setup wizard’s main activity:</p>
+<p>To meet setup requirements, add the following code to the device setup's main
+activity:</p>
-<pre>
-@Override
+<pre>@Override
protected void onStart() {
super.onStart();
@@ -133,7 +176,7 @@
// has intervened and, if so, complete an orderly exit
boolean completed = Settings.Secure.getInt(getContentResolver(),
Settings.Secure.USER_SETUP_COMPLETE, 0) != 0;
- if (completed) {
+ if (completed) {
startActivity(new Intent(Intent.ACTION_MAIN, null)
.addCategory(Intent.CATEGORY_HOME)
.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK
diff --git a/src/devices/tech/admin/managed-profiles.jd b/src/devices/tech/admin/managed-profiles.jd
index 8951166..72463f5 100644
--- a/src/devices/tech/admin/managed-profiles.jd
+++ b/src/devices/tech/admin/managed-profiles.jd
@@ -25,49 +25,40 @@
</div>
<p>A <em>managed profile</em> or <em>work profile</em> is an Android <a
-href="multi-user.html">user</a> with some additional special properties around
+href="multi-user.html">user</a> with additional special properties around
management and visual aesthetic.</p>
-<h2 id=purpose>DevicePolicyManager APIs</h2>
-
-<p>Android 5.x or newer 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.
-You may 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. See <a
-href="https://developer.android.com/training/enterprise/work-policy-ctrl.html">Building
-a Work Policy Controller</a> for additional details.
-
-<h2 id=purpose>Purpose</h2>
-
<p>The primary goal of a managed profile is to create a segregated and secure
-space for managed (for example, corporate) data to reside. The administrator of
+space for managed data (such as corporate date) 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><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><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><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>
+<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 cannot
-communicate directly with one another across the profile-user boundary and act
-independently of one another.</p>
+<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>
@@ -83,63 +74,63 @@
<h3 id=settings>Settings</h3>
-<p>Enforcement of settings is generally scoped to the managed profile with a few
-exceptions. Specifically, lockscreen and encryption settings are still scoped
+<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>
-uid = 100000 * userid + appid
-</pre>
-
+<pre>uid = 100000 * userid + appid</pre>
<p>They have separate app data like regular users:</p>
-<pre>
-/data/user/<userid>
-</pre>
+<pre>/data/user/<userid></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 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.</p>
-
-<p>The main differences between a managed profile and a regular secondary user are
-as follows:</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> Notifications for managed profiles are enabled by ActivityManagerService
-allowing the managed profile to share the activity stack with the primary user.
- <li> Some other system services shared are: IME, A11Y services, Wi-Fi, and NFC.
- <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>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 two new types of device administrators for
-enterprises:</p>
+<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><em>Device Owner</em>—Designed for corp-liable environments
+ <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 that have been 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>
+<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)
+<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
@@ -148,25 +139,39 @@
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>
+<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>Enforced disclosure always displayed in quick-settings
+ <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, and here are a few examples:</p>
+<p>Device owners can conduct some tasks profile owners cannot, such as:</p>
<ul>
- <li>Wipe device data
- <li>Disable Wi-Fi/ BT
- <li>Control <code>setGlobalSetting</code>
- <li><code>setLockTaskPackages</code> (the ability to whitelist packages that can pin themselves to the foreground)
- <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>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>
diff --git a/src/devices/tech/admin/multi-user.jd b/src/devices/tech/admin/multi-user.jd
index 8319be0..24b4da8 100644
--- a/src/devices/tech/admin/multi-user.jd
+++ b/src/devices/tech/admin/multi-user.jd
@@ -24,139 +24,169 @@
</div>
</div>
-<p>This document describes the Android multi-user feature. It allows more than one
-user on a single Android device by separating their accounts and application
-data. For instance, parents may let their children use the family tablet. Or a
-critical team might share a mobile device for on-call duty.</p>
+<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>
-<h1 id=definitions>Definitions</h1>
+<h2 id=definitions>Terminology</h2>
+<p>Android uses the following terms when describing Android users and accounts.</p>
-<p>Before supporting multiple Android users, you should understand the basic
-concepts involved. Here are the primary terms used 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><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. See the <a href="https://developer.android.com/reference/android/accounts/Account.html">Account class</a> definition.
- <li><em>Profile<strong></em> </strong>- 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><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. See <a href="https://developer.android.com/training/enterprise/index.html">Building Apps for Work</a>.
+ <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>
-<h2 id=user_types>User types</h2>
+<h3 id=user_types>User types</h3>
+<p>Android device administration uses the following user types.</p>
<ul>
- <li><em>Primary</em> - The first user added to a device. The primary user cannot be removed except
-by factory reset. This user also has some special privileges and settings only
-it can set. The primary user is always running even when other users are in the
-foreground.
- <li><em>Secondary</em> - Any user added to the device other than the primary user. They can be
-removed by either themselves or the primary user and cannot impact other users
-on a device. Secondary users can run in the background and will continue to
-have network connectivity when they do.
- <li><em>Guest<strong></em> </strong>- A guest user is a temporary secondary user with 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><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>
-<h2 id=profile_types>Profile types</h2>
+<h3 id=profile_types>Profile types</h3>
+<p>Android device administration uses the following profile types.</p>
<ul>
- <li><em>Managed<strong></em> </strong>- Managed profiles are created by an application to contain work data and
-apps. They are managed exclusively by the ‘profile owner’, the app who created
-the corp profile. Launcher, notifications and recent tasks are shared by the
-primary user and the corp profile.
- <li><em>Restricted</em> - Restricted profiles use the accounts based off the primary user. The Primary
-user can control what apps are available on the restricted profile. Restricted
-profiles are available only on tablets.
+ <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.</li>
</ul>
-<h1 id=effects>Effects</h1>
+<h2 id=applying_the_overlay>Enabling multi-user</h2>
-<p>When users are added to a device, some functionality will be 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>The default state is 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
-Settings > Users, select the user, and switch the <em>Allow phone calls and SMS</em> setting to off.</p>
-
-<p>Please note, some restrictions exist when a secondary user is in background.
-For instance, the background secondary user will not be able to display the
-user interface or make Bluetooth services active. Finally, background secondary
-users will be halted by the system process if the device needs additional
-memory for operations in the foreground user.</p>
-
-<p>Here are aspects of behavior to keep in mind when employing multiple users on
-an Android device:</p>
-
-<ul>
- <li>Notifications appear for all accounts of a single user at once.
- <li>Notifications for other users do not appear until they are active.
- <li>Each user gets his or her own workspace to install and place apps.
- <li>No user has access to the app data of another user.
- <li>Any user can affect the installed apps for all users.
- <li>The primary user can remove apps or even the entire workspace established by
-secondary users.
-</ul>
-
-<h1 id=implementation>Implementation</h1>
-
-<h2 id=managing_users>Managing 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. They may use 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=applying_the_overlay>Applying the overlay</h2>
-
-<p>The multi-user feature is disabled by default in the Android 5.0 release. To
+<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 frameworks/base/core/res/res/values/config.xml:</p>
+the following values in <code>frameworks/base/core/res/res/values/config.xml</code>:
+</p>
-<pre>
-<!-- Maximum number of supported users -->
+<pre><!-- Maximum number of supported users -->
<integer name="config_multiuserMaximumUsers">1</integer>
<!-- Whether Multiuser UI should be shown -->
<bool name="config_enableMultiUserUI">false</bool>
</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>
+<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> Replace the value of <code>config_enableMultiUserUI</code> with: <code>true</code>
+ <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.</p>
+<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="{@docRoot}compatibility/android-cdd.pdf">Android Compatibility
+Definition Document</a> (CDD).</p>
-<p>That said, if device manufacturers or others have modified settings, they need
-to ensure SMS and telephony work as defined in the <a
-href="{@docRoot}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 N 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 N device administration features, refer to
+<a href="https://developer.android.com/preview/features/afw.html">Android
+for Work Updates</a>.</p>
diff --git a/src/devices/tech/admin/provision.jd b/src/devices/tech/admin/provision.jd
index a1b20bc..abd3e01 100644
--- a/src/devices/tech/admin/provision.jd
+++ b/src/devices/tech/admin/provision.jd
@@ -24,34 +24,35 @@
</div>
</div>
-<p>This page describes the process for deploying devices to corporate users.</p>
+<p>This page describes the process for deploying devices to corporate users
+using NFC or with an activation code (for a complete list of requirements, see
+<a href="{@docRoot}devices/tech/admin/implement.html">Implementing Device
+Administration</a>).</p>
-<p>Device owner provisioning can be accomplished over NFC or with an activation
-code. See <a href="implement.html">Implementing Device Administration</a> for
-the complete list of requirements.</p>
-
-<p>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>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 will first need to be factory reset.</p>
+started, affected devices must be factory reset first.</p>
-<h2 id=managed_provisioning>Managed Provisioning</h2>
+<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. You can
-think of it as a setup wizard for managed profiles.</p>
+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> Remember, the device owner can be set
-only from an unprovisioned device. If
-<code>Settings.Secure.USER_SETUP_COMPLETE</code> has ever been set, then the
-device is considered provisioned & device owner cannot be set.</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>Please note, devices that enable default encryption offer considerably
-simpler/quicker device administration provisioning flow. The managed provisioning
+<p>Devices that enable default encryption offer a considerably simpler and
+quicker device administration provisioning flow. The managed provisioning
component:</p>
<ul>
@@ -70,29 +71,31 @@
</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.</p>
+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>
-<p>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>
-<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>Profile owner provisioning assumes the user of the device oversees its
-management (and not a company IT department). To enable, profile owner
-provisioning, you must send an intent with appropriate extras. See the <a href="https://developer.android.com/samples/BasicManagedProfile/index.html">BasicManagedProfile.apk</a> for an example.</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>
-<p>Mobile Device Management (MDM) applications trigger the creation of the managed
-profile by sending an intent with action:</p>
-
-<p><a href="https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/app/admin/DevicePolicyManager.java">DevicePolicyManager.ACTION_PROVISION_MANAGED_PROFILE</a></p>
-
-<p>Here is a sample intent that will trigger the creation of the managed profile
-and set the DeviceAdminSample as the profile owner:</p>
-
-<pre>
-adb shell am start -a android.app.action.PROVISION_MANAGED_PROFILE \
+<pre>adb shell am start -a android.app.action.PROVISION_MANAGED_PROFILE \
-c android.intent.category.DEFAULT \
-e wifiSsid $(printf '%q' \"GoogleGuest\") \
-e deviceAdminPackage "com.google.android.deviceadminsample" \
@@ -101,15 +104,16 @@
-e android.app.extra.DEFAULT_MANAGED_PROFILE_NAME "My Organisation"
</pre>
-<h2 id=device_owner_provisioning_via_nfc>Device Owner Provisioning via NFC</h2>
+<h2 id=device_owner_provisioning_via_nfc>Device owner provisioning via NFC</h2>
<p>Device owner provisioning via NFC is similar to the profile owner method but
-requires more bootstrapping before managed provisioning.</p>
+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>To use this method, <a href="http://developer.android.com/guide/topics/connectivity/nfc/nfc.html">NFC bump</a> the device from the first page of setup wizard (SUW). This offers a low-touch
-flow and configures Wi-Fi, installs the DPC, and sets the DPC as device owner.</p>
-
-<p>Here is the typical NFC bundle:</p>
+<p>A typical NFC bundle includes the following:</p>
<pre>
EXTRA_PROVISIONING_DEVICE_ADMIN_PACKAGE_NAME
@@ -119,53 +123,55 @@
EXTRA_PROVISIONING_WIFI_SECURITY_TYPE
</pre>
-<p>The device must have NFC configured to accept the managed provisioning mimetype
-from SUW:</p>
+<p>Devices must have NFC configured to accept the managed provisioning
+mimetype from the setup experience:</p>
-<pre>
-/packages/apps/Nfc/res/values/provisioning.xml
+<pre>/packages/apps/Nfc/res/values/provisioning.xml
<bool name="enable_nfc_provisioning">true</bool>
<item>application/com.android.managedprovisioning</item>
</pre>
-<h2 id=device_owner_provisioning_with_activation_code>Device Owner Provisioning with Activation Code</h2>
+<h2 id=device_owner_provisioning_with_activation_code>Device owner provisioning
+with activation code</h2>
-<p>Select <em>Add Work Account</em> from the setup wizard. This triggers a
-lookup of the EMM from Android servers.</p>
-
-<p>The device installs the EMM app and starts provisioning flow. As an extra
-option, Android device administration supports the option of using email
-address with a six-digit activation code to bootstrap the process as part of
-setup wizard.</p>
+<p>Select <em>Add Work Account</em> from the setup/out-of-box experience (this
+triggers a lookup of the EMM from Android servers). The device installs the EMM
+app and starts provisioning flow. As an extra option, Android device
+administration supports the option of using email address with a six-digit
+activation code to bootstrap the process as part of setup.</p>
<h2 id=emm_benefits>EMM benefits</h2>
-<p>An EMM can help by conducting these tasks for you:</p>
+<p>An enterprise mobility management (EMM) app can help by conducting the
+following tasks:</p>
<ul>
- <li>Provision managed profile
+ <li>Provision managed profile</li>
<li>Apply security policies
<ul>
- <li>Set password complexity
- <li>Lockdowns: disable screenshots, sharing from managed profile, etc.
- </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>Configure VPN on the device
- <li>Use DPM.setApplicationRestrictions() to configure corporate VPN
- </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 DPM.installKeyPair()to silently install corp client certs
- <li>Use DPM.setApplicationRestrictions() to configure hostnames, cert alias’ of
-corporate apps
- </ul>
+ <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 piece of the EMM end-to-end workflow, with the
- end goal being to make corporate data accessible to apps in the managed profile.</p>
-
-<p>See <a href="testing-setup.html">Setting up Device Testing</a> for testing instructions.</p>
+<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="{@docRoot}devices/tech/admin/testing-setup.html">Setting up Device
+Testing</a>.</p>
diff --git a/src/devices/tech/admin/testing-setup.jd b/src/devices/tech/admin/testing-setup.jd
index 678c04b..129fa8e 100644
--- a/src/devices/tech/admin/testing-setup.jd
+++ b/src/devices/tech/admin/testing-setup.jd
@@ -24,70 +24,84 @@
</div>
</div>
-<p>These are the essential elements that must exist for OEM devices to ensure
-minimal support for managed profiles:</p>
+<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>Device Owner
- <li>Activation Code Provisioning
+ <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>
+ <li>Activation code provisioning</li>
</ul>
-<p>See <a href="implement.html">Implementing Device Administration</a> for the complete list of requirements.</p>
-<h2 id=summary>Summary</h2>
-<p>To test your device administration features:</p>
+<p>For a complete list of requirements, see
+<a href="{@docRoot}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>For device owner, use the <a
-href="https://developer.android.com/samples/BasicManagedProfile/index.html">BasicManagedProfile.apk</a>
-test app.
- <li>Consider working with other enterprise mobility management (EMM) providers
-directly.
-</ol>
-
-<h2 id=set_up_the_device_owner_for_testing>Set up the device owner for testing</h2>
-<ol>
- <li>Device MUST be built with <strong>userdebug</strong> or <strong>eng</strong> build.
+ <li>Set up the device:
+ <ol>
+ <li style="list-style-type: lower-alpha">Ensure the device uses a
+ <strong>userdebug</strong> or <strong>eng</strong> build.</li>
+ <li style="list-style-type: lower-alpha">Factory reset the target device.</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>Factory reset the target device (and continue with the next steps in the
- meantime).
- </li>
- <li>Download <a
- href="http://developer.android.com/downloads/samples/BasicManagedProfile.zip">BasicManagedProfile.zip</a>. (Also see the <a
- href="http://developer.android.com/samples/BasicManagedProfile/index.html">BasicManagedProfile</a> documentation.)</li>
- <li>Unzip the file.
- <li>Navigate (<code>cd</code>) to the unzipped directory.</li>
- <li>If you don't have it, download the <a href="http://developer.android.com/sdk/index.html#Other">Android SDK Tools</a> package.</li>
- <li>Create a file with the name <code>local.properties</code> containing the following single
- line:<br>
- <code>sdk.dir=<em><path to your android SDK folder></em></code><br>
- <li>On Linux and Mac OS, run:<br>
- <code>./gradlew assembleDebug</code><br>
- Or on windows run:<br>
- <code>gradlew.bat assembleDebug</code></li>
- <li>If the build is unsuccessful because you have an outdated android SDK, run:<br>
- <code><em><your android sdk folder></em>/tools/android update sdk -u -a</code></li>
- <li>Wait for factory reset to complete if it hasn’t yet.<br>
- <p class="Caution"><strong>Caution</strong>: Stay on the first screen
- after factory reset and do not finish the setup wizard.</li>
- <li>Install the BasicManagedProfile app by running the following command:<br>
- <code>adb install ./Application/build/outputs/apk/Application-debug.apk </code>
- </li>
- <li>Set this app as the device owner by running this command:<br><code>$ adb shell am start -a
- com.android.managedprovisioning.ACTION_PROVISION_MANAGED_DEVICE --es
- android.app.extra.PROVISIONING_DEVICE_ADMIN_PACKAGE_NAME
- com.example.android.basicmanagedprofile</code>
+ <li>Set the TestDPC app as the device owner using the following command:<br>
+ <pre>$ 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 the device owner was correctly setup</h2>
-<ol>
- <li>Go to <em>Settings > Security > Device Administrators</em>.
- </li>
- <li>Confirm the BasicManagedProfile is in the list and verify it cannot be
- disabled. (This signifies it is a device owner.)
- </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="troubleshooting">Bug reports and logs</h2>
+<p>In Android N, 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="{@docRoot}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>