Merge "docs: Updates to Implementing App Restrictions 3" into mnc-docs

docs/html/training/enterprise/app-restrictions.jd

@@ -152,10 +152,10 @@ enterprise administrator to:</p>
 &lt;restrictions xmlns:android="http://schemas.android.com/apk/res/android" &gt;
 
   &lt;restriction
-    android:key="downloadOnCellular"
+    android:key="download_on_cell"
-    android:title="App is allowed to download data via cellular"
+    android:title="@string/download_on_cell_title"
     android:restrictionType="bool"
-    android:description="If 'false', app can only download data via Wi-Fi"
+    android:description="@string/download_on_cell_description"
     android:defaultValue="true" /&gt;
 
 &lt;/restrictions&gt;
@@ -166,6 +166,12 @@ enterprise administrator to:</p>
   documented in the reference for {@link android.content.RestrictionsManager}.
 </p>
 
+<p class="note">
+  <strong>Note:</strong> <code>bundle</code> and
+  <code>bundle_array</code> restriction types are not supported by Google Play
+  for Work.
+</p>
+
 <p>
   You use each restriction's <code>android:key</code> attribute to read its
   value from a restrictions bundle. For this reason, each restriction must have
@@ -211,7 +217,7 @@ enterprise administrator to:</p>
   </li>
 
   <li>When the app is notified of a restriction change, as described in
-    <a href="#listen">Listen for Device Configuration
+    <a href="#listen">Listen for App Configuration
     Changes</a>
   </li>
 </ul>
@@ -254,9 +260,30 @@ enterprise administrator to:</p>
   the {@link android.content.Intent#ACTION_APPLICATION_RESTRICTIONS_CHANGED
   ACTION_APPLICATION_RESTRICTIONS_CHANGED} intent to find out if restrictions
   change while your app is active, as described in <a href="#listen">Listen for
-  Device Configuration Changes</a>.
+  App Restriction Changes</a>.
 </p>
 
+<p>
+  When your app checks for restrictions using
+ {@link android.content.RestrictionsManager#getApplicationRestrictions
+ RestrictionsManager.getApplicationRestrictions()}, we recommend that you
+ check to see if the enterprise administrator has set the key-value pair
+ {@link android.os.UserManager#KEY_RESTRICTIONS_PENDING} to true. If so, you
+ should block the user from using the app, and prompt them to contact their
+ enterprise administrator. The app should then proceed as normal, registering
+ for the {@link android.content.Intent#ACTION_APPLICATION_RESTRICTIONS_CHANGED
+ ACTION_APPLICATION_RESTRICTIONS_CHANGED} broadcast.
+</p>
+
+<img src="{@docRoot}images/training/enterprise/app_restrictions_diagram.png"
+width="620" srcset="{@docRoot}images/training/enterprise/app_restrictions_diagram.png 1x,
+{@docRoot}images/training/enterprise/app_restrictions_diagram_2x.png 2x" />
+
+ <p class="img-caption">
+   <strong>Figure 1.</strong> Checking whether restrictions are pending before
+   registering for the broadcast.
+ </p>
+
 <h3 id="read_restrictions">
   Reading and applying restrictions
 </h3>
@@ -266,11 +293,11 @@ enterprise administrator to:</p>
   getApplicationRestrictions()} method returns a {@link android.os.Bundle}
   containing a key-value pair for each restriction that has been set. The
   values are all of type <code>Boolean</code>, <code>int</code>,
-  <code>String</code>, and <code>String[]</code>. Once you have the
+  <code>String</code>, <code>String[]</code>, <code>Bundle</code>, and
-  restrictions {@link android.os.Bundle}, you can check the current
+  <code>Bundle[]</code>. Once you have the restrictions {@link android.os.Bundle},
-  restrictions settings with the standard {@link android.os.Bundle} methods for
+  you can check the current restrictions settings with the standard
-  those data types, such as {@link android.os.Bundle#getBoolean getBoolean()}
+  {@link android.os.Bundle} methods for those data types, such as
-  or
+  {@link android.os.Bundle#getBoolean getBoolean()} or
   {@link android.os.Bundle#getString getString()}.
 </p>
 
@@ -284,10 +311,11 @@ enterprise administrator to:</p>
 
 <p>
   It is up to your app to take appropriate action based on the current
-  restrictions settings. For example, if your app has a restriction specifying
+  restrictions settings. For example, if your app has a restriction schema
-  whether it can download data over a cellular connection, and you find that
+  to specify whether it can download over a cellular connection (like the
-  the restriction is set to <code>false</code>, you would have to disable data
+  example in <a href="#define_restrictions">Define App Restrictions</a>),
-  download except when the device has a Wi-Fi connection, as shown in the
+  and you find that the restriction is set to false, you would have to disable
+  data download except when the device has a Wi-Fi connection, as shown in the
   following example code:
 </p>
 
@@ -307,6 +335,13 @@ if (!appCanUseCellular) {
     // ...show appropriate notices to user
 }</pre>
 
+<p class="note">
+   <strong>Note:</strong> The restrictions schema should be
+   backward and forward compatible, since Google Play for Work
+   gives the EMM only one version of the App Restrictions
+   Schema per app.
+ </p>
+
 <h2 id="listen">
   Listen for App Restriction Changes
 </h2>
@@ -354,8 +389,8 @@ registerReceiver(restrictionsReceiver, restrictionsFilter);
   <strong>Note:</strong> Ordinarily, your app does not need to be notified
   about restriction changes when it is paused. Instead, you should unregister
   your broadcast receiver when the app is paused. When the app resumes, you
-  first check for the current restrictions (as discussed in <a href=
+  first check for the current restrictions (as discussed in
-  "#check_restrictions">Check Device Restrictions</a>), then register your
+  <a href="#check_restrictions">Check App Restrictions</a>), then register
-  broadcast receiver to make sure you're notified about restriction changes
+  your broadcast receiver to make sure you're notified about restriction changes
   that happen while the app is active.
 </p>

docs/image_sources/training/enterprise/app_restrictions_diagram.txt

@@ -0,0 +1,5 @@
+The source file for app_restrictions_diagram.png is a
+Google Doc owned by Matt Werner, mattwerner@google.com.
+You can access the diagram in this doc:
+
+https://docs.google.com/document/d/1qffQfciilSYHHJxpWCs-VEsANnbIt69Zz1qmQuGe0Wc/edit