AT&T U-verse Enabled How to Use the TV UI API Publication Date: September 9, 2014
Legal Disclaimer This document and the information contained herein (collectively, the "Information") is provided to you (both the individual receiving this document and any legal entity on behalf of which such individual is acting) ("You" and "Your") by AT&T, on behalf of itself and its affiliates ("AT&T") for informational purposes only. AT&T is providing the Information to You because AT&T believes the Information may be useful to You. The Information is provided to You solely on the basis that You will be responsible for making Your own assessments of the Information and are advised to verify all representations, statements and information before using or relying upon any of the Information. Although AT&T has exercised reasonable care in providing the Information to You, AT&T does not warrant the accuracy of the Information and is not responsible for any damages arising from Your use of or reliance upon the Information. You further understand and agree that AT&T in no way represents, and You in no way rely on a belief, that AT&T is providing the Information in accordance with any standard or service (routine, customary or otherwise) related to the consulting, services, hardware or software industries. AT&T DOES NOT WARRANT THAT THE INFORMATION IS ERROR-FREE. AT&T IS PROVIDING THE INFORMATION TO YOU "AS IS" AND "WITH ALL FAULTS." AT&T DOES NOT WARRANT, BY VIRTUE OF THIS DOCUMENT, OR BY ANY COURSE OF PERFORMANCE, COURSE OF DEALING, USAGE OF TRADE OR ANY COLLATERAL DOCUMENT HEREUNDER OR OTHERWISE, AND HEREBY EXPRESSLY DISCLAIMS, ANY REPRESENTATION OR WARRANTY OF ANY KIND WITH RESPECT TO THE INFORMATION, INCLUDING, WITHOUT LIMITATION, ANY REPRESENTATION OR WARRANTY OF DESIGN, PERFORMANCE, MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, OR ANY REPRESENTATION OR WARRANTY THAT THE INFORMATION IS APPLICABLE TO OR INTEROPERABLE WITH ANY SYSTEM, DATA, HARDWARE OR SOFTWARE OF ANY KIND. AT&T DISCLAIMS AND IN NO EVENT SHALL BE LIABLE FOR ANY LOSSES OR DAMAGES OF ANY KIND, WHETHER DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, PUNITIVE, SPECIAL OR EXEMPLARY, INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OF GOODWILL, COVER, TORTIOUS CONDUCT OR OTHER PECUNIARY LOSS, ARISING OUT OF OR IN ANY WAY RELATED TO THE PROVISION, NON-PROVISION, USE OR NON-USE OF THE INFORMATION, EVEN IF AT&T HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSSES OR DAMAGES. i
Table of Tables Contents 1 Introduction... 1 1.1 Additional Resources... 1 2 Overview... 2 3 TV UI API... 2 4 Sample Code... 3 ii
Table of Examples Example 3-1: Using the TV UI API.... 5 iii
1 Introduction This document is an introduction for developers to the TV UI API. Using this API, you are able to create interfaces for your app on the screen attached to the U- verse receiver. This allows a user to interact with your TV UI app on a television connected to a U-verse receiver. This document includes the basics of adding this functionality to your app and creating a page to display on the television, as well as a code sample using the API to display an image on the television screen. 1.1 Additional Resources In addition to this document, you may find the following documents helpful when developing U-verse Enabled ios apps. How to Set Up a U-verse Enabled Project in Xcode How to Write Your First AT&T U-verse Enabled ios App In addition, you can find more technical information on the AT&T Developer Program web site at http://developer.att.com/u-verse. Page 1 of 5
2 Overview The TV UI API allows you to display content from your app onto the screen attached to the U-verse receiver. This allows you to draw content on screen, such as buttons, images, and text, as well as play audio and visual content. In ios this is handled by an object conforming to the uvetvapplicationdelegate protocol. The two methods are used to serve this content: 3 TV UI API The pageforname:withparams:forframe method enables you to create the uvepages that will be used in your app. Each uvepage you create will be a full TV screen of content. Each time a new page is to be drawn on screen in response to a user action, this method is called with the name of the page passed as a parameter. Using this method you create a full uvepage, adding and positioning the UI elements you wish to display on the TV screen, and then return the uvepage object you created. The resourceforname:withparams:forframe method provides the resources used on each uvepage. These can include video and image files. The resourceforname:withparams:forframe method separates the loading of resource elements from the page layout itself, leading to a quicker initial page load. The TV UI API allows you to display content from your app onto the screen attached to the U-verse receiver. This allows you to draw content, such as buttons, images, and text, as well as play audio and visual content, on screen. To add second-screen functionality to your app, you use the uvetvapplicationdelegate protocol. This protocol has four methods: pageforname:withparams:forframe: This is the callback method that your app receives each time that the U-verse receiver displays a page of content on the screen. Use this method to create UVEPage/UVEPanel objects with UVE gadgets, UVE actions, UVE Animations resourceforname:withparams:forframe:this is the callback method that your app receives each time that a page requests a media file, such as images, audio and video. Although you create the object and add it to the page using the pageforname:withparams:forframe method, when the resource is needed the receiver will call this method, passing the URL of the resource as the name argument. The app then returns the resource as NSData for network transmission. applicationserverdidstart: This method is called when the application server is started. After you receive this callback, the app can display a page on the screen. Page 2 of 5
4 Sample Code applicationserverdidfailtostartwitherror: This method is called when the application server fails to start. After you have implemented the methods in the uvetvapplicationdelegate protocol, call starttvapplicationwithdelegate on the SetTopBox object, on which you wish to display the content. The code sample below starts the application server on the engaged receiver, passing the uvetvapplicationdelegate object that contains this sample as the delegate. [[UverseConnectedManagersharedManager].mostRecentlyEngagedSetTopBox starttvapplicationwithdelegate:self]; After you receive the applicationserverdidstart callback, you can call the displaypagewithname method on the SetTopBox object on which you started the application server, passing the name of the page that you wish to display as the argument. [[UverseConnectedManagersharedManager].mostRecentlyEngagedSetTopBox displaypagewithname:@"test"]; After you call displaypagewithname, the object that you passed as the argument to the starttvapplicationwithdelegate method will receive the pageforname:withparams:forframe callback. this callback is received for each page your app displays, you should check the pagename argument and then display the correct content for the requested page. After the call to the pageforname:withparams:forframe callback returns the page to be displayed to the SetTopBox, the callback resourceforname:withparams:forframe is called if any resources need to be loaded on the page. Below is an example with a basic implementation of the TV UI API that displays an image on the screen. This example sends an image to be displayed on the screen that is attached to the receiver. Using the ios initwithnibname:bundle method, this example checks if the application server has been started, and if not it calls the starttvapplicationwithdelegate method to start the application server. Next, in the applicationserverdidstart callback, this example calls the displaypagewithname method to display the page on the screen attached to the U-verse receiver. The U-verse receiver then calls the pageforname:withparams:forframe method. In this example, the method creates and adds the uveimage object to the page, and then returns the page. Finally, when the U-verse receiver is about to the display the image, it calls the resourceforname:withparams:forframe method. There are two important things Page 3 of 5
to consider regarding this method. First, the resourcename argument is the URL of the resource and not the name. Second, this method returns an NSData object, so the source must be wrapped in an NSData object before it is returned. TV UI API 1 @implementation appserverviewcontroller 2 @synthesize associatedstb = _associatedstb; 3 @synthesize page = _page; 4 5 - (id)initwithnibname:(nsstring *)nibnameornil bundle:(nsbundle *)nibbundleornil 6 { 7 self = [super initwithnibname:nibnameornil bundle:nibbundleornil]; 8 if (self) { 9 UverseConnectedManager *uvcmgr = [UverseConnectedManager sharedmanager]; 10 _associatedstb = [UverseConnectedManager sharedmanager].mostrecentlyengagedsettopbox; 11 12 if (uvcmgr.appserverstate!= AppServerStarted){ 13 [_associatedstb starttvapplicationwithdelegate:self]; 14 } 15 } 16 return self; 17 } 18 19 #pragma mark - uvetvapplicationdelegate 20 - (void)applicationserverdidstart{ 21 NSLog(@"applicationServerDidStart"); 22 [self.associatedstb displaypagewithname:@"test"]; 23 } 24 25 - (void)applicationserverdidfailtostartwitherror:(nserror*)error{ 26 NSLog(@"Failed to start Application Server"); } 27 28 -(uvepage *)pageforname:(nsstring *)pagename withparams:(nsmutabledictionary *)params forframe:(cgrect)tvframe 29 { 30 if ([pagename isequaltostring:@"test"]){ 31 self.page = [[uvepage alloc] initpagewithname:@"test"]; 32 CGRect imageframe = CGRectMake(20,20, 300, 200); 33 NSURL *imageurl = [NSURL urlwithstring:@"car.jpg"]; 34 uveimage *image = [[uveimage alloc] initimagewithname:@"image" imageurl:imageurl frame:imageframe]; 35 [self.page addgadget:image]; Page 4 of 5
36 return page; 37 } 38 else { 39 return nil; 40 } 41 } 42 43 - (NSData *)resourceforname:(nsstring*)resourcename withparams:(nsmutabledictionary*)params 44 { 45 if ( [resourcename isequaltostring:@"car.jpg"]){ 46 NSURL imageurl = [NSURL urlwithstring:@"car.jpg"]; 47 return [NSData datawithcontentsofurl:imageurl]; 48 } 49 } 50 @end Example 4-1: Using the TV UI API. Page 5 of 5