AT&T U-verse® Enabled How to Use the TV UI API in iOS Apps Publication Date: November 1st, 2013 © 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property. 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. IOS is a trademark or registered trademark of Cisco in the U.S. and other countries. © 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property. i Table of Tables Contents 1 Introduction .......................................................................................................................................... 1 1.1 Additional Resources .................................................................................................................... 1 2 TV UI API................................................................................................................................................ 2 3 Sample Code ......................................................................................................................................... 3 © 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property. ii Table of Examples Example 2-1: Using theTV UI API .................................................................................................................. 4 © 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property. 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 Uverse 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 Setup 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. See Develop AT&T U-verse ® Enabled Apps and select the development platform that you are interested in. © 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property. Page 1 of 4 2 TV UI API 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 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.  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. © 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property. Page 2 of 4 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. 3 Sample Code 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 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 2 3 4 5 | | | | | 6 7 | | 8 9 | | 10 | 11 12 13 14 | | | | @implementation appServerViewController @synthesize associatedSTB = _associatedSTB; @synthesize page = _page; - (id)initWithNibName:(NSString *)nibNameOrNil bundle:(NSBundle *)nibBundleOrNil { self = [super initWithNibName:nibNameOrNil bundle:nibBundleOrNil]; if (self) { UverseConnectedManager *uvcMgr = [UverseConnectedManager sharedManager]; _associatedSTB = [UverseConnectedManager sharedManager].mostRecentlyEngagedSetTopBox; if (uvcMgr.appServerState != AppServerStarted){ [_associatedSTB startTVApplicationWithDelegate:self]; } © 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property. Page 3 of 4 15 16 17 18 19 20 21 22 23 24 25 26 | | | | | | | | | | | | 27 28 | | -(uvePage *)pageForName:(NSString *)pageName withParams:(NSMutableDictionary *)params forFrame:(CGRect)tvFrame | { | if ([pageName isEqualToString:@"test"]){ | self.page = [[uvePage alloc] initPageWithName:@"test"]; | CGRect imageFrame = CGRectMake(20,20, 300, 200); | NSURL *imageURL = [NSURL urlWithString:@"car.jpg"]; | uveimage *image = [[uveImage alloc] initImageWithName:@"image" imageURL:imageURL frame:imageFrame]; | [self.page addGadget:image]; | return page; | } | else { | return nil; | } | } | | - (NSData *)resourceForName:(NSString*)resourceName withParams:(NSMutableDictionary*)params | { | if ( [resourceName isEqualToString:@"car.jpg"]){ | NSURL imageURL = [NSURL urlWithString:@"car.jpg"]; | return [NSData dataWithContentsOfURL:imageURL]; | } | } | @end 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 } return self; } #pragma mark - uveTVApplicationDelegate - (void)applicationServerDidStart{ NSLog(@"applicationServerDidStart"); [self.associatedSTB displayPageWithName:@"test"]; } - (void)applicationServerDidFailToStartWithError:(NSError*)error{ NSLog(@"Failed to start Application Server"); } Example 3-1. Using the TV UI API © 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property. Page 4 of 4