Yahoo! Connected TV — Frequently Asked Questions

Here is a list of the most commonly asked questions with their answers. Additional answers, troubleshooting, and testing support for TV Apps are provided through the Connected TV forums at this URL:
http://developer.yahoo.com/forum/Connected TV

Business FAQ

Development FAQ

Distribution FAQ

 

 

 

Business FAQ

Q: Does the platform support DRM?

The DRM services supported by Connected TV devices vary by manufacturer. The Yahoo! Connected TV Platform supports a DRM services interface whose implementation is provided by device partners.

To discuss content protection concerns and acceptable security level options, content providers can contact the Yahoo! Connected TV partner integration team at the following email address: yctvsupport@yahoo-inc.com

 

 

 

Development FAQ

Device Communication

Q: What network connection modes are supported?

The following network connection modes are supported:

  • Connect in Bridged Mode — Make sure that the VM has connectivity by browsing to a web page. Launch the Applications→Yahoo! CTV-ADK→Device Communication Simulator. Launch the Android Connected TV app from Google Play and let it auto-discover the Simulator in the list of available devices on the same local network.

  • Connect in NAT Mode — Follow the same steps as for the Bridged Mode above, except that Network Settings must be configured to forward port 8099 to the VM, otherwise the Android Connected TV app will not be able to discover the Device Communication Simulator on the local network.

Q: How do you handle failure to bind?

Intermittently, the Simulator fails to bind to the Device Communication port. Restart the Simulator to resolve this error. To verify this state, check the log for an "Unable to Bind to Port" error message. Go to the Profile app→System Settings→System Status menu and verify that the Device Communication status is inactive.

Q: How do you create an Application Key?

The unique Application Key provided in the ADK sample code does not work in the production environment. You must create your own developer Application Key through YDN. See the Creating an Application Key section in the Developer Guide.

Q: Where can you find Device Communication example apps?

Device Communication example apps are available on GitHub and installed by the Simulator. You can find source code in the following locations:

  1. App Chat Example — The App Chat Java example opens a connection through the local network with the Yahoo! Connected TV Platform (the "Platform") and starts an instant message command-line dialog with the App Chat TV App.


  2. Simple Navigation Example — The Simple Navigation Java example opens a connection through the local network with the Platform, issues a command to navigate to the right, then closes.


  3. Video List Example — The Video List Java example opens a connection through the local network with the Platform, queries the Video List TV App for a list of videos, then prompts the user to enter a URL.

Networking

Q: Do you support both synchronous and asynchronous calls?

Be sure to fetch data asynchronously from your back-end server as device resources are limited. TV Apps should not make synchronous calls and will not pass the Yahoo! QA process with synchronous calls. Please download the YCTV Acceptance Criteria (.doc or .rtf) for additional requirements.

Example — URL.fetchAsync()

For more detail, see the URL.fetchAsync() online reference. 

var url = new URL();
url.location = "http://www.yahoo.com";
url.fetchAsync(url_done);
function url_done(url){
    print("fetch complete");
    print("response: " + url.response);
    print("result: " + url.result);
}
Example — XMLHttpRequest

For more detail, see the XMLHttpRequest online reference, XPath Support, and the XML DOM API Reference. 

var request = new XMLHttpRequest();
request.onreadystatechange = myStatusProc;
request.open("GET", "http://www.yahoo.com", true);
request.send();

// someplace else
function myStatusProc(){
    if (this.readyState == 4) {
        // complete
        print(this.status);
    }
}

Review the discussions in the YCTV Developer Forums for relevant content: http://developer.yahoo.com/forum/Connected TV

Q: Do you support XML response data (XMLHttpRequest)?

Try to use JSON instead of XML. Parsing large blocks of XML is slow and resource intensive. Avoid using XML on all device platforms. Use JSON for significantly faster performance. See the FAQ on asynchronous calls.

Q: How do you test for network failure?

TV Apps 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 App QA and approval process. To streamline getting your app into the production TV Store, be sure your app 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 app states:
    • Bookmark
    • Sidebar
    • Fullscreen view with TV Passthrough off, if applicable
    • Fullscreen view with TV Passthrough on, if applicable
    • Fullscreen view with streaming video, if applicable

 

