Docs: Added Data Saver N Developer Preview feature page

Bug: 27048177
Change-Id: Ib4e856bb26f78f9566a9db142a70d1ed4ac285df

diff --git a/docs/html/preview/features/data-saver.jd b/docs/html/preview/features/data-saver.jd
new file mode 100644 (file)
index 0000000..4ea47d5
--- /dev/null
+++ b/docs/html/preview/features/data-saver.jd
@@ -0,0 +1,146 @@
+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