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