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

<restrictions xmlns:android="http://schemas.android.com/apk/res/android" >

  <restriction

    android:key="downloadOnCellular"

    android:title="App is allowed to download data via cellular"

    android:key="download_on_cell"

    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" />

</restrictions>

  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

  </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>

  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">

  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

  restrictions {@link android.os.Bundle}, you can check the current

  restrictions settings with the standard {@link android.os.Bundle} methods for

  those data types, such as {@link android.os.Bundle#getBoolean getBoolean()}

  or

  <code>String</code>, <code>String[]</code>, <code>Bundle</code>, and

  <code>Bundle[]</code>. Once you have the restrictions {@link android.os.Bundle},

  you can check the current restrictions settings with the standard

  {@link android.os.Bundle} methods for those data types, such as

  {@link android.os.Bundle#getBoolean getBoolean()} or

  {@link android.os.Bundle#getString getString()}.

</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

  whether it can download data over a cellular connection, and you find that

  the restriction is set to <code>false</code>, you would have to disable data

  download except when the device has a Wi-Fi connection, as shown in the

  restrictions settings. For example, if your app has a restriction schema

  to specify whether it can download over a cellular connection (like the

  example in <a href="#define_restrictions">Define App Restrictions</a>),

  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>

    // ...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>

  <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=

  "#check_restrictions">Check Device Restrictions</a>), then register your

  broadcast receiver to make sure you're notified about restriction changes

  first check for the current restrictions (as discussed in

  <a href="#check_restrictions">Check App Restrictions</a>), then register

  your broadcast receiver to make sure you're notified about restriction changes

  that happen while the app is active.

</p>

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

 No newline at end of file