Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit ebae30fc authored by Adarsh Fernando's avatar Adarsh Fernando
Browse files

Docs: Added Data Saver N Developer Preview feature page

Bug: 27048177
Change-Id: Ib4e856bb26f78f9566a9db142a70d1ed4ac285df
parent 982e93bc
Loading
Loading
Loading
Loading
+146 −0
Original line number Diff line number Diff line
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