Check the Network Status before calling XMLHttpRequest and URL methods

Your app 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 app.

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 app's network request has failed (as set by your app).

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 app 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 app's XMLHttpRequest or URL network request fails, the app should inform the KONtx Framework so that a “no network” icon can be displayed on the app and a "request failed" dialog can be brought up. On a failed network request, the app should call KONtx.application.­setNetworkRequestFailed(true). For each successful network request, the app should set the network status to “connected” by calling KONtx.application.­setNetworkRequestFailed(false). In the example below, the method setNetworkRequestFailed() is wrapped in the myApp namespace (see the section on backward compatibility):

function callAPI(url, callback) {
    if (KONtx.application.isPhysicalNetworkDown()) {
        log("the network is down!");
        return;
    }
    var request = new URL();
    request.callback = callback;
    request.location = url;
    KONtx.utility.WaitIndicator.up();
    request.fetchAsync(function (u) {
        KONtx.utility.WaitIndicator.down();
        if (u.response == 200){
            myApp.application.setNetworkRequestFailed(false);
            u.callback(u.result);
        } else {
            myApp.application.setNetworkRequestFailed(true);
        }
    });
}

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 app. 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 app 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:

EventHandlers.onNetworkHideDialog.subscribeTo(
    KONtx.application, 
    "onNetworkHideDialog", 
    EventHandlers
);

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 app has stale data or is not ready for display, you may want to call event.preventDefault(), for example:

if (event.payload.type == 1) {
    // Check if you have the base data you need to render your main view
    // This would normally be config data which you would fetch at app startup
    // DO NOT fetch data inside this handler, the network is unstable
    if (data_ready == false) {
        event.preventDefault();
    }
}

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 app should succeed. However, use of this event is not recommended. The suggested best practice is to wait until the consumer accesses your app 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.

// Replace myApp with your app's custom object

myApp.network = (function () {
    var setDownByUser = false;
    return {
        setNetworkRequestFailed: function (status) {
            KONtx.application.setNetworkRequestFailed(status);
            setDownByUser = status;
        },
        isPhysicalNetworkDown: function () {
            if (KONtx.application.getNetworkDownStatus) {
                return !setDownByUser;
            }
            return false;
        }
    };
})();

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

if (typeof KONtx.application.isPhysicalNetworkDown === "undefined") {
    KONtx.application.isPhysicalNetworkDown = function () {
        // Replace myApp with your app's custom object
        return myApp.network.isPhysicalNetworkDown();
    };
}

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

function callAPI(url, callback) {
    if (KONtx.application.isPhysicalNetworkDown()) {
        log("the network is down!");
        return;
    }
    var request = new URL();
    request.callback = callback;
    request.location = url;
    KONtx.utility.WaitIndicator.up();
    request.fetchAsync(function (u) {
        KONtx.utility.WaitIndicator.down();
        if (u.response == 200){
            myApp.application.setNetworkRequestFailed(false);
            u.callback(u.result);
        } else {
            myApp.application.setNetworkRequestFailed(true);
        }
    });
}

 

Video / Audio / Media Player

Q: How do you migrate from KONtx.videoplayer to KONtx.mediaplayer?

Refer to the "Migrating to KONtx.mediaplayer" section in the Media Player API Reference.

Q: What video/audio codecs are supported?

To ensure that your TV App’s video works on all supported TVs/devices the following encoding specifications have been verified on all Connected TV devices. Deviating from these recommended video encoding parameters may render the video incompatible with deployed or legacy systems.

Streaming Transport

Progressive download over HTTP is supported. Many encoders have an option to enable Internet streaming where the stream is buffered so that playback starts before the whole clip is fully downloaded.

Some device-specific media players support seeking to particular times inside a piece of media by jumping to a relative or absolute offset. Video-seeking and time index changes require a special version of GStreamer (0.10.23) to test on the Simulator, so typically time index testing occurs on the TV/device. To support stopping at a particular point in a video, the event onTimeIndexChanged fires at one second intervals. Currently none of the devices in production support fast forward and rewind over HTTP streams.

