networking.config API: Add an example to the documentation.

chrome/common/extensions/docs/templates/intros/networking_config.html

+<h2 id="usage">Implementing a Captive Portal Authenticator</h2>
+This API allows an extension to implement an authenticator for captive portals.

[not at google - send to devlin, 2015/03/13 17:55:41]

It's nice to try to use "Extension" not "extension" in docs.

[pneubeck (no reviews), 2015/03/17 10:27:02]

Done.

+The interaction between extension, Chrome OS and the user will be:

[not at google - send to devlin, 2015/03/13 17:55:41]

Try to use oxford commas, i.e. "Extension, Chrome OS, and the user..."

Btw is the correct terminology here "Chrome OS" or just "Chrome"?

[pneubeck (no reviews), 2015/03/17 10:27:02]

it should be fine to use 'Chrome'. As long as the API is restricted to Chrome OS
there is anyways a disclaimer at the top of the page.

[pneubeck (no reviews), 2015/03/17 10:27:02]

Done.

+<ul>

[not at google - send to devlin, 2015/03/13 17:55:41]

Should this be an ordered list?

[pneubeck (no reviews), 2015/03/17 10:27:03]

Semantically these steps happen in order.
I just find the numbers a bit distracting.

Done.

+  <li>Using $(ref:setNetworkFilter), the extension registers for a list of Wi-Fi
+  networks that it wants to handle captive portals on.</li>
+  <li>If one of these networks is detected by Chrome OS, it will appear in the
+  network list, badged with an icon to indicate that a captive portal handler is

[not at google - send to devlin, 2015/03/13 17:55:40]

"badged with an icon" --> "badged with your Extension's icon".

[pneubeck (no reviews), 2015/03/17 10:27:03]

As this highly debated about, I would not want to over-specify this (at least
until this stabilized more).
Also, the current implementation indeed uses a fixed icon and not the
extension's one.

+  available.</li>
+  <li>If the user initiates a connection to such a network, Chrome OS will
+  connect as usual.</li>

[not at google - send to devlin, 2015/03/13 17:55:40]

I find this point confusing, what does "as usual" mean? And it seems to
contradict the next points. Perhaps it should be left out, then change the next
2 points to be:

<li>If the user selects such a network, but a captive portal is not detected,
Chrome will connect as usual - the extension will never be involved.
<li>Otherwise, if a captive portal is detected, the user is notified....

[pneubeck (no reviews), 2015/03/17 10:27:02]

Done.

+  <li>If Chrome OS does not detect a captive portal, it will continue without
+  interacting with the extension.</li>
+  <li>If a captive portal is detected, the user is notified and asked whether
+  he wants to authenticate using the registered extension or whether he wants

[not at google - send to devlin, 2015/03/13 17:55:40]

Avoid gender specific pronouns. In this case, you could rephrase this point
like:

"If a captive portal is detected, the user is notified and asked to authenticate
using the registered extension, or whether to visit the captive portal page."

[pneubeck (no reviews), 2015/03/17 10:27:02]

Done.

+  to visit the captive portal page.</li>
+  <li>If he selects the extension, Chrome OS notifies the extension through
+  the $(ref:onCaptivePortalDetected) event.</li>

[not at google - send to devlin, 2015/03/13 17:55:40]

and:

"If the user selects the extension..."

[pneubeck (no reviews), 2015/03/17 10:27:02]

Done.

+  <li>The extension starts now any user interaction and network communication
+  that is required to authenticate at the captive portal. For that, other APIs
+  can be used as well.</li>

[not at google - send to devlin, 2015/03/13 17:55:40]

I don't understand this point, perhaps it needs to be reworded a bit.

[pneubeck (no reviews), 2015/03/17 10:27:02]

Done.

+  <li>Once the extension finished the authentication, it notifies the API using
+  $(ref:finishAuthentication) about its success or failure.</li>
+</ul>
+

[not at google - send to devlin, 2015/03/13 17:55:41]

It would helpful to include a few screenshots in here.

+<p>
+In the extension, this can look similar to the following snippet:
+</p>
+
+<pre data-filename="background.js">
+var myNetworks = [
+  { Type: 'WiFi', SSID: 'MyHotSpot-1' },
+  { Type: 'WiFi', SSID: 'MyHotSpot-2' }
+];
+
+chrome.networking.config.setNetworkFilter(myNetworks, function() {
+    if (chrome.runtime.lastError) {
+        // Handle Error
+    }
+});
+
+chrome.networking.config.onCaptivePortalDetected.addListener(
+  function(networkInfo) {
+    var guid = networkInfo.GUID;
+
+    // Check at first whether we really care about this network.
+    // This can look at additional network properties like BSSID that are not
+    // supported in the filter.
+    if (isBadNetwork(networkInfo)) {
+      chrome.networking.config.finishAuthentication(guid, 'unhandled');
+      return;
+    }
+    checkForMyCaptivePortalServer(function(serverStatus) {
+      if (serverStatus == 'not-detected') {
+        chrome.networking.config.finishAuthentication(guid, 'unhandled');
+        return;
+      }
+      if (serverStatus == 'error') {
+        chrome.networking.config.finishAuthentication(guid, 'failed');
+        return;
+      }
+
+      // If required, interact with the user. E.g. to register him on first

[not at google - send to devlin, 2015/03/13 17:55:40]

s/him/them/

[pneubeck (no reviews), 2015/03/17 10:27:02]

Done.

+      // usage. On subsequent authentications, cached credentials could be used.
+      ShowUIToRegisterUser(continueAuthentication.bind(null, guid));
+    });
+});
+
+function continueAuthentication(guid, credentials) {
+  if (!credentials) {
+    chrome.networking.config.finishAuthentication(guid, 'failed');
+  }
+  AuthenticateToMyCaptivePortalServer(credentials, function(success) {
+    chrome.networking.config.finishAuthentication(
+        guid, success ? 'succeeded' : 'rejected');
+  });
+}
+</pre>