David Friedman | bf31c62 | 2016-03-03 13:55:00 -0800 | [diff] [blame] | 1 | page.title=Data Saver |
Adarsh Fernando | ebae30fc | 2016-03-01 11:09:49 -0800 | [diff] [blame] | 2 | metaDescription=User-enabled data usage optimization. |
| 3 | page.keywords="android N", "data usage", "metered network" |
| 4 | @jd:body |
| 5 | |
| 6 | <div id="qv-wrapper"> |
| 7 | <div id="qv"> |
| 8 | <h2> |
| 9 | In this document |
| 10 | </h2> |
| 11 | |
| 12 | <ol> |
| 13 | <li> |
Adarsh Fernando | 1c796b1 | 2016-03-08 17:01:36 -0800 | [diff] [blame] | 14 | <a href="#status">Checking Data Saver Preferences</a> |
Adarsh Fernando | 2ba8e2a | 2016-05-09 10:24:38 -0700 | [diff] [blame] | 15 | <ol> |
| 16 | <li> |
Adarsh Fernando | b1386a7 | 2016-05-12 15:18:14 -0700 | [diff] [blame^] | 17 | <a href="#request-whitelist">Requesting whitelist permissions</a> |
Adarsh Fernando | 2ba8e2a | 2016-05-09 10:24:38 -0700 | [diff] [blame] | 18 | </li> |
| 19 | </ol> |
Adarsh Fernando | ebae30fc | 2016-03-01 11:09:49 -0800 | [diff] [blame] | 20 | </li> |
| 21 | |
| 22 | <li> |
Adarsh Fernando | 2ba8e2a | 2016-05-09 10:24:38 -0700 | [diff] [blame] | 23 | <a href="#monitor-changes">Monitoring Changes to Data Saver |
| 24 | Preferences</a> |
Adarsh Fernando | 8cdd5e3 | 2016-03-14 13:49:12 -0700 | [diff] [blame] | 25 | </li> |
| 26 | |
| 27 | <li> |
| 28 | <a href="#testing">Testing with Android Debug Bridge Commands</a> |
Adarsh Fernando | ebae30fc | 2016-03-01 11:09:49 -0800 | [diff] [blame] | 29 | </li> |
| 30 | </ol> |
| 31 | </div> |
| 32 | </div> |
| 33 | |
| 34 | <p> |
| 35 | Over the life of a smartphone, the cost of a cellular data plan can easily |
Adarsh Fernando | 1c796b1 | 2016-03-08 17:01:36 -0800 | [diff] [blame] | 36 | exceed the cost of the device itself. In the N Developer Preview, users can |
| 37 | enable Data Saver on a device-wide basis in order to use less data, whether |
| 38 | roaming, near the end of the billing cycle, or on a small prepaid data pack. |
Adarsh Fernando | ebae30fc | 2016-03-01 11:09:49 -0800 | [diff] [blame] | 39 | </p> |
| 40 | |
| 41 | <p> |
| 42 | When a user enables Data Saver in <strong>Settings</strong> and the device is |
| 43 | on a metered network, the system blocks background data usage and signals |
| 44 | apps to use less data in the foreground wherever possible. Users can |
| 45 | whitelist specific apps to allow background metered data usage even when Data |
| 46 | Saver is turned on. |
| 47 | </p> |
| 48 | |
| 49 | <p> |
Adarsh Fernando | 1c796b1 | 2016-03-08 17:01:36 -0800 | [diff] [blame] | 50 | The N Developer Preview extends the {@link android.net.ConnectivityManager} |
| 51 | API to provide apps with a way to <a href="#status">retrieve the user’s Data |
| 52 | Saver preferences</a> and <a href="#monitor-changes">monitor preference |
Adarsh Fernando | ebae30fc | 2016-03-01 11:09:49 -0800 | [diff] [blame] | 53 | changes</a>. It is considered good practice for apps to check whether the |
| 54 | user has enabled Data Saver and make an effort to limit foreground and |
| 55 | background data usage. |
| 56 | </p> |
| 57 | |
Adarsh Fernando | 1c796b1 | 2016-03-08 17:01:36 -0800 | [diff] [blame] | 58 | <h2 id="status"> |
| 59 | Checking Data Saver Preferences |
| 60 | </h2> |
Adarsh Fernando | ebae30fc | 2016-03-01 11:09:49 -0800 | [diff] [blame] | 61 | |
| 62 | <p> |
Adarsh Fernando | 1c796b1 | 2016-03-08 17:01:36 -0800 | [diff] [blame] | 63 | In the N Developer Preview, apps can use the {@link |
Adarsh Fernando | ebae30fc | 2016-03-01 11:09:49 -0800 | [diff] [blame] | 64 | android.net.ConnectivityManager} API to determine what data usage |
| 65 | restrictions are being applied. The {@code getRestrictBackgroundStatus()} |
| 66 | method returns one of the following values: |
| 67 | </p> |
| 68 | |
| 69 | <dl> |
| 70 | <dt> |
| 71 | {@code RESTRICT_BACKGROUND_STATUS_DISABLED} |
| 72 | </dt> |
| 73 | |
| 74 | <dd> |
| 75 | Data Saver is disabled. |
| 76 | </dd> |
| 77 | |
| 78 | <dt> |
| 79 | {@code RESTRICT_BACKGROUND_STATUS_ENABLED} |
| 80 | </dt> |
| 81 | |
| 82 | <dd> |
| 83 | The user has enabled Data Saver for this app. Apps should make an effort to limit data |
| 84 | usage in the foreground and gracefully handle restrictions to background |
| 85 | data usage. |
| 86 | </dd> |
| 87 | |
| 88 | <dt> |
| 89 | {@code RESTRICT_BACKGROUND_STATUS_WHITELISTED} |
| 90 | </dt> |
| 91 | |
| 92 | <dd> |
| 93 | The user has enabled Data Saver but the app is whitelisted. Apps should |
| 94 | still make an effort to limit foreground and background data usage. |
| 95 | </dd> |
| 96 | </dl> |
| 97 | |
| 98 | <p> |
| 99 | It is considered good practice to limit data usage whenever the device is |
| 100 | connected to a metered network, even if Data Saver is disabled or the app |
| 101 | is whitelisted. The following sample code uses {@link |
| 102 | android.net.ConnectivityManager#isActiveNetworkMetered |
| 103 | ConnectivityManager.isActiveNetworkMetered()} and {@code |
| 104 | ConnectivityManager.getRestrictBackgroundStatus()} to determine how much data |
| 105 | the app should use: |
| 106 | </p> |
| 107 | |
| 108 | <pre> |
| 109 | ConnectivityManager connMgr = (ConnectivityManager) |
| 110 | getSystemService(Context.CONNECTIVITY_SERVICE); |
| 111 | // Checks if the device is on a metered network |
| 112 | if (connMgr.isActiveNetworkMetered()) { |
| 113 | // Checks user’s Data Saver settings. |
Adarsh Fernando | 8cdd5e3 | 2016-03-14 13:49:12 -0700 | [diff] [blame] | 114 | switch (connMgr.getRestrictBackgroundStatus()) { |
Adarsh Fernando | ebae30fc | 2016-03-01 11:09:49 -0800 | [diff] [blame] | 115 | case RESTRICT_BACKGROUND_STATUS_ENABLED: |
| 116 | // Background data usage is blocked for this app. Wherever possible, |
| 117 | // the app should also use less data in the foreground. |
| 118 | |
| 119 | case RESTRICT_BACKGROUND_STATUS_WHITELISTED: |
| 120 | // The app is whitelisted. Wherever possible, |
| 121 | // the app should use less data in the foreground and background. |
| 122 | |
| 123 | case RESTRICT_BACKGROUND_STATUS_DISABLED: |
| 124 | // Data Saver is disabled. Since the device is connected to a |
| 125 | // metered network, the app should use less data wherever possible. |
| 126 | } |
| 127 | } else { |
| 128 | // The device is not on a metered network. |
| 129 | // Use data as required to perform syncs, downloads, and updates. |
| 130 | } |
| 131 | </pre> |
| 132 | |
Adarsh Fernando | 2ba8e2a | 2016-05-09 10:24:38 -0700 | [diff] [blame] | 133 | <h3 id="request-whitelist"> |
| 134 | Requesting whitelist permissions |
| 135 | </h3> |
| 136 | |
| 137 | <p> |
| 138 | If your app needs to use data in the background, it can request whitelist |
| 139 | permissions by sending a |
| 140 | <code>Settings.ACTION_IGNORE_BACKGROUND_DATA_RESTRICTIONS_SETTINGS</code> |
Adarsh Fernando | b1386a7 | 2016-05-12 15:18:14 -0700 | [diff] [blame^] | 141 | intent containing a URI of your app's package name: for example, |
| 142 | <code>package:MY_APP_ID</code>. |
Adarsh Fernando | 2ba8e2a | 2016-05-09 10:24:38 -0700 | [diff] [blame] | 143 | </p> |
| 144 | |
| 145 | <p> |
Adarsh Fernando | b1386a7 | 2016-05-12 15:18:14 -0700 | [diff] [blame^] | 146 | Sending the intent and URI launches the <strong>Settings</strong> app and |
| 147 | displays data usage settings for your app. The user can then decide whether |
| 148 | to enable background data for your app. Before you send this intent, it is |
| 149 | good practice to first ask the user if they want to launch the |
| 150 | <strong>Settings</strong> app for the purpose of enabling background data |
| 151 | usage. |
Adarsh Fernando | 2ba8e2a | 2016-05-09 10:24:38 -0700 | [diff] [blame] | 152 | </p> |
| 153 | |
Adarsh Fernando | 1c796b1 | 2016-03-08 17:01:36 -0800 | [diff] [blame] | 154 | <h2 id="monitor-changes"> |
Adarsh Fernando | ebae30fc | 2016-03-01 11:09:49 -0800 | [diff] [blame] | 155 | Monitoring Changes to Data Saver Preferences |
Adarsh Fernando | 1c796b1 | 2016-03-08 17:01:36 -0800 | [diff] [blame] | 156 | </h2> |
Adarsh Fernando | ebae30fc | 2016-03-01 11:09:49 -0800 | [diff] [blame] | 157 | |
| 158 | <p> |
| 159 | Apps can monitor changes to Data Saver preferences by creating a {@link |
| 160 | android.content.BroadcastReceiver} to listen for {@code |
Adarsh Fernando | b1386a7 | 2016-05-12 15:18:14 -0700 | [diff] [blame^] | 161 | ConnectivityManager.ACTION_RESTRICT_BACKGROUND_CHANGED} and dynamically |
| 162 | registering the receiver with {@link android.content.Context#registerReceiver |
Adarsh Fernando | ebae30fc | 2016-03-01 11:09:49 -0800 | [diff] [blame] | 163 | Context.registerReceiver()}. When an app receives this broadcast, it should |
| 164 | <a href="#status">check if the new Data Saver preferences affect its |
| 165 | permissions</a> by calling {@code |
| 166 | ConnectivityManager.getRestrictBackgroundStatus()}. |
| 167 | </p> |
| 168 | |
| 169 | <p class="note"> |
| 170 | <strong>Note:</strong> The system only sends this broadcast to apps that |
| 171 | dynamically register for them with {@link |
| 172 | android.content.Context#registerReceiver Context.registerReceiver()}. Apps |
| 173 | that register to receive this broadcast in their manifest will not receive |
| 174 | them. |
David Friedman | bf31c62 | 2016-03-03 13:55:00 -0800 | [diff] [blame] | 175 | </p> |
Adarsh Fernando | 8cdd5e3 | 2016-03-14 13:49:12 -0700 | [diff] [blame] | 176 | |
| 177 | <h2 id="testing"> |
| 178 | Testing with Android Debug Bridge Commands |
| 179 | </h2> |
| 180 | |
| 181 | The <a href="{@docRoot}tools/help/adb.html">Android Debug Bridge (ADB)</a> |
| 182 | provides a few commands that you can use to check and configure network |
| 183 | permissions: |
| 184 | |
| 185 | <dl> |
| 186 | <dt> |
| 187 | <code>$ adb shell dumpsys netpolicy</code> |
| 188 | </dt> |
| 189 | |
| 190 | <dd> |
| 191 | Generates a report that includes the current global background network |
| 192 | restriction setting, package UIDs currently on a whitelist, and the network |
| 193 | permissions of other known packages. |
| 194 | </dd> |
| 195 | |
| 196 | <dt> |
| 197 | <code>$ adb shell cmd netpolicy</code> |
| 198 | </dt> |
| 199 | |
| 200 | <dd> |
| 201 | Displays a full list of Network Policy Manager (netpolicy) commands. |
| 202 | </dd> |
| 203 | |
| 204 | <dt> |
| 205 | <code>$ adb shell cmd netpolicy set restrict-background |
| 206 | <boolean></code> |
| 207 | </dt> |
| 208 | |
| 209 | <dd> |
| 210 | Enables or disables Data Saver mode when passing <code>true</code> or |
| 211 | <code>false</code>, respectively. |
| 212 | </dd> |
| 213 | |
| 214 | <dt> |
| 215 | <code>$ adb shell cmd netpolicy add restrict-background-whitelist |
| 216 | <UID></code> |
| 217 | </dt> |
| 218 | |
| 219 | <dd> |
| 220 | Adds the specified package UID to the whitelist to allow background metered |
| 221 | data usage. |
| 222 | </dd> |
| 223 | |
| 224 | <dt> |
| 225 | <code>$ adb shell cmd netpolicy remove restrict-background-whitelist |
| 226 | <UID></code> |
| 227 | </dt> |
| 228 | |
| 229 | <dd> |
| 230 | Removes the specified package UID from the whitelist to block background |
| 231 | metered data usage while Data Saver is enabled. |
| 232 | </dd> |
| 233 | </dl> |