Other supported streaming protocols vary by device. Currently one device partner supports MMS and other device partners will be supporting M3U8 and RTSP late in 2010 and early 2011. Existing devices can support a video playlist of URLs, but do not support a continuous open stream. The Yahoo! Connected TV Platform also supports redirection for the video playlist URLs.

Currently play-listed progressive download is being used for radio apps. HTTP streaming audio is supported through a fullscreen view where you have exclusive access to the audio pipeline. In fullscreen mode, there is no mixing with any other audio signals. You cannot playback audio (or video) from the sidebar view, as it will be mixed with the audio from the TV Channel. Play-listed progressive download is supported by the current Connected TV devices, but a continuous open stream is not supported. The playlist can be a series of audio files, which play one after the other over an HTTP stream. The majority of our platform partners have all specified they are supporting HTTP live streaming protocols in their 2011 devices. Some partners will come out with updated firmware for existing devices as well. Currently our Simulator supports live streaming for your development needs.

Encoding Formats

The following encoding formats have been tested and work across all Connected TV devices:

  • MP4 / H.264 / AAC — Recommended
    • Container: MP4 (mpeg4)
    • Codec: H.264
    • Audio: AAC
  • WMV9 / VC-1 / WMA
    • Container: WMV9
    • Codec: VC-1
    • Audio: WMA

Constant/Variable Bit Rate

Optional. Both Constant Bit Rate (CBR) and Variable Bit Rate (VBR) are supported.

Multiple Video Bitrates

Yahoo! recommends choosing one resolution based on your source video's size, and then encoding your videos in multiple bitrates to support varying connection bandwidth. The KONtx.mediaplayer chooses the best stream given the current connection speed returned from KONtx.speedtest. Support for the following video bitrates is recommended:

  • 300 kbps
  • 700 kbps
  • 1000 kbps
  • 2000 kbps

Audio Bitrate

The recommended audio bitrate is 128 kbps for standard bitrate quality.

Resolution

All devices are HD compatible and have a 16:9 aspect ratio. However, the device's available network bandwidth limits HD resolution to 1280 x 720. PAL resolutions are supported. Depending on your content source, the following pixel resolutions are recommended:

  • 640 x 360 — (medium quality 16:9)
  • 640 x 480 — (medium quality 4:3)
  • 720 x 480 — (high quality)
  • 1280 x 720 — (for HD content only)

B-frames

Optional.

Encoding Passes

Optional.

Frame Rate

Optional. Typical frame rates of 29.97 fps for video-based source material and 23.97 fps for film-based source material are supported.

Q: How do you test video playback?

Video playback behavior and performance in the Simulator are not representative of video playback behavior and performance on a TV/device.

The Simulator uses the video playback software library GStreamer to decode and render video. Typically, the software rendering provided by GStreamer is much slower than hardware optimized rasterization. You may see that the audio and video playback is not in sync. This is not representative of device media player behavior. Detailed specifications for each device’s media player implementation do not yet exist. You can go to http://connectedtv.yahoo.com to find out more about Connected TV devices.

