June 28th, 2010 09:00 AM

Handling the Network Disconnected State

Widgets need to detect changes in network availability and support both offline and online modes as appropriate. Testing for the “Network Disconnected” state is part of the TV Widget QA and approval process. To streamline getting your widget into the production widget gallery, be sure your widget properly handles the following disconnected states:

1. Disconnect and reconnect WAN cable from router
   • causes loss of connectivity but retains IP address
2. Disconnect and reconnect LAN cable from router
   • causes loss of connectivity and loss of IP address
3. Perform Use Case 1 and Use Case 2 above in the following widget states:
   1. Snippet
   2. Sidebar
   3. Fullscreen view with TV Passthrough off, if applicable
   4. Fullscreen view with TV Passthrough on, if applicable
   5. Fullscreen view with streaming video, if applicable

Check the Network Status before calling XMLHttpRequest and URL methods

Your widget should never initiate an XMLHttpRequest or URL request when the physical network is down. You should use the KONtx.application.­­isPhysicalNetworkDown() method in tandem with the KONtx.­application.getNetworkDownStatus accessor method to differentiate between the physical network being down and a request error (from XMLHttpRequest or URL methods) set by the widget.

KONtx.application.isPhysicalNetworkDown()

In KONtx Framework v1.3.18 and above the KONtx.application.­isPhysicalNetworkDown() method has been added to check if the physical network is disconnected.

• If KONtx.application.­isPhysicalNetworkDown() returns true, the network is down and you should not make the request.
• If KONtx.application.­isPhysicalNetworkDown() returns false, it is safe to make the request.

When the KONtx Framework detects that the physical network is down, a “physical disconnect” dialog is displayed.

KONtx.application.getNetworkDownStatus

The legacy accessor method KONtx.application.­getNetworkDownStatus is true when the network is disconnected or when your widget’s network request has failed (as set by your widget).

The KONtx.application.isPhysicalNetworkDown() method only checks the status of the physical network. If this returns false, we know that the physical network is up, and it’s safe to send out an XMLHttpRequest or URL request, even if the current value of KONtx.application.­getNetworkDownStatus is true. When the new request succeeds, the widget should clear the request error by calling KONtx.application.­setNetworkRequestFailed(false) in the request interface.

Set the Network Status when a Network Request Fails

If your widget’s XMLHttpRequest or URL network request fails, the widget should inform the KONtx Framework so that a “no network” icon can be displayed on the widget and a “request failed” dialog can be brought up. On a failed network request, the widget should call KONtx.application.­setNetworkRequestFailed(true). For each successful network request, the widget should set the network status to “connected” by calling KONtx.application.­setNetworkRequestFailed(false). In the example below, the method setNetworkRequestFailed() is wrapped in the myWidget namespace (see the section on backward compatibility):

Handle the onNetworkHideDialog Event

The onNetworkHideDialog event allows you to have more control over what happens when network connectivity is restored. This event is fired when the KONtx Framework detects that the network issue is resolved.

The default behavior for this event is to auto-hide the “no network” dialog box and to return to the currently displayed widget. If you prevent the default behavior from happening, the dialog box will not be auto-hidden, and the consumer is forced to dismiss the dialog and returned to the widget dock.

To change the default action, you can implement custom behavior in the event handler. To handle the onNetworkHideDialog event fired by the KONtx.application class, subscribe to it in your init.js file—for example:

If the onNetworkHideDialog event’s property event.payload.type is equal to 1, the dialog about to be hidden is a “physical disconnect” dialog. If event.payload.type is equal to 2, the dialog is a “request failed” dialog.

Do not fetch data inside the onNetworkHideDialog handler as the network may be unstable. If the KONtx Framework is displaying a “physical disconnect” dialog, and your widget has stale data or is not ready for display, you may want to call event.preventDefault(), for example:

The onNetworkConnectionReconnect event is fired when the network’s physical connection is restored and stays stable for 60 seconds or more. If you subscribe to this event, subsequent network requests made by the widget should succeed. However, use of this event is not recommended. The suggested best practice is to wait until the consumer accesses your widget from the dock before firing new requests after a network reconnection.

Support Backward-Compatibility with other KONtx Framework versions

To be backward-compatible with older versions of the KONtx Framework, Yahoo! recommends you follow these steps:

1. Create a custom object to set the network down status.

2. Use a wrapper to test for the method’s existence. Define this wrapper in init.js or someplace parsed once at runtime.

3. Set the network down status when your XMLHttpRequest() or URL() requests fail. On a failed network request the widget should call KONtx.­application.setNetworkRequestFailed(true). For each successful network request the widget should set the network status to “connected” by calling KONtx.application.­setNetworkRequestFailed(false).

---

To see additional networking examples go to the Development FAQ→Networking section.

Please also search for networking posts in the Connected TV Developer forums: http://developer.yahoo.net/forum/?showforum=91

3 Responses to “Handling the Network Disconnected State”

1. Dolores Ximines says:

   March 23, 2011 at 11:33 pm

   I’ll right away grab your rss feed as I can not find your e-mail subscription link or e-newsletter service. Do you’ve any? Please let me know so that I could subscribe. Thanks.
2. Aracely Brant says:

   April 13, 2011 at 8:40 am

   I really enjoyed Handling the Network Disconnected State Yahoo! Connected TV. I found your weblog site on google and check a number of of your early posts. Proceed to keep up the very good operate. I simply extra up your RSS feed to my MSN Information Reader. In search of forward to studying more from you in a while!… Agile Marketing Solutions, LLC 2905 East Point Street, Suite 91784, Atlanta, GA 30344 (404) 939-5631
3. BREEN says:

   May 29, 2011 at 9:02 pm

   Create ones own LONG URL!! with this easy to practice instructions, you’ll find the greatest collection of url/domain scripts on line.