© 2014 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.
AT&T U-verse® Enabled
How to Set Up a U-verse Enabled Project in Xcode®
Publication Date: September 9, 2014
Legal Disclaimer
© 2014 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.
i
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 consult ing,
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.
Table of Contents
© 2014 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.
ii
Contents
1 Introduction .................................................................................................................................... 1
1.1 Additional Resources ................................................................................................................ 1
1.1 Defined Terms .......................................................................................................................... 1
2 About the AAP Bundle ..................................................................................................................... 3
3 Setting up a U-verse Enabled Project in Xcode ................................................................................. 5
4 Conclusion ....................................................................................................................................... 9
Table of Figures
© 2014 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.
iii
Figure 3-1: Other Linker Flags settings on the Build Settings screen. ........................................................ 5
Figure 3-2: Link Binary With Libraries list. ................................................................................................ 6
Table of Examples
© 2014 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.
iv
Example 3-1: Environment Constants. ..................................................................................................... 7
Example 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.
Page 1 of 9
1 Introduction
Before you can write your first iOS® app using the U-verse Enabled SDK, you need 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 Enabled 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 submitted for AT&T Quality Engineering Testing. For more details on the expectations and testing criteria of a U-verse Enabled App, please view the AT&T U-verse Enabled Developer Guidelines, and the document U-verse Enabled Mobile Application Security. For more details of the process of submitting your application for Quality Engineering Testing, see Submit AT&T U-verse Enabled Apps on the AT&T Developer Program website.
This document describes how to set up a U-verse Enabled project in Xcode, the iOS development environment, and is intended for developers with experience with Objective-C, the Cocoa Touch frameworks and Xcode. You will find instructions on configuring your project, adding the necessary frameworks and U-verse libraries, and incorporating the AAP bundle.
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 Register and Start Developing for U-verse Enabled
How to Write Your First AT&T U-verse Enabled iOS App
You can find these documents, as well as other technical information in the Develop AT&T U-verse ® Enabled iOS Apps section of the AT&T Developer Program web site.
1.1 Defined Terms
The following terms are used in the U-verse Enabled documentation:
AAP: The Application Authentication Package (AAP) is used to authenticate each 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 2 of 9
AAP Developer Key: The AAP Developer Key is a shared security secret that is combined with the AAP to validate the source of the app. The AAP developer key applies to a specific app ID, regardless of version.
Associate/Association: An association is a durable relationship that is established between a device and a receiver through the My Enabled Devices channel/interface. An association must be present between a device and a receiver in order for an app on the device to engage the receiver.
Disabled (Closed) Mode: A receiver mode where no devices may be associated.
Default (Open) Mode: A receiver mode where all devices are implicitly associated.
Engage, Engagement: A short-term relationship between an app and a U-verse receiver, during which the app may use the U-verse Enabled application programming interface (API) to send commands to the receiver and retrieve information from the receiver.
Custom (Managed) Mode: A receiver mode where only devices that have previously associated with a PIN code are allowed to associate.
Receiver (set-top box): Receiver is the term for a U-verse set-top box that enables the user to watch and record AT&T U-verse programming.
U-verse Enabled Control Panel: The Control Panel in the U-verse Enabled Onboarding Tool includes the U-verse Enabled web content, SDK, support processes, and development environments that are available to a registered developer for development, testing, and deployment of U-verse Enabled apps.
U-verse Enabled Network Service: This service provides the multiple support functions necessary for a U-verse Enabled app to run in a U-verse environment, 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 3 of 9
2 About the AAP Bundle
The AAP bundle contains resource files including your AAP resource file and your Developer Key, which are necessary to authenticate your app with a U-verse 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 is certified for a development or production environment:
ZDEV – This is a test environment for your application, which can be accessed through the developer channel U-verse Enabled Developer Test Channel (9315). If you have a consumer U-verse account, you can apply to have this channel enabled on your U-verse receiver through the U-verse Enabled Onboarding Tool. For more details, see the document, How to Register and Start Developing for U-verse Enabled. The AAP bundle will contain the environment name zdevca.
Production: This AAP bundle is issued after your app completes AT&T Quality Engineering testing. You must submit every version update of your app to AT&T for testing before the updated version is approved to run in the production environment. The production AAP bundle will contain the environment name prodca.
You must use the correct AAP bundle for each environment. Using the wrong AAP bundle will cause authentication to fail during Discovery with an internal U-verse error code 3000.
After you submit your app information using the U-verse Enabled Onboarding Tool, your development resource files will be uploaded and available to download from the U-verse Enabled Onboarding Tool. After your app passes AT&T Quality Engineering Testing, your production resource files will then be uploaded and available 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 the AAP bundle. This new version of the AAP bundle is not compatible with earlier versions of the U-verse Enabled SDK. However, the existing AAP bundles will continue to function with apps which are built using the 3.2 version of the U-verse Enabled SDK and earlier. An updated bundle is created when you create or update an app and select version 5.0 of the U-verse Enabled SDK in the U-verse Enabled onboarding tool. The updated AAP bundle is valid for ten years, an improvement over the previous bundle’s two years.
The same AAP files can be used in new versions of an app. However, all new versions of the app must undergo AT&T Quality Engineering testing before a new version may run in production and the new version number must be registered with AT&T through the U-verse Enabled Onboarding Tool. More information on the 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 4 of 9
Test AAP bundles (ZDEV) do not include version checking, and the version number can be changed during development. In the production environment, the version number is checked and the CFBundleShortVersionString (the Xcode build number) must exactly match the version number registered in the U-verse Enabled Onboarding Tool.
The AAP bundle file name ends with the extension .resource, and the developer key file name ends with the extension .satoken. Both file names are prefixed with the application bundle identifier, version number, and the environment that the files 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 be “com.example.ExampleTestApp.1.0.testca.resource” and “com.example.ExampleTestApp.1.0.testca.satoken”.
When a U-verse receiver has two different U-verse Enabled environments, the receiver will attempt to authenticate your app with the environment that was last used. This means that if you’re using a ZDEV AAP bundle, engagement will fail unless 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 5 of 9
3 Setting up a U-verse Enabled Project in Xcode
Follow 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 “Build Settings” tab.
ii. Scroll down to the “Linking” section. If you are unable to see the linking 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 “Build Settings” 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 6 of 9
i. Click the name of your app in the “Targets” list and click the “Build Phases” 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.framework
Figure 3-2: Link Binary With Libraries list.
4. Add the static library and the header files to the project. These files are part of the U-verse Enabled SDK you downloaded. To add them, open the folder containing the files in the Finder, and drag-and-drop them into your Xcode project window. The current version of the U-verse Enabled SDK for iOS is distributed in two separate libraries, the main library and the TV UI API library. The main library is critical for every U-verse Enabled app. The main library 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 current program and channel. The TV UI API library is distributed as an add-on library, 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 7 of 9
can draw your content on the user’s U-verse television screen. All U-verse Enabled apps must include the main library in their U-verse project, while apps using the TV UI API will need to include both libraries.
5. Import the AAP bundle into your project by unzipping the ZIP file and dragging the folder into your Xcode project window.
6. Choose the correct SERVER_URL for the project in your code, as in Example 3-1 below.
The SERVER_URL is dependent upon which U-verse Enabled network server you are connecting to:
https://zdais.iac.asp.att.net/dais/ – Use this URL if you using the U-verse Enabled Developer Test Channel. This environment is also known as the ZDEV 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 and you 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 the environment and type, such as “zdevca.satoken” for the zdev developer key.
Place the following code at the top of the appDelegate class:
Defined Environment Constants
1 | //#define __PRODUCTION__ 1
2 | //#define __ZDEV__ 1
3 |
4 |
5 | #ifdef __PRODUCTION__
6 | #define SERVER_URL @" https://dais.iac.asp.att.net/dais/ "
7 | #define AAP_RESOURCE_FILE @"prodca.resource"
8 | #define AAP_DEVELOPER_KEY @"prodca.satoken"
9 | #elif defined __ZDEV__
10 | #define SERVER_URL @" https://zdais.iac.asp.att.net/dais/ "
11 | #define AAP_RESOURCE_FILE @"zdevca.resource"
12 | #define AAP_DEVELOPER_KEY @"zdevca.satoken"
13 | #endif
14 |
15 |
16 |
17 |
Example 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 8 of 9
The following code has been designed to allow you to easily change the environment in your project using the constants defined above.
Add the following code to the application:didFinishLaunchingWithOptions method:
Change Environments
1 | NSURL *url = [[NSBundle mainBundle] URLForResource:AAP_DEVELOPER_KEY withExtension:nil];
2 | NSString *sharedSecret = [NSString stringWithContentsOfURL:url encoding:NSUTF8StringEncoding error:NULL];
3 | [mgr.userInfo setObject:sharedSecret forKey:UverseEnabledDeveloperKey];
4 | mgr.fileNameAAP = AAP_RESOURCE_FILE;
5 | mgr.overrideURL = SERVER_URL;
Example 3-2: Environment Code Sample.
You can also load only the AAP bundle specific to the environment you are using, then use the files and values in that bundle. However, the above method is recommended because it enables you to easily change the environment when required.
When you submit your app to AT&T for compliance testing, you must build it for the ZDEV environment. After your app passes the testing process, you must
rebuild 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 change between these builds is the AAP bundle you use for each environment. Any other changes to the code could lead to your apps being blocked from running in the U-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 9 of 9
4 Conclusion
The setup procedure described in this document is the same for any U-verse Enabled 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 document demonstrates the process of writing a basic U-verse Enabled remote control app, including the process of engaging with a U-verse receiver.