If you have trouble testing video in your TV App please follow these recommended steps:

  1. Use small test files that are less than 20 MB. This is for testing purposes only.
  2. Check to see that all the GStreamer packages are installed. Try setting the following environment variable:
    export KF_GSTREAMER_USE_ALTERNATIVE_PIPELINE=1
  3. Test using the Simulator with the latest KONtx Framework and Simulator (via the Latest Production Simulator menu item from the Applications→Yahoo! CTV-ADK→Latest Production menu).
  4. Update the Simulator and sample apps software when updates are available (via the Latest Production Simulator Update Apps menu item from the Applications→Yahoo! CTV-ADK→Latest Production menu).
  5. Use the MediaPlayerSample app (located in $HOME/YCTV-ADK/YCTV-SIM-Latest/TV/Widgets/) as a template for using the KONtx.mediaplayer API.
  6. Test all video-related code on an actual TV/device. Playback behavior and performance on the Simulator are not representative.
  7. Update the firmware of your TV/device. New features may be supported on new device models, for example US and European models vary in format and feature support.
  8. Test the device's media player using the Simulator Console. Launch the Simulator. Let the dock load. Do not interact with any apps. On the Simulator Console command line, execute the following:
    tv.mediaPlayer.load("http://mycompany.com/test/test.mp4");
    tv.mediaPlayer.play();
    You must run the commands above from a fresh start of the Simulator to avoid an inconsistent state.  If these commands fail there may be a problem with the media player installation.
  9. Test the device's sound server using the Simulator Console. An error message of "Invalid argument" from the gstreamer pipeline may be caused by the sound server. Try setting the sound server to ALSA or PulseAudio instead of auto-detect. Try to playback the stream by entering the following command in the Simulator Console:
    gst-launch playbin uri=http://mycompany.com/test/test.mp4
  10. Test local files. If the stream stalls while buffering it usually indicates an issue with the stream server. In these test cases, store the file locally and use a local uri (for example, file:///noise.mp4).
  11. Test playback through the entire video stream so you can test end-of-stream behavior.
  12. Research existing video playback sample solutions in the YCTV Developer Forums http://developer.yahoo.com/forum/Connected TV

Q: How does video buffering work?

Typically devices cannot buffer more than 100 MB of video. If the video metadata moov atom is at the end of the video, and the video size is larger than the device’s buffer size, the device’s media player will not play the video. Some media players can fetch the video metadata from the end of the file but not all devices support this behavior.

Some encoders, for example Quicktime, have options for Internet streaming which put the video metadata at the front file. For Quicktime, the qt-faststart utility rearranges the top-level atoms by shifting the moov atom from the back of the file to the front, and patches the chunk offsets along the way. This utility only operates on uncompressed moov atoms. To move the metadata to the front of the file run:

qt-faststart original.mov new_file.mov

Q: How do you configure the aspect ratio of the media player?

The default viewport configuration for the media player has the (x,y) position at (0,0) and sets the width and height of the viewport to 1920x1080. To use the default viewport configuration for the media player use the following methods:

KONtx.mediaplayer.setViewportBounds(KONtx.mediaplayer.getDefaultViewportBounds());

The default viewport will stretch 4:3 content during playback on some devices. The video playback on the Simulator is not intended to be an indicator of video playback on the Connected TV device. If you want to configure the aspect ratio of video playback for 4:3 content without stretching you can set the viewport properties as follows: 

var bounds = {
  x: 333,
  y: 333,
  width: 640,
  height: 480
};
KONtx.mediaplayer.setViewportBounds(bounds);

Q: How do you letterbox the video plane?

The graphical plane sits on top of the video plane. To have video playback within a graphical boundary, create a transparent area within your background image.

Q: Do you support streaming audio?

Currently play-listed progressive download is being used for radio apps. HTTP streaming audio is supported through a fullscreen view where you have exclusive access to the audio pipeline. In fullscreen mode, there is no mixing with any other audio signals. You cannot playback audio (or video) from the sidebar view, as it will be mixed with the audio from the TV Channel. Play-listed progressive download is supported by the current Connected TV devices, but a continuous open stream is not supported. The playlist can be a series of audio files, which play one after the other over an HTTP stream. The majority of our platform partners have all specified they are supporting HTTP live streaming protocols in their 2011 devices. Some partners will come out with updated firmware for existing devices as well. Currently our Simulator supports live streaming for your development needs.

Images and Animation

Q: How do you handle image load failure?

To handle image load failure add onError events where you instantiate the image. For example:

var myImage = new KONtx.element.Image({
    src: "Images/960x540/detail/play.png",
    missingSrc: "Images/960x540/missingImage.png",
    events: {
        onLoaded: function(event) {
            // Do something on load of an image, like resize or add a border
        },
        onError: function(event) {
            // Do something on failure to load the image
        }
    }
});

Q: How do you change an image after view creation?

To change an image in an existing view call:

myImage.setSource(newURL);

Q: Do you support animation?

Currently animation is not supported. Many partner platforms do not have enough processing power at this time to support animation. Please let us know your animation requirements and feedback on simplified animation support for Connected TV devices through the developer forum:
http://developer.yahoo.com/forum/Connected TV

Q: Why does the Simulator screen appear black?

When you first launch the Simulator, the screen may appear totally black. Resizing the window (maximizing it and returning it to its regular size) forces a refresh of the background and provides the correct display. This workaround is also valuable when playing video. Pressing the F10 key (BACK) causes video playback to stop, but does not close the video screen. Resizing the window after pressing the F10 key (BACK), forces a refresh of the background and provides the correct display.

User Interface Controls

Q: How do you set up button handlers that access the containing view?

There are two basic approaches to set up button selection handlers that affect or need information from the containing view.

Example — this.getView()

The first method is to get a reference to the view while within the button's scope. 

this.controls.my_button = new KONtx.control.TextButton({
    events: {
        onSelect: function () {
            this.setText('You selected me!');
            var view = this.getView();
            view.controls.other_button.setDisabled(true);
        }
    }
}).appendTo(this);

Example — bindto(this)

You can also bind the method to the view to guarantee that this will reference the view while within the button’s onSelect listener. This method of accessing the view from within a button scope is useful if your onSelect listener operates mostly on items in the view's scope. 

this.controls.my_button = new KONtx.control.TextButton({
    events: {
        onSelect: (function () {
            this.controls.my_button.setText('You selected me!');
            this.controls.other_button.setDisabled(true);
    }).bindTo(this)
  }
}).appendTo(this);

Q: How do you redefine the back button?

The BACK button is integral to the interaction model defined for the app. Changes to the default BACK button behavior should be limited to the following example. If your app moves from Home to View A to View B:

Home→View A→View B

and you do not want the BACK button to go from View B to View A, call the loadView() method when going to View B as follows:

KONtx.application.loadView('view-B', myPersistParams, true);

This call prevents View A from being stored in the view history. An example of this behavior is useful when changing a video player view to a video post roll view. When selecting the BACK button from the post roll view, the consumer should not go back to the player view, but instead, all the way back to the sidebar or detailed view.

Before investing resources in design and development, please send email to yctvsupport@yahoo-inc.com to get approval for this user interface behavior change. In order to pass the YCTV Acceptance Criteria, when you submit your app for production approval, you must outline this "BACK Button Use Case" for testing purposes. Please download the YCTV Acceptance Criteria (.doc and .rtf) for additional requirements.

Q: How do you wrap text properly?

To make text wrap properly based on the width of the container, you need to specify the styles.width property at the same time as setting the wrap property to true. If you add the wrap property and your text object is no longer displayed, check that the styles.width property is set.

Example — Centered, Wrapped, and Truncated

Here is an example of centered, wrapped, and truncated text: 

var descTxt = new KONtx.element.Text({
    label: dataItem.description || ' ', 
    wrap: true, 
    truncation: 'end', 
    styles: { 
        visible: (ss.show_title_description && true) || false, 
        fontSize: '26px', 
        color: '#FFFFFF', 
        textAlign: 'center', 
        width: 584, 
        height: 36, 
        hOffset: 12, 
        vOffset: 70 
    }
}).appendTo(container);

Example — Left-Justified, Wrapped, and Truncated

Here is an example of left-justified, wrapped, and truncated text: 

var descTxt = new KONtx.element.Text({
    label: dataItem.description || ' ',
    wrap: true, 
    truncation: 'end', 
    styles: { 
        visible: (ss.show_title_description && true) || false, 
        fontSize: '26px', 
        color: '#FFFFFF', 
        textAlign: 'left', 
        width: 584, 
        height: 36, 
        hOffset: 12, 
        vOffset: 70 
    } 
}).appendTo(container);

Q: How do you get date/time values on the TV?

Be careful when using JavaScript Date/Time methods which may work on the Simulator but will not work on the TV device. The TV device does not maintain an accurate real time clock and restarts at zero each time the TV is turned on. The method to get the current time is as follows:

var datetime = getRealTime();

The method getRealTime() returns the number of seconds since the epoch. Convert this time from seconds to milliseconds to use the JavaScript Date formatting and conversion methods.

var date = new Date(getRealTime() * 1000);

If the date returned from this function is January 1, 1970, Coordinate Universal Time (UTC), check that your clock has been reset properly.

Q: How do you set up a timer?

Use the Timer class with MessageCenter together to get a callback in your view:

File init.js:

var myTimer = new Timer(); 
myTimer.onTimerFired = function () {
    var beat = getRealTime()*1000; // getRealTime() is provided by the Yahoo! Connected TV Platform
    KONtx.messages.store("TimerTrigger", beat); 
};
myTimer.interval = 10; // in seconds 
myTimer.ticking = true; // kick it off

File myView.js:

var myView = new KONtx.Class({
    initView: function(){ 
        this.registerMessageCenterListenerCallback(this.onBroadcast); 
    }, 
    onBroadcast: function(event){ 
        switch (event.payload.key) { 
            case "TimerTrigger": 
                var currentTime = new Date(event.payload.value); 
                // Your implementation here
                break;
            default:
                break;                  
        } 
    }
});

Q: How do you authenticate an account?

You can login to a remote server account using the KONtx.dialogs class which creates a generic dialog box for username and password text entry. The login dialog box does not automatically handle new account authentication when the profile is switched. You can store authentication information in the currentAppData storage class which stores application data for the active profile.

Example — Generic Login 
// Fetch Login Credentials if they exist
var loginData = currentAppData.get("loginCredentials");
if (loginData === null) { 
    var dialog = new KONtx.dialogs.Login({ 
        title: "Login to my service", 
        message: "To use this functionality, you need to login below", 
        callback: function(result) { 
            var user = result.username; 
            var pwd = result.password; 
            // Verify login
			
            // Store Login Credentials 
            currentAppData.set("loginCredentials", {username: user, password: pwd});
        },
        logo: "Assets/960x540/logo_snippet_65x29.png",

        cancelCallback: function (){
                // Handle user cancels login
        } 
    });
    dialog.show();
}

Q: How do you store Copyright, Terms of Service, and Privacy policies?

Ideally you would pull the Copyright, TOS, and Privacy text on-demand from your web site. If you wish to package the text up, use an XML file in your Contents directory. For example:

File TOS.xml

<?xml version="1.0" encoding="UTF-8"?>
<tos>
<![CDATA[
  I am the TOS, and no character escaping is needed.
  ]]>
</tos>

Then use XMLDOM.parseFile() to read in the XML file in a view:

var TosView = new KONtx.Class({
    title: 'TosView',
    Extends: KONtx.system.SidebarView,
    config: {
        tos_key: 'tos',
    },
    createView: function() {
        this.controls.buttonHeight = KONtx.utility.scale(35);
        this.controls.agree = new KONtx.control.TextButton({ 
            guid: 'agree-button', 
            label: 'I agree',
            styles: { 
                width:this.width/2,
                height: this.controls.buttonHeight,
                vOffset: this.height-this.controls.buttonHeight
            },
            events: {
                onSelect: function(event) {
                    currentAppData.set(this.getView().config.tos_key, "you have seen the tos");
                    KONtx.application.loadView('view-Main', {});
                }
            } 
        }).appendTo(this); 
        this.controls.disagree = new KONtx.control.TextButton({ 
            guid: 'agree-button', 
            label: 'I do not agree',
            styles: { 
                width:this.width/2,
                hOffset: this.width/2,
                height: this.controls.buttonHeight,
                vOffset: this.height-this.controls.buttonHeight
            },
            events: {
                onSelect: function(event) {
                KONtx.HostEventManager.send('exitToDock');
                }
            } 
        }).appendTo(this); 
        this.controls.pageIndicator = new KONtx.control.PageIndicator({
            guid: 'pager', 
            styles: {
                width: this.width,
                height: this.controls.buttonHeight,
                vOffset: this.controls.agree.outerHeight-this.controls.agree.height -this.controls.buttonHeight,
            }
        }).appendTo(this);
        this.controls.content = new KONtx.element.TextGrid({
            guid: 'tos',
            styles: {
                fontFamily: '"Helvetica Neue Regular"',
                fontSize: 12,
                color: '#FFFFFF',
                padding: 5,
                wrap: true,
                width: this.width,
                height: this.height-this.controls.agree.height-this.controls.pageIndicator.height,
            }
        }).appendTo(this).attachAccessories(this.controls.pageIndicator);
    },
    updateView: function() {
        var tos = XMLDOM.parseFile("TOS.xml");
        this.controls.content.setText(tos.documentElement.firstChild.nodeValue);
    }
});

Redirect the view to the TOS if this is the first time opening the app. Save a Boolean value into currentAppData to show that you have read the TOS.

File init.js:

include("Framework/kontx/version/src/all.js");
include("Javascript/views/TosView.js");
include("Javascript/views/snippet.js");
include("Javascript/views/sidebar.js");
include("Javascript/views/settings.js");

KONtx.application.init({
    views: [
        { id: 'view-Main', viewClass: SampleSidebarView },
        { id: 'view-Player', viewClass: SamplePlayerView },
        { id: 'view-Settings', viewClass: SettingsView },
        { id: 'snippet-main', viewClass: SampleSnippetView },
        { id: 'view-Tos', viewClass: TosView },
    ],
    defaultViewId: 'view-Main',
    settingsViewId: 'view-Settings',
});
(function (event) {
    var snippet_id = event.payload.viewId;
    var load_tos = (currentAppData.get('tos')==null)?true:false;
    if (load_tos) {
        event.preventDefault();
        event.stopPropagation();
        KONtx.application.setHostResultToViewId(event, 'view-Tos', {} );
    }
}).subscribeTo( KONtx.application, 'onActivateSnippet' );

Examples and Samples

Q: How do you get more apps in your Simulator dock?

The Simulator has access to only platform and sample apps from the TV Store and does not have access to commercial TV Apps.

The ADK Update Check app in the dock indicates when app updates are available. When an update is available, select the Update Apps menu item for the current Simulator from the Applications→Yahoo! CTV-ADK menu. Both new apps and updates for existing apps are downloaded.

Q: Where can you find media player examples?

Examples for the KONtx.mediaplayer interface can be found in the "Media Player Examples" section of the Media Player API Reference.

Q: Where can you find sample apps?

Sample apps are installed with the WDK. For detailed steps see the section, Extract a Sample TV App to Your Development Directory.

Debugging and Testing

Q: Which version of Ubuntu should you use?

The Simulator has been tested and is supported on the provided Ubuntu 10.04 Linux VMware virtual machine (VM) for Mac OS X and Windows. See the Installation Guide.

Q: How do you debug on the Simulator?

TV App developers can use the Simulator Console to inspect both the Engine and toolbox objects during runtime. When you launch the Simulator, a terminal window running the Simulator Console is also launched. You can type commands into this terminal window.

For a list of debugger commands, see Debugging with the Simulator Console.

Q: How do you debug on the TV?

To debug your app on a TV send a request to a web server, and view the logs. The example below uses the regular log() function when debugging on the Simulator, and sends HTTP requests when debugging on the TV. For production releases this type of logging should be disabled. 

function myLog(s) {
    if (myPlatform.buildConfig == 'beta') {
        var r = new XMLHttpRequest();
        r.onreadystatechange = function() {};
        r.open("GET", "http://mycompany.com/debug?output=" + s, true);
        r.timeout = 10;
        r.send();
    } else {
        log(s);
    }
}

Q: How do you test the remote control using the Simulator?

To test the remote control keys using the Simulator, type the following commands into the Simulator Console. First attach the debugger to your app:

/widgets
/widgets number-of-your-app

/key Up
/key Down
/key Left
/key Right
/key Select
/key Home 

/key Play
/key Pause
/key Stop
/key Rewind
/key Forward

/widgets
/widgets number-of-container-app-one-or-two
/key Red
/key Green 
/key Yellow 
/key Blue

You can also use the Keyboard to Remote Control Mapping table.

 

 

 

Distribution FAQ

Q: How do you initiate the TV App QA process?

The QA process starts when we receive your TV App's completed YCTV Acceptance Criteria Form (download the .doc or the .rtf file).

When you are ready to enter the production QA process, send your completed YCTV Acceptance Criteria document to yctvsupport@yahoo-inc.com. For a complete list of required steps, see this section on Uploading to the TV Store . Yahoo! Connected TV will acknowledge your submission through email and will update you as your TV App moves through the QA process.

Q: Which device partners support the application framework's new media player interface, KONtx.mediaplayer?

The KONtx.mediaplayer interface is implemented in KONtx Framework v1.3 (and above) and is shipped out-of-the-box in all 2010 devices. Older 2009 devices using KONtx v1.2 or KONtx v1.1 will not support TV Apps using the KONtx.mediaplayer interface and its advanced features. These older devices will work with apps using the legacy KONtx.videoplayer interface.

When you submit the YCTV Acceptance Criteria (download the .doc or the .rtf file), you must list the Supported OEMs and identify the platforms on which your TV App should be distributed. If you are submitting a media-based app to Vizio, you must use KONtx.mediaplayer. All OEMs in your Supported OEMs list should support your TV App's use of the media player interface.

Q: Do you require additional QA tests after bug fixes or other changes?

If you fix a bug, or change your TV App's software (or user interface assets) you need to resubmit your TV App to the QA process. You do not need to send a new TV App Acceptance Criteria form unless an update is necessary (for example, new use cases). To resubmit a TV App, send email to yctvsupport@yahoo-inc.com with a description of your changes. If Yahoo! has provided you with a bug list, you need to update the bug list with each bug's resolution and attach it to your email.

Q: How long does it take for an app to get through the approval process?

The shortest path to production is 3 weeks. This occurs when the app developer submits a bug-free app for production release. During this time both Yahoo! and the device partners must pass the app through their QA processes without a bug or issue.

Once Yahoo! QA has been passed, the app developer will be informed that his or her app has met the criteria necessary to move on to device partner QA.

At the end of the device partner QA process, if no launch-gating issues remain, then the app will enter the app release process. TV App developers will receive a minimum of three (3) US business days notice of the pending release of an app.

Q: Who communicates with each device partner?

Yahoo! manages all app submissions and communication with each device partner on behalf of the app developer. Yahoo! reviews the bugs provided by the device partner prior to sending them to you. At this time, all communication is via email with Yahoo! and bug lists are managed in spreadsheet attachments. When resubmitting your app with fixes, you should update your status on each bug using this spreadsheet.

Q: What does Yahoo! QA testing cover?

Yahoo! QA testing covers the following:

  • Installation
  • Interaction/Functionality
  • Media playback (where appropriate)
  • Negative inputs
  • Disconnected network handling

 

The following defects will prevent an app from passing Yahoo! QA on any platform:

  • Failure to meet all the YCTV Acceptance Criteria (download the .doc or the .rtf version).
  • Blank or incomplete loading of bookmark, sidebar, and/or fullscreen views.
  • Inconsistent video playback, including not returning to the sidebar at the end of video playback.
  • Inappropriate messaging when network connectivity fails.
  • Not returning as expected when network connectivity is re-established.
  • Dead-ends in the app interaction resulting in returning to the dock.
  • Inconsistent back button behavior (for example, bread-crumbing and focus).
  • Poor handling of negative inputs (for example, erroneous ids and passwords).

 

The following defects are considered bugs but will not prevent passing Yahoo! QA if an acceptable committed fix-date is received from the app developer:

  • Cosmetic issues.
  • Testing considered excessively outside normal user behavior, such as extraordinarily complex, excessive, or rapid input.
  • Defects discovered on pre-production platforms not otherwise present on production platforms.

 

It is important to note that due to platform differences (such as media player implementations and disconnected network event handling) an app may function correctly on one platform but not on another during QA.

Q: Which TV should you buy?

Yahoo! Connected TV recommends buying the latest 2010 models which support the fastest, most-advanced environments. Follow the Connected TV Developer Forums for device updates and feedback.

Q: How can you speed up the QA process?

Here's a list of tips to speed up the QA process:

  • Test on several TVs, including newer models. For example, test the media player and network connectivity failure on several devices. Be prepared to reproduce bugs on specific devices.
  • Do not include synchronous calls in your TV App. See this FAQ on asynchronous support.
  • Encode your video/audio using these Video Encoding Specifications.
  • Create test cases so you can independently test all the requirements in the YCTV Acceptance Criteria form (download the .doc or the .rtf version).
  • Remove hidden files from your app's folders prior to zipping (for example, remove .thumb, .DS_Store, .svn, and all other non-app files).
  • Submit detailed use cases with the YCTV Acceptance Criteria form to indicate your app's desired behavior (for example, unconventional back button behavior).
  • Provide the appropriate username and passwords for test accounts with your TV App submission.
  • Be sure to contact yctvsupport@yahoo-inc.com if your content is IP filtered to retrieve IP addresses for whitelisting.