© 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 an AT&T U-verse Enabled Project in AndroidTM

Publication Date: July 16 2015

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 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.

Android is a trademark of Google Inc.

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.2 Defined Terms ............................................................................................................................... 2

2 Setting up a U-verse Enabled Project in Android Studio ...................................................................... 3

3 Using a U-verse Enabled Android Sample App ..................................................................................... 8

4 Conclusion ............................................................................................................................................. 9

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.

iii

Example 2-1: Android Studio Project Permissions. ....................................................................................... 3

Example 2-2: Server URL variable. ................................................................................................................ 6

Example 2-3: Get Uverse Enabled manager. ................................................................................................ 6

© 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 U-verse Enabled app to make use of the U-verse Enabled platform and the U-verse Enabled SDK, you should be familiar with the process of setting up 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 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, covers the process for applying for an AAP and requesting the U-verse Enabled Developer Test Channel to be enabled on your U-verse receiver.

All apps must be submitted for AT&T Quality Engineering Testing. For more details on the expectations and testing criteria of an U-verse Enabled app, see the AT&T U-verse Enabled Developer Guidelines, and the document U-verse Enabled Mobile Application Security. For the process of submitting your app for Quality Engineering testing, see Submit AT&T U-verse Enabled Apps on the AT&T Developer Program web site.

This document describes how to set up a U-verse Enabled project in the Android Studio development environment, including configuring your project, adding the necessary frameworks and U-verse libraries, and incorporating the AAP bundle.

1.1 Additional Resources

In addition to the documents listed above, you may find these documents helpful when developing U-verse Enabled Android apps:

How to Register and Start Developing for U-verse Enabled

How to Write Your First AT&T U-verse Enabled Android App

You can find these documents and other technical information in the Develop AT&T U-verse Enabled Android Apps section of the AT&T Developer Program website.

© 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

1.2 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.

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 (SetTopBox) 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 (SetTopBox): Receiver is the term for a U-verse SetTopBox that enables the user to watch and record AT&T U-verse programming.

U-verse Enabled Control Panel: The Control Panel in the Launch Center 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 Setting up a U-verse Enabled Project in Android Studio

To set up a U-verse Enabled Android Project in Android Studio, use the following procedure:

1. Create a new project in Android Studio. You can do this using any of the activity templates that come with the Android SDK in Android Studio.

2. Add the necessary permissions to the project using the following steps:

i. Open the AndroidManifest.xml

ii. Add the following permissions

Project Permissions

1 | <uses-permissionandroid:name="android.permission.INTERNET"/>

2 | <uses-permissionandroid:name="android.permission.ACCESS_WIFI_STATE"/>

3 | <uses-permissionandroid:name="android.permission.CHANGE_WIFI_MULTICAST_STATE"/>

4 | <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

5 | <uses-permission android:name="android.permission.READ_PHONE_STATE" />

Example 2-1: Android Studio Project Permissions.

3. Add the static SDK library files (for example, UverseEnabledAndroid-5.2.9p.jar) to the project in the libs folder. These files were downloaded as part of the SDK. To add them, simply drag and drop from a finder window that contains the files. You may have to configure the project property to include the library in the java build path.

4. Import the AAP bundle files information into your project.

The AAP zip file (for example, com.att.android.AndroidSampleApp.1.0.zdevca.zip) contains resource files including your AAP bundle and your developer key. The resource file in the zip file will differ depending on whether your app is certified for a development environment or for a production environment. After you submit your app information to the Launch Center, your development resource files will be uploaded to your developer dashboard. After your app passes AT&T acceptance testing, your production resource files will be uploaded to your developer dashboard.

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

© 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

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.

In the sample app, the AAP bundle has been added to the raw area of the project and the developer key is stored in strings.xml. It is recommended to encrypt the developer key and then decrypt the key when using it.

To associate your app with the receiver, both the AAP bundle and the key are needed. The file names are prefixed with the app bundle identifier, version number, the environment the files are issued for, and the suffix .resource for the AAP bundle and .satoken for the key. For example, the bundle might be named com_att_android_androidsampleapp_1_0_zdevca.resource, and the developer key might be named com.att.android.AndroidSampleApp.1.0.zdevca.satoken.

A unique AAP bundle and developer key for each environment must be used or your U-verse Enabled app will fail during Discovery. If you receive an error code, check its description in the uveErrorCodes object. A LibraryNotReady error may occur if the AAP resource and developer key values do not match, or if the package name submitted during the app registration is not the same as that used now.

Separate AAP resources are required for XDEV, ZDEV and Production environments.

The following changes are required in the AAP files before using it in your app.

There cannot be multiple dots or capital letters used in resource file names. For example, a bundle file named com.att.android.androidsampleapp.1.0.zdevca.resource should be renamed com_att_android_androidsampleapp_1_0_zdevca.resource.

The satoken file contains your developer key and is used in your app to verify the AAP bundle. This file is a shared secret and should be kept private. The key contained in this file must be passed to the uveManager before calling startDiscovery.

The satoken file content should be added to the strings.xml file and can be accessed in the normal manner. For example, content for the secret key secret_key_zdev_phase5 would be inserted to read:

