Docs: Added Data Saver N Developer Preview feature page

page.title=N Developer Preview Data Saver

metaDescription=User-enabled data usage optimization.

page.keywords="android N", "data usage", "metered network"

@jd:body

<div id="qv-wrapper">

  <div id="qv">

    <h2>

      In this document

    </h2>

    <ol>

      <li>

        <a href="#status">Checking User Data Saver Preferences</a>

      </li>

      <li>

        <a href="#monitor-changes">Monitoring Changes to Data Saver

        Preferences</a>

      </li>

    </ol>

  </div>

</div>

<p>

  Over the life of a smartphone, the cost of a cellular data plan can easily

  exceed the cost of the device itself. In the N Developer Preview, users can

  enable Data Saver in order to use less data, whether roaming, near the end of

  the billing cycle, or on a small prepaid data pack.

</p>

<p>

  When a user enables Data Saver in <strong>Settings</strong> and the device is

  on a metered network, the system blocks background data usage and signals

  apps to use less data in the foreground wherever possible. Users can

  whitelist specific apps to allow background metered data usage even when Data

  Saver is turned on.

</p>

<p>

  The N Developer Preview extends the {@link android.net.ConnectivityManager}

  API to provide apps a way to <a href="#status">retrieve the user’s Data Saver

  preferences</a> and <a href="#monitor-changes">monitor preference

  changes</a>. It is considered good practice for apps to check whether the

  user has enabled Data Saver and make an effort to limit foreground and

  background data usage.

</p>

<h1 id="status">

  Checking the User's Data Saver Preferences

</h1>

<p>

  In the N Developer Preview, apps can use the {@link

  android.net.ConnectivityManager} API to determine what data usage

  restrictions are being applied. The {@code getRestrictBackgroundStatus()}

  method returns one of the following values:

</p>

<dl>

  <dt>

    {@code RESTRICT_BACKGROUND_STATUS_DISABLED}

  </dt>

  <dd>

    Data Saver is disabled.

  </dd>

  <dt>

    {@code RESTRICT_BACKGROUND_STATUS_ENABLED}

  </dt>

  <dd>

    The user has enabled Data Saver for this app. Apps should make an effort to limit data

    usage in the foreground and gracefully handle restrictions to background

    data usage.

  </dd>

  <dt>

    {@code RESTRICT_BACKGROUND_STATUS_WHITELISTED}

  </dt>

  <dd>

    The user has enabled Data Saver but the app is whitelisted. Apps should

    still make an effort to limit foreground and background data usage.

  </dd>

</dl>

<p>

  It is considered good practice to limit data usage whenever the device is

  connected to a metered network, even if Data Saver is disabled or the app

  is whitelisted. The following sample code uses {@link

  android.net.ConnectivityManager#isActiveNetworkMetered

  ConnectivityManager.isActiveNetworkMetered()} and {@code

  ConnectivityManager.getRestrictBackgroundStatus()} to determine how much data

  the app should use:

</p>

<pre>

ConnectivityManager connMgr = (ConnectivityManager)

        getSystemService(Context.CONNECTIVITY_SERVICE);

// Checks if the device is on a metered network

if (connMgr.isActiveNetworkMetered()) {

  // Checks user’s Data Saver settings.

  switch (connMgr.getRestrictBackgroundStatus) {

    case RESTRICT_BACKGROUND_STATUS_ENABLED:

    // Background data usage is blocked for this app. Wherever possible,

    // the app should also use less data in the foreground.

    case RESTRICT_BACKGROUND_STATUS_WHITELISTED:

    // The app is whitelisted. Wherever possible,

    // the app should use less data in the foreground and background.

    case RESTRICT_BACKGROUND_STATUS_DISABLED:

    // Data Saver is disabled. Since the device is connected to a

    // metered network, the app should use less data wherever possible.

  }

} else {

  // The device is not on a metered network.

  // Use data as required to perform syncs, downloads, and updates.

}

</pre>

<h1 id="monitor-changes">

  Monitoring Changes to Data Saver Preferences

</h1>

<p>

  Apps can monitor changes to Data Saver preferences by creating a {@link

  android.content.BroadcastReceiver} to listen for {@code

  ConnectivityManager.ACTION_RESTRICT_BACKGROUND_CHANGED} ({@code

  "android.net.conn.RESTRICT_BACKGROUND_CHANGED"}) and dynamically registering

  the receiver with {@link android.content.Context#registerReceiver

  Context.registerReceiver()}. When an app receives this broadcast, it should

  <a href="#status">check if the new Data Saver preferences affect its

  permissions</a> by calling {@code

  ConnectivityManager.getRestrictBackgroundStatus()}.

</p>

<p class="note">

  <strong>Note:</strong> The system only sends this broadcast to apps that

  dynamically register for them with {@link

  android.content.Context#registerReceiver Context.registerReceiver()}. Apps

  that register to receive this broadcast in their manifest will not receive

  them.

</p>

 No newline at end of file