Download Report

AT&T U-verse® Enabled
How to Set Up a U-verse® Enabled Project in Xcode ®
Publication Date: September 23, 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 Contents
Contents
1
Introduction .......................................................................................................................................... 1
1.1
Additional Resources .................................................................................................................... 1
2
About the AAP Bundle .......................................................................................................................... 2
3
Setting up a U-verse Enabled Project in Xcode ..................................................................................... 4
4
Conclusion ............................................................................................................................................. 9
© 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 Figures
Figure 3-1: Other Linker Flags settings on the Build Settings screen............................................................ 4
Figure 3-2: Link Binary With Libraries list ..................................................................................................... 5
© 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.
iii
Table of Examples
Example 3-1. Environment Constants........................................................................................................... 7
Example 3-2. Environment Code Sample ...................................................................................................... 7
© 2013 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.
iv
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. The process for
obtaining an AAP is covered in the document, “How to Start Developing for
U-verse Enabled.”

A U-verse receiver that has been configured for the development and test
environments.
The How to Register and Start Developing U-verse Enabled Apps document
covers the process for applying for an AAP and requesting the developer channel
(9315) to be enabled on your U-verse receiver.
All apps need to undergo AT&T Quality Engineering Testing. For more details on
the expectations and testing criteria of an U-verse Enabled App, please view the
AT&T U-verse Enabled Developer Guidelines. For more details of the process of
submitting your application for Quality Engineering Testing, see Submit AT&T Uverse Enabled Apps on the AT&T Developer Program web site.
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 in
Objective-C, the Cocoa Touch frameworks and using Xcode. You will find
instructions on how to configure your project, add the necessary frameworks and
U-verse libraries, and how to incorporate the AAP bundle that you have obtained
for your app.
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 on the
AT&T Developer Program web site. See Develop AT&T U-verse ® Enabled iOS
Apps.
© 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 9
2 About the AAP Bundle
The AAP (Application Authentication Package) bundle is a zip file that contains
resource files including your Application Certificate and your Developer Key. The
Developer Key is a shared secret and should be kept private. Your app must
pass the key to the UverseConnectedManager object before calling
startDiscovery.
The resource files differ depending on whether your app is certified for a
development environment or a production environment. After you submit your
app information to the AT&T Launch Center, development resource files will be
available in your developer dashboard, and after your app passes AT&T Quality
Engineering testing, production resource files will be available.
Note: The same AAP files can be used in new versions of an app. However,
version number changes must be registered with AT&T through the U-verse
Enabled Control Panel in the Launch Center for the production environment. All
new versions of the app must undergo AT&T Quality Engineering testing before a
new version may run in production. More information on the submission process,
see Submit AT&T U-verse ® Enabled Apps.
The test AAPs do not include version checking, and as such the version number
can be changed during development.
The AAP resource file and the AAP Developer Key are necessary to associate
your app with a U-verse receiver (SetTopBox).
The resource 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 bundle identifier, version number, and the environment that the
files are issued for. You must use the correct AAP Bundle for each environment,
and using the wrong AAP bundle will cause your app to fail with an Internal Uverse error (error code 3000).
For example, files for an app named “ExampleTestApp” version 1.0 in a test
environment will be in the bundle “com.example.ExampleTestApp”, and the file
names will include “com.example.ExampleTestApp.1.0.testca.resource” and
“com.example.ExampleTestApp.1.0.testca.satoken”.
There are three different types of AAP bundles that could be issued.

Production: This AAP 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 allowed to run in the
production environment. The AAP bundle will contain the environment name
prodca.

ZDEV – This is a test environment that can be used to test your application.
This environment can be accessed through the developer channel (9315). If
© 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 9
you have a consumer U-verse account, you can apply for this channel to be
enabled on your U-verse receiver through the Launch Center. The details of
this are covered in How to Register and Set Up a U-verse ® Enabled
Environment. This channel can also be accessed through the RAKv2. The
AAP bundle will contain the environment name zdevca.

XDEV – This is the test environment that can be accessed if you apply to do
your testing in the AT&T Innovation Center in Palo Alto. This does not use the
developer channel (9315) and is instead accessed through the menu system
on the U-verse receiver. This is the environment that is used by the RAKv1.
The AAP bundle will contain the name testca.
When you use the developer channel (9315) for your testing, you must first tune
your receiver to the developer channel before testing begins. As these U-verse
receivers have two different U-verse Enabled environments, production and
ZDEV, the U-verse receiver will attempt to authenticate your app with the
environment that was last used.
If the last used environment was the production environment (channel 9301), and
you are trying to run an app with a ZDEV AAP, engagement will fail. If you tune
the receiver to the developer channel (channel 9315), and restart your app, it will
then succeed.
This is also the case if you are testing an app in the ZDEV environment, and then
want to run an app in the production environment, such as an app that was
downloaded from the App Store, you will first need to tune the U-verse receiver
to channel 9301 before the app will be able to engage with the U-verse receiver.
© 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 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
a. Click the name of your app in the “Targets” list and click the “Build
Settings” tab.
b. 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.
c. 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:
© 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 9
a. Click the name of your app in the “Targets” list and click the “Build
Phases” tab.
b. Expand the “Link Binary With Libraries” section.
c. At the bottom of the section, click the “+” symbol.
d. 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. As of the 3.1 release of the U-verse Enabled SDK for iOS,
the SDK is now 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 a add-on
library, and contains the API for creating U-verse Enabled apps where you
© 2013 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
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://zdevsa.asp.att.net/dais/ – Use this URL if you using the developer
channel (9315) in Production U-verse for development or the RAKV2.
This environment is referred to as the ZDEV environment.

https://swsdcs.foundry.att.com/dais/ – Use this URL if you are not in a Uverse area and are using a Remote Access Kit Version 1 (RAKV1) for
development, or if you are developing during a development session at
the AT&T Innovation Center in Palo Alto. This environment is referred as
the XDEV environment.

https://vsapps.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.
The following code example is the recommended method for setting the
appropriate U-verse environment. This code is designed to allow you to
simply un-comment the environment you wish to use, and assigns priority first
to PRODUCTION, then ZDEV, then FOUNDRY. For example, if you are
looking to use the foundry server and you un-comment both “__ ZDEV__”
and “__ FOUNDRY__”, your app will use the constants for “__ ZDEV__”.
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:
© 2013 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
Defined Environment Constants
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
//#define __PRODUCTION__ 1
//#define __ZDEV__ 1
#define __FOUNDRY__ 1
#ifdef __PRODUCTION__
#define SERVER_URL @"https://vsapps.asp.att.net/dais/"
#define AAP_RESOURCE_FILE @"prodca.resource"
#define AAP_DEVELOPER_KEY @"prodca.satoken"
#elif defined __ZDEV__
#define SERVER_URL @"https://zdevsa.asp.att.net/dais/"
#define AAP_RESOURCE_FILE @"zdevca.resource"
#define AAP_DEVELOPER_KEY @"zdevca.satoken"
#elif defined __FOUNDRY__
#define SERVER_URL @"https://swsdcs.foundry.att.net/dais/"
#define AAP_RESOURCE_FILE @"testca.resource"
#define AAP_DEVELOPER_KEY @"testca.satoken"
#endif
Example 3-1. Environment Constants
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
|
2
|
3
|
4
5
|
|
NSURL *url = [[NSBundle mainBundle]
URLForResource:AAP_DEVELOPER_KEY withExtension:nil];
NSString *sharedSecret = [NSString stringWithContentsOfURL:url
encoding:NSUTF8StringEncoding error:NULL];
[mgr.userInfo setObject:sharedSecret
forKey:UverseEnabledDeveloperKey];
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 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.
© 2013 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
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.
© 2013 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 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, How to Write
Your First 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.
© 2013 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