Transcription
AT&T U-verse EnabledHow to Set Up a U-verse Enabled Project in Xcode Publication Date: September 9, 2014 2014 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.
Legal DisclaimerThis document and the information contained herein (collectively, the "Information") is provided to you (both the individual receivingthis document and any legal entity on behalf of which such individual is acting) ("You" and "Your") by AT&T, on behalf of itself andits affiliates ("AT&T") for informational purposes only. AT&T is providing the Information to You because AT&T believes theInformation may be useful to You. The Information is provided to You solely on the basis that You will be responsible for makingYour own assessments of the Information and are advised to verify all representations, statements and information before usin g orrelying upon any of the Information. Although AT&T has exercised reasonable care in providing the Information to You, AT&T doesnot warrant the accuracy of the Information and is not responsible for any damages arising from Your use of or reliance upon theInformation. You further understand and agree that AT&T in no way represents, and You in no way rely on a belief, that AT&T isproviding 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 OFPERFORMANCE, COURSE OF DEALING, USAGE OF TRADE OR ANY COLLATERAL DOCUMENT HEREUNDER OROTHERWISE, AND HEREBY EXPRESSLY DISCLAIMS, ANY REPRESENTATION OR WARRANTY OF ANY KIND WITHRESPECT TO THE INFORMATION, INCLUDING, WITHOUT LIMITATION, ANY REPRESENTATION OR WARRANTY OFDESIGN, PERFORMANCE, MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ORANY REPRESENTATION OR WARRANTY THAT THE INFORMATION IS APPLICABLE TO OR INTEROPERABLE WITH ANYSYSTEM, DATA, HARDWARE OR SOFTWARE OF ANY KIND. AT&T DISCLAIMS AND IN NO EVENT SHALL BE LIABLE FORANY LOSSES OR DAMAGES OF ANY KIND, WHETHER DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, PUNITIVE,SPECIAL OR EXEMPLARY, INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESSINTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OF GOODWILL, COVER, TORTIOUS CONDUCT OR OTHERPECUNIARY LOSS, ARISING OUT OF OR IN ANY WAY RELATED TO THE PROVISION, NON-PROVISION, USE OR NON-USEOF THE INFORMATION, EVEN IF AT&T HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSSES OR DAMAGES. 2014 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.i
Table of ContentsContents1Introduction . 11.1Additional Resources. 11.1Defined Terms. 12About the AAP Bundle . 33Setting up a U-verse Enabled Project in Xcode . 54Conclusion . 9 2014 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.ii
Table of FiguresFigure 3-1: Other Linker Flags settings on the Build Settings screen. . 5Figure 3-2: Link Binary With Libraries list. . 6 2014 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.iii
Table of ExamplesExample 3-1: Environment Constants. . 7Example 3-2: Environment Code Sample. . 8 2014 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.iv
1 IntroductionBefore you can write your first iOS app using the U-verse Enabled SDK, youneed to be familiar with how to setup a U-verse Enabled project.The prerequisites for any U-verse Enabled project are: An Application Authentication Package (AAP) bundle. A U-verse receiver configured for the development with the U-verse EnabledDeveloper Test Channel (9315) in the channel lineup.The document How to Register and Start Developing U-verse EnabledApplications, covers the process for applying for an AAP and requesting the Uverse Enabled Developer Test Channel.All apps must be submitted for AT&T Quality Engineering Testing. For moredetails on the expectations and testing criteria of a U-verse Enabled App, pleaseview the AT&T U-verse Enabled Developer Guidelines, and the document Uverse Enabled Mobile Application Security. For more details of the process ofsubmitting your application for Quality Engineering Testing, see Submit AT&T Uverse Enabled Apps on the AT&T Developer Program website.This document describes how to set up a U-verse Enabled project in Xcode, theiOS development environment, and is intended for developers with experiencewith Objective-C, the Cocoa Touch frameworks and Xcode. You will findinstructions on configuring your project, adding the necessary frameworks and Uverse libraries, and incorporating the AAP bundle.1.1 Additional ResourcesIn addition to this document, you may find the following documents helpful whendeveloping U-verse Enabled iOS apps: How to Register and Start Developing for U-verse Enabled How to Write Your First AT&T U-verse Enabled iOS AppYou can find these documents, as well as other technical information in theDevelop AT&T U-verse Enabled iOS Apps section of the AT&T DeveloperProgram web site.1.1 Defined TermsThe following terms are used in the U-verse Enabled documentation: AAP: The Application Authentication Package (AAP) is used to authenticateeach app with AT&T before the app is allowed to engage a receiver. 2014 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.Page 1 of 9
AAP Developer Key: The AAP Developer Key is a shared security secret thatis combined with the AAP to validate the source of the app. The AAPdeveloper key applies to a specific app ID, regardless of version. Associate/Association: An association is a durable relationship that isestablished between a device and a receiver through the My EnabledDevices channel/interface. An association must be present between a deviceand a receiver in order for an app on the device to engage the receiver. Disabled (Closed) Mode: A receiver mode where no devices may beassociated. Default (Open) Mode: A receiver mode where all devices are implicitlyassociated. Engage, Engagement: A short-term relationship between an app and a Uverse receiver, during which the app may use the U-verse Enabledapplication programming interface (API) to send commands to the receiverand retrieve information from the receiver. Custom (Managed) Mode: A receiver mode where only devices that havepreviously associated with a PIN code are allowed to associate. Receiver (set-top box): Receiver is the term for a U-verse set-top box thatenables the user to watch and record AT&T U-verse programming. U-verse Enabled Control Panel: The Control Panel in the U-verse EnabledOnboarding Tool includes the U-verse Enabled web content, SDK, supportprocesses, and development environments that are available to a registereddeveloper for development, testing, and deployment of U-verse Enabledapps. U-verse Enabled Network Service: This service provides the multiple supportfunctions necessary for a U-verse Enabled app to run in a U-verseenvironment, including verification of the app version and certificate. 2014 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.Page 2 of 9
2 About the AAP BundleThe AAP bundle contains resource files including your AAP resource file andyour Developer Key, which are necessary to authenticate your app with a Uverse receiver. The Developer Key is a shared secret and should be kept private.The resource file in the AAP bundle will differ depending on whether your app iscertified for a development or production environment: ZDEV – This is a test environment for your application, which can beaccessed through the developer channel U-verse Enabled Developer TestChannel (9315). If you have a consumer U-verse account, you can apply tohave this channel enabled on your U-verse receiver through the U-verseEnabled Onboarding Tool. For more details, see the document, How toRegister and Start Developing for U-verse Enabled. The AAP bundle willcontain the environment name zdevca. Production: This AAP bundle is issued after your app completes AT&TQuality Engineering testing. You must submit every version update of yourapp to AT&T for testing before the updated version is approved to run in theproduction environment. The production AAP bundle will contain theenvironment name prodca.You must use the correct AAP bundle for each environment. Using the wrongAAP bundle will cause authentication to fail during Discovery with an internal Uverse error code 3000.After you submit your app information using the U-verse Enabled OnboardingTool, your development resource files will be uploaded and available to downloadfrom the U-verse Enabled Onboarding Tool. After your app passes AT&T QualityEngineering Testing, your production resource files will then be uploaded andavailable to download from the U-verse Enabled Onboarding Tool.Note: Version 5.0 and later of the U-verse Enabled SDK use a new version of theAAP bundle. This new version of the AAP bundle is not compatible with earlierversions of the U-verse Enabled SDK. However, the existing AAP bundles willcontinue to function with apps which are built using the 3.2 version of the U-verseEnabled SDK and earlier. An updated bundle is created when you create orupdate an app and select version 5.0 of the U-verse Enabled SDK in the U-verseEnabled onboarding tool. The updated AAP bundle is valid for ten years, animprovement over the previous bundle’s two years.The same AAP files can be used in new versions of an app. However, all newversions of the app must undergo AT&T Quality Engineering testing before a newversion may run in production and the new version number must be registeredwith AT&T through the U-verse Enabled Onboarding Tool. More information onthe submission process, see the Submit AT&T U-verse Enabled Apps page. 2014 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.Page 3 of 9
Test AAP bundles (ZDEV) do not include version checking, and the versionnumber can be changed during development. In the production environment, theversion number is checked and the CFBundleShortVersionString (the Xcodebuild number) must exactly match the version number registered in the U-verseEnabled Onboarding Tool.The AAP bundle file name ends with the extension .resource, and the developerkey file name ends with the extension .satoken. Both file names are prefixed withthe application bundle identifier, version number, and the environment that thefiles are issued for. For example, files for an app named “ExampleTestApp”version 1.0 in a test environment would be in the bundle“com.example.ExampleTestApp”, and the file names will e” n”.When a U-verse receiver has two different U-verse Enabled environments, thereceiver will attempt to authenticate your app with the environment that was lastused. This means that if you’re using a ZDEV AAP bundle, engagement will failunless you tune the receiver to the U-verse Enabled Developer Test Channel(9315) and relaunch your app. Likewise, tune to the U-verse Enabled channel(9301) and relaunch your app if you’re using the production AAP bundle. 2014 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.Page 4 of 9
3 Setting up a U-verse Enabled Project in XcodeFollow these steps to set up a U-verse Enabled iOS project in Xcode:1. Create a new project in Xcode using any of its default templates.2. Link to the U-verse Enabled Library:i.Click the name of your app in the “Targets” list and click the “BuildSettings” tab.ii.Scroll down to the “Linking” section. If you are unable to see thelinking section, change the view from “Basic” to “All” at the top of the“Build Settings” list.iii.Change the setting to the right of “Other Linker Flags” to “–ObjC”.The following figure shows the “Other Linker Flags” section of the “BuildSettings” screen.Figure 3-1: Other Linker Flags settings on the Build Settings screen.3. Add the necessary frameworks to the project: 2014 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.Page 5 of 9
i.Click the name of your app in the “Targets” list and click the “BuildPhases” tab.ii.Expand the “Link Binary With Libraries” section.iii.At the bottom of the section, click the “ ” symbol.iv.Add the following frameworks: SystemConfiguration.framework Security.framework CFNetwork.framework CoreTelephony.frameworkFigure 3-2: Link Binary With Libraries list.4. Add the static library and the header files to the project. These files are partof the U-verse Enabled SDK you downloaded. To add them, open the foldercontaining the files in the Finder, and drag-and-drop them into your Xcodeproject window. The current version of the U-verse Enabled SDK for iOS isdistributed in two separate libraries, the main library and the TV UI APIlibrary. The main library is critical for every U-verse Enabled app. The mainlibrary is responsible for the discovery and engagement of U-verse receivers,and contains the commands used to implement remote control features,tuning to full screen video and requesting information about the currentprogram and channel. The TV UI API library is distributed as an add-onlibrary, and contains the API for creating U-verse Enabled apps where you 2014 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.Page 6 of 9
can draw your content on the user’s U-verse television screen. All U-verseEnabled apps must include the main library in their U-verse project, whileapps using the TV UI API will need to include both libraries.5. Import the AAP bundle into your project by unzipping the ZIP file anddragging the folder into your Xcode project window.6. Choose the correct SERVER URL for the project in your code, as in Example3-1 below.The SERVER URL is dependent upon which U-verse Enabled networkserver you are connecting to: https://zdais.iac.asp.att.net/dais/ – Use this URL if you using the U-verseEnabled Developer Test Channel. This environment is also known as theZDEV environment. https://dais.iac.asp.att.net/dais/ – The production server URL.If you use the wrong SERVER URL, attempts to run your app will fail andyou will receive a 3001 error (”Zeus Network Error”).7. Set the environment to use the appropriate AAP bundle and SERVER URL.In this example, the filenames have been shortened to just be theenvironment and type, such as “zdevca.satoken” for the zdev developer key.Place the following code at the top of the appDelegate class:Defined Environment Constants1234567891011121314151617 //#define PRODUCTION 1//#define ZDEV 1#ifdef PRODUCTION#define SERVER URL @" https://dais.iac.asp.att.net/dais/ "#define AAP RESOURCE FILE @"prodca.resource"#define AAP DEVELOPER KEY @"prodca.satoken"#elif defined ZDEV#define SERVER URL @" https://zdais.iac.asp.att.net/dais/ "#define AAP RESOURCE FILE @"zdevca.resource"#define AAP DEVELOPER KEY @"zdevca.satoken"#endifExample 3-1: Environment Constants. 2014 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.Page 7 of 9
The following code has been designed to allow you to easily change theenvironment in your project using the constants defined above.Add the following code to the ange Environments1 2 3 45 NSURL *url [[NSBundle mainBundle]URLForResource:AAP DEVELOPER KEY withExtension:nil];NSString *sharedSecret [NSString coding error:NULL];[mgr.userInfo rKey];mgr.fileNameAAP AAP RESOURCE FILE;mgr.overrideURL SERVER URL;Example 3-2: Environment Code Sample.You can also load only the AAP bundle specific to the environment you areusing, then use the files and values in that bundle. However, the above method isrecommended because it enables you to easily change the environment whenrequired.When you submit your app to AT&T for compliance testing, you must build it forthe ZDEV environment. After your app passes the testing process, you mustrebuild the app with the production AAP for submission to the Apple App Store .As part of your Developer agreement with AT&T, the only allowed changebetween these builds is the AAP bundle you use for each environment. Any otherchanges to the code could lead to your apps being blocked from running in theU-verse Enabled production environments. 2014 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.Page 8 of 9
4 ConclusionThe setup procedure described in this document is the same for any U-verseEnabled project. If this is your first project, you should also see the document,How to Write Your First AT&T U-verse Enabled iOS App. That documentdemonstrates the process of writing a basic U-verse Enabled remote control app,including the process of engaging with a U-verse receiver. 2014 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.Page 9 of 9
Developer Test Channel (9315) in the channel lineup. The document How to Register and Start Developing U-verse Enabled Applications, covers the process for applying for an AAP and requesting the U-verse Enabled Developer Test Channel. All apps must be sub
