AWS SDK for Android (Beta) Readme

The AWS SDK for Android provides a library, code samples, and documentation for developers to build connected mobile applications using AWS. This guide walks through the steps for setting up the SDK and running one of the samples. 

About the SDK

The AWS SDK for Android includes:

• Libraries- Build Android applications on top of APIs that take the complexity out of coding directly against a web service interface. The libraries provide APIs that hide much of the lower-level plumbing, including authentication, request retries, and error handling. Each service has its own library, so you can use only the services you need and keep your application size as small as possible.
• Code Samples- Practical examples for how to use the library to build applications.
• Documentation- Complete reference documentation demonstrating how to use the SDK.

Get Set Up

To get set up, you must sign up for Amazon Web Services, get your AWS credentials, and set up your environment.

Sign Up for AWS Products

Before you can begin, you must sign up for each AWS product you want to use. The sample we'll cover in this guide uses both Amazon SimpleDB, Amazon S3, Amazon SNS, and Amazon SQS, so you'll need to sign up for all four products.

1. Go to the home page for the product, for example aws.amazon.com/s3/.
   
   Tip: Go to aws.amazon.com/products for a list of links to all our products.
   
   
2. Click the sign-up button on the top right corner of the page.
3. Follow the on-screen instructions. If you don't already have an AWS account, you are prompted to create one as part of the sign-up process.

AWS sends you a confirmation email after the sign-up process is complete. You can view your current account activity or manage your account at any time, by going to aws.amazon.com and clicking the Account tab.

Get Your Credentials

In order to use the AWS SDK for Android, you need your AWS Access Key ID and Secret Access Key.

1. Go to http://aws.amazon.com/.
2. Click Account and then click Security Credentials.
   The Security Credentials page displays (you might be prompted to log in).
3. Scroll down to Access Credentials and make sure the Access Keys tab is selected.
   The AWS Access Key ID appears in the Access Key column.
4. To view the Secret Access Key, click Show.

Important! Your Secret Access Key is a secret, which only you and AWS should know. It is important to keep it confidential to protect your account. Store it securely in a safe place. Never include it in your requests to AWS, and never email it to anyone. Do not share it outside your organization, even if an inquiry appears to come from AWS or Amazon.com. No one who legitimately represents Amazon will ever ask you for your Secret Access Key.

Get the Android SDK

Downlod the SDK from http://aws.amazon.com/sdkforandroid.

Minimum requirements for using the AWS SDK for Android are:

• Requires Android 2.1 (API Level 7) or higher. For more information on the Android SDK, see developer.android.com.
• To run the sample in this guide, you also need Android Development Tools.

Package Contents

After unzipping the AWS SDK for Android package, you'll find the following contents:

• documentation- Contains the JavaDocs for all of the relevant portions of the SDK.
• lib- Contains a number of jars to help you better determine how to bundle your Android application. The .jar files can help with debugging your application or helping reduce the size of the production application.
• aws-android-sdk-VERSION-obfuscated.jar- Contains all necessary files (including third-party dependencies) for AmazonS3, SimpleDB, SQS and SNS. All class files are obfuscated and compilation was done without the debug option. This is the smallest jar file possible for the SDK.
• aws-android-sdk-VERSION-debug.jar- Contains all necessary files (including third-party dependencies). No obfuscation and all codes was compiled with the debug option on.
• aws-android-sdk-VERSION-core.jar- Contains all third-party dependencies and the base platform used to send and process requests to AWS services. All services are built using this classes. The classes were compiled with debug OFF and were obfuscated.
• aws-android-sdk-VERSION-s3.jar- Contains the classes necessary to use Amazon S3. Must be used with the aws-android-sdk-VERSION-core.jar file. All classes were obfuscated and are compiled without debug.
• aws-android-sdk-VERSION-sdb.jar- Contains the classes necessary to use Amazon SimpleDB. Must be used with the aws-android-sdk-VERSION-core.jar file. All classes were obfuscated and are compiled without debug.
• aws-android-sdk-VERSION-sqs.jar- Contains the classes necessary to use the Amazon SQS. Must be used with the aws-android-sdk-VERSION-core.jar file. All classes were obfuscated and are compiled without debug.
• aws-android-sdk-VERSION-sns.jar- Contains the classes necessary to use the Amazon SNS. Must be used with the aws-android-sdk-VERSION-core.jar file. All classes were obfuscated and are compiled without debug.
• samples- Contains code built using the aws-android-sdk-VERSION-obfuscated.jar library.
• src- Contains the original source files for the SDK.
• third-party- Contains the individual jars and licenses for the third-party packages SDK is dependent on.

Run the Sample

The /samples directory in the SDK contains a browser application that demonstrates how to make requests to AWS using the SDK.

The following steps assume you're using the ADT Plugin for Eclipse and have created a Virtual Device for running the project. For more information, see http://developer.android.com/sdk/eclipse-adt.html.

To run the browser sample

1. Open a Sample Android Project:
   1. Go to File -> New Android Project. The New Project wizard opens.
   2. Select Create project from existing source, then click the Browse button to select the sample code. The Browse dialog box opens.
   3. Browse to the sample/AWSAndroidDemo directory, then click Open.
   4. Verify that the Build Target is Android 2.1.
   5. Click Finish.
2. Edit the Project properties:
   1. Go to Project -> Properties.
   2. Select the Libraries tab.
   3. Click Add External JARs. The Browse dialog box opens.
   4. Browse to
      samples/AWSAndroidDemo/lib/aws-android-sdk-1.0.12-obfuscated.jar, then click Select.
3. Update your AWS Credentials:
   1. Open the AwsCredential.properties file located in src/com/amazon/aws/demo.
   2. Edit the file to use your Access Key ID and Secret Access Key.
4. Run the project:
   1. Go to Project -> Clean.
   2. Go to Project -> Build All.
   3. Go to Run -> Run.

Where Do I Go from Here?

For more information about the AWS SDK for Android, including a complete list of supported AWS products, go to aws.amazon.com/sdkforandroid.

SDK Reference Documentation

The SDK reference documentation includes the ability to browse and search across all code included with the SDK. It provides thorough documentation, usage examples, and even the ability to browse method source. You can find it at http://docs.amazonwebservices.com/AWSAndroidSDK/latest/javadoc/.