getString(R.string.secret_key_zdev_phase5);

© 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

The following illustration shows the Android project and file structure.

Figure 2-1: Android Project and File Structure.

5. Choose the correct server URL for the project.

The server URL is dependent upon which U-verse Enabled network server you are connecting to.

Server environments can now be selected through uveManager.Server enums.

Note: If you use the wrong server URL, attempts to run the application will fail and you will receive a uveFailedToAuthenticateServer error. You must set the server URL before calling startDiscovery. If you change the server URL while the application is running, you must quit the application and re-launch it before the new server URL will be used for discovery. Phase 5 server URL should be used when you are using the 5.0.X or higher version of U-verse Enabled Android SDK.

The current server Phase 5 URLs in use are:

https://zdais.iac.asp.att.net/dais/: Use this URL if you are using the developer channel 9315 for development.

https://dais.iac.asp.att.net/dais/: This is the production server URL. Channel 9301 is associated with the Production U-verse environment.

The Phase 3 server URLs are:

© 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

https://zdevsa.asp.att.net/dais/: Use this URL if you are using the developer channel 9315 for development.

https://vsapps.asp.att.net/dais/: This is the production server URL. Channel 9301 is associated with the Production U-verse environment.

6. Set the environment in your code to use the correct AAP bundle and server URL.

Use the server URL variable, so that the project is easily configurable. The following example is the method used in the sample code.

In the \res\values\strings.xml file, add the following:

Server URL variable

1 | <string name="serveraddress_production_phase5">https://dais.iac.asp.att.net/dais/</string>

2 | <stringname="serveraddress_zdev_phase5">https://zdais.iac.asp.att.net/dais/</string>

3 | <string name="serveraddress_production_phase3">https://vsapps.asp.att.net/dais/</string>

4 | <stringname="serveraddress_zdev_phase3">https://zdevsa.asp.att.net/dais/</string>

Example 2-2: Server URL variable.

The following example code sets the server address in RemoteScreenActivity.java to the ZDEV environment:

uveManager.setServerAddress(getString(R.string.serveraddress_zdev_phase5));

Environment, bundle, and developer key settings for various environments must be updated in the startDiscovery method in uveManager. You can choose to implement this in various ways, such as with flags for each environment and a method for selecting the environment so that the server address, bundle file, and secret key all match.

getUverseEnabledmanager has a new construction that does not require a deviceID to get the uverseEnabledManager instance.

getUverseEnabledManager

1 | uveMgr = uveManager.getUverseEnabledManager(this,

2 | null,

3 | R.raw.com_att_android_androidsampleapp_1_0_zdevca, getString(R.string.secret_key_zdev_phase5));

Example 2-3: Get Uverse Enabled manager.

© 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

This is necessary for the following important reasons:

When you submit your application for AT&T QE testing, you will need to build for the ZDEV environment, and after the testing is complete you must rebuild the application with the production AAP for submission to the Android Market.

As part of your Developer agreement with AT&T, you have agreed that the only change between these builds will the changing of the AAP bundle you use for each environment, and any other changes to the code could lead to any or all of 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 8 of 9

3 Using a U-verse Enabled Android Sample App

To get up to speed with U-verse Enabled apps, you can find sample apps on the U-verse Enabled Sample Code section of the AT&T Developer Program website.

To use a sample app, follow these steps in Android Studio:

1. Import one of the U-verse Enabled Android sample apps(File -> New -> Import Project).

2. In the AAP bundle file name, replace the dots (.) with underscores (_ on your desktop. Do not make this change within Android Studio or the bundle may become corrupted.

3. Copy the resource file to the U-verse Enabled Remote/app/src/main/res/raw folder.

4. Copy the U-verse Enabled Android SDK jar file to the /app/libs folder.

5. Right click the libraries(.jar files) and select “Add as Library”, so that the jar file dependencies gets added to the build.gradle file in app module.

eg.

dependencies {

compile files('libs/UverseEnabledAndroid-5.2.9p.jar')

compile files('libs/gson-2.2.2.jar')

}

6. In Project, navigate to java folder then right click and select new package. Then enter the package name used while registering your application in developer portal and press OK.

7. Now select all the files in the “AndroidSampleApp” package and drag it to the new package created.

8. Build the project. You will see errors in UVEBaseActivity.java, requiring you to update the AAP file and satoken in getUverseEnabledManager:

uveMgr = uveManager.getUverseEnabledManager(this, null, UPDATE_AAPBUNDLE_RESOURCEFILE, UPDATE_DEVELOPERKEY_SATOKENFILE);

9. In AndroidManifest.xml and build.gradle files, where com.att.android.AndroidSampleApp appears, change to your app package name.

10. Remove “import com.att.android.AndroidSampleApp.R;” from all of your files.

11. Restart Android Studio, then make a clean build and run the sample app.

© 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 steps described in this document are necessary for building any U-verse Enabled project. If this is your first project, we recommend that as a next step you read the document, How to Write Your First U-verse Enabled Android App. This document demonstrates a basic U-verse Enabled remote control application and shows the steps your application must perform to engage a U-verse receiver.