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 9 @jd:body 10 11 <div id="tb-wrapper"> 12 <div id="tb"> 13 14 15 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> 28 </div> 29 30 <p> 31 Over the life of a smartphone, the cost of a cellular data plan can easily 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. 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> 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 users Data 50 Saver preferences</a> and <a href="#monitor-changes">monitor preference 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 56 <h2 id="status"> 57 Checking Data Saver Preferences 58 </h2> 59 60 <p> 61 In the N Developer Preview, apps can use the {@link 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 users Data Saver settings. 112 switch (connMgr.getRestrictBackgroundStatus()) { 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 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> 139 intent containing a URI of your app's package name: for example, 140 <code>package:MY_APP_ID</code>. 141 </p> 142 143 <p> 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. 150 </p> 151 152 <h2 id="monitor-changes"> 153 Monitoring Changes to Data Saver Preferences 154 </h2> 155 156 <p> 157 Apps can monitor changes to Data Saver preferences by creating a {@link 158 android.content.BroadcastReceiver} to listen for {@code 159 ConnectivityManager.ACTION_RESTRICT_BACKGROUND_CHANGED} and dynamically 160 registering the receiver with {@link android.content.Context#registerReceiver 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. 173 </p> 174 175 <h2 id="testing"> 176 Testing with Android Debug Bridge Commands 177 </h2> 178 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> 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> 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> 253 </dl> 254
