AWS SDK for Android
Getting Started Guide
Next »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

Getting Started with the AWS SDK for Android

The AWS SDK for Android provides libraries, 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 the code samples.

About the SDK

The AWS SDK for Android includes:

  • Class libraries. Build Android applications on top of class libraries that hide much of the lower-level plumbing of the web service interface, including authentication, request retries, and error handling. Each service has its own library, so you can include class libraries for only the services you need and keep your application as small as possible.

  • Code samples. Practical examples of using the class libraries to build applications.

  • Documentation. Reference documentation of AWS SDK for Android API.

Get Set Up

Get Your Access Key ID and Secret Access Key

If you haven't already signed up for Amazon Web Services, you will need to do that first to get your access key ID and secret access key. Then you can set up your environment. Sign In or Create an AWS Account.

To get your access key ID and secret access key

Access keys consist of an access key ID and secret access key, which are used to sign programmatic requests that you make to AWS. If you don't have access keys, you can create them by using the AWS Management Console.

Note

To create access keys, you must have permissions to perform the required IAM actions. For more information, see Granting IAM User Permission to Manage Password Policy and Credentials in Using IAM.

  1. Go to the IAM console.

  2. From the navigation menu, click Users.

  3. Select your IAM user name.

  4. Click User Actions, and then click Manage Access Keys.

  5. Click Create Access Key.

    Your keys will look something like this:

    • Access key ID example: AKIAIOSFODNN7EXAMPLE

    • Secret access key example: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

  6. Click Download Credentials, and store the keys in a secure location.

    Your secret key will no longer be available through the AWS Management Console; you will have the only copy. Keep it confidential in order to protect your account, and never email it. 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 key.

Related topics

Get the SDK for Android

Minimum requirements for using the AWS SDK for Android are:

Download the SDK from http://aws.amazon.com/sdkforandroid. The SDK is stored in a compressed file named aws-android-sdk.zip. The .zip file contains the following:

  • /documentation folder. Contains the documentation in JavaDoc format.

  • /lib folder. Contains Java archive files (.jar) that include AWS class libraries. To manage the size of your application, you can include only the files that you need for the services your application is using. The .jar files can also help you with debugging your application. The following files are included:

    • aws-android-sdk-VERSION.jar. Contains all necessary files (including third-party dependencies) for all supported AWS services. All class files were compiled without the debug option.

    • aws-android-sdk-VERSION-autoscaling.jar. Contains the classes necessary to use Auto Scaling. Must be used with the aws-android-sdk-VERSION-core.jar file. All classes were compiled without debug.

    • aws-android-sdk-VERSION-cloudwatch.jar. Contains the classes necessary to use CloudWatch. Must be used with the aws-android-sdk-VERSION-core.jar file. All classes were compiled without debug.

    • 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 were built using these classes. The classes were compiled without debug.

    • aws-android-sdk-VERSION-ddb.jar. Contains all the classes necessary to use Amazon DynamoDB. Must be used with aws-android-sdk-VERSION-core.jar file. All classes were compiled without debug.

    • aws-android-sdk-VERSION-ddb-mapper.jar. Contains all the classes necessary to use the Amazon DynamoDB Object Mapper. Must be used with aws-android-sdk-VERSION-core.jar and aws-android-sdk-VERSION-ddb.jar files and only with Android API levels 8 and up (Android 2.2 or later). All classes were compiled without debug.

    • aws-android-sdk-VERSION-ddb-mapper-debug.jar. Contains all the classes necessary to use the Amazon DynamoDB Object Mapper. Must be used with the aws-android-sdk-VERSION-debug.jar file and only with Android API levels 8 and up (Android 2.2 or later). The code was compiled with the debug option on with all symbols retained.

    • aws-android-sdk-VERSION-debug.jar. Contains all files (including third-party dependencies) necessary for debugging. The code was compiled with the debug option on with all symbols retained.

    • aws-android-sdk-VERSION-ec2.jar. Contains the classes necessary to use Amazon Elastic Compute Cloud (Amazon EC2). Must be used with the aws-android-sdk-VERSION-core.jar file. All classes were without debug.

    • aws-android-sdk-VERSION-elb.jar. Contains the classes necessary to use Elastic Load Balancing. Must be used with the aws-android-sdk-VERSION-core.jar file. All classes were compiled without debug.

    • aws-android-sdk-VERSION-s3.jar. Contains the classes necessary to use Amazon Simple Storage Service (Amazon S3). Must be used with the aws-android-sdk-VERSION-core.jar file. All classes were 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 compiled without debug.

    • aws-android-sdk-VERSION-ses.jar. Contains the classes necessary to use Amazon Simple Email Service (Amazon SES). Must be used with the aws-android-sdk-VERSION-core.jar file. All classes were compiled without debug.

    • aws-android-sdk-VERSION-sns.jar. Contains the classes necessary to use the Amazon Simple Notification Service (Amazon SNS). Must be used with the aws-android-sdk-VERSION-core.jar file. All classes were compiled without debug.

    • aws-android-sdk-VERSION-sqs.jar. Contains the classes necessary to use the Amazon Simple Queue Service (Amazon SQS). Must be used with the aws-android-sdk-VERSION-core.jar file. All classes were compiled without debug.

    • aws-android-sdk-VERSION-sts.jar. Contains the classes necessary to use the AWS Security Token Service. Must be used with the aws-android-sdk-VERSION-core.jar file. All classes were compiled without debug.

  • /samples folder. Contains code built using the aws-android-sdk-VERSION-debug.jar library. Samples are named based on the services they demonstrate.

  • /src folder. Contains the original source files for the class libraries.

  • /third-party folder. Contains the individual .jar files and licenses for the third-party packages that the SDK depends on.

About the Demos

The /samples folder in the SDK contains a number of demo applications, including three demos in directories named S3_SimpleDB_SNS_SQS_Demo, S3_SimpleDB_SNS_SQS_DemoTVM, and S3_SimpleDB_SNS_SQS_DemoTVMIdentity. Each demo demonstrates how to make requests to AWS, but each takes a different approach to providing credentials to AWS.

In S3_SimpleDB_SNS_SQS_Demo, you enter your AWS Access Key ID and Secret Access Key directly into the application code. This approach will get you running quickly, but we do not recommend it in a production application: a malicious user could use decompiling techniques to steal your AWS security credentials.

Caution

Do not include your credentials in source code for applications outside your control, such as mobile apps.

S3_SimpleDB_SNS_SQS_DemoTVM and S3_SimpleDB_SNS_SQS_DemoTVMIdentity demonstrate a more secure mechanism for transferring AWS security credentials to a mobile client. These demos require a server application, in this case the token vending machine (TVM), which is provided as a separate download. TVM uses the AWS Security Token Service to get temporary security credentials and pass them to the mobile app.

The TVM is available in two forms: one that supports anonymous registration, and one that requires a user name and password to register a device and receive security tokens. As implied by their names, S3_SimpleDB_SNS_SQS_DemoTVM uses the anonymous registration TVM, while S3_SimpleDB_SNS_SQS_DemoTVMIdentity uses the identity registration TVM.

Important

In order to run the samples that use the token vending machine, you must first download and install the appropriate TVMs.

All three demos demonstrate how to access AWS from a mobile device using the following services:

  • Amazon Simple Notification Service (Amazon SNS), to create, delete, and list topics. You can list all subscribers, subscribe to a topic, and publish to a topic.

  • Amazon Simple Queue Service (Amazon SQS), to create, view, delete, and send messages to a queue.

  • Amazon Simple Storage Service (Amazon S3), to create and view data storage components called buckets and their contents.

  • Amazon SimpleDB, to create and view domains and create items.

Run the Demos

Important

To run the demos in Eclipse, you will need the ADT Plugin for Eclipse to create a virtual device for running the project. To download the ADT Plugin for Eclipse, go to http://developer.android.com/sdk/eclipse-adt.html.

Except for the way you provide your AWS credentials, the procedure for preparing each demo to run is the same.

To prepare the samples

  1. In the Eclipse environment, on the File menu, click Import.

  2. In the Import wizard, select General, then Existing Projects Into Workspace.

  3. Click the Browse button next to Select root directory.

  4. In the Browse For Folder dialog box, navigate to the samples folder and click Open.

  5. Click the checkbox for each sample you want to import into your workspace.

The procedure you follow to configure the demo for acquiring AWS credentials depends on which demo you are preparing to run:

  • For the S3_SimpleDB_SNS_SQS_Demo, you enter your access key ID and secret key directly in a properties file.

  • For the S3_SimpleDB_SNS_SQS_DemoTVM, the mobile client registers anonymously with the token vending machine and receives a token that provides access to the services that the sample uses.

  • For S3_SimpleDB_SNS_SQS_DemoTVMIdentity, the mobile client registers with the token vending machine by providing a user name and password and then receives a token that provides access to the services that the sample uses.

To provide your AWS credentials for the demo you are preparing, proceed directly to the corresponding procedure.

To provide your AWS Credentials to S3_SimpleDB_SNS_SQS_Demo

  1. In the Eclipse environment, open the sample project and, navigate to the src/com.amazon.aws.demo folder, and open the AwsCredential.properties file.

  2. In the file, edit the ACCESS_KEY_ID and SECRET_KEY attributes to reflect the corresponding keys for your own AWS account, then save and close the file.

  3. Build the project by selecting Project, then click Build Project.

  4. Run the application by selecting Run, then click Run.

To allow anonymous registration for S3_SimpleDB_SNS_SQS_DemoTVM

  1. In the Eclipse environment, open the sample project and, navigate to the src/com.amazon.aws.demo.anonymous folder, and open the AwsCredential.properties file.

  2. In the file, edit the tokenVendingMachineURL attribute to reflect the address of your TVM deployment.

  3. Build the project by selecting Project, then click Build Project.

  4. Run the application by selecting Run, then click Run.

To require a user name and password for S3_SimpleDB_SNS_SQS_DemoTVMIdentity

  1. In the Eclipse environment, open the project and, navigate to the src/com.amazon.aws.demo.identity folder, select the AwsCredential.properties file, then click Open.

  2. In the file, edit the tokenVendingMachineURL to reflect the address of your TVM deployment.

  3. Edit the appName attribute to reflect the name that you gave to the mobile application when you installed it, then save and close the file.

  4. In a browser, sign in to the AWS Management Console. At the top of the console, click the drop-down arrow to open a list of services. In the service list, click AWS Elastic Beanstalk.

  5. On the Actions menu for your TVM application, click Edit/Load Configuration and select the Container tab.

  6. In the PARAM1 box, type the name that you gave to the mobile application. This is the same name that you entered as the value for the appName attribute earlier. Click Apply Changes.

  7. Build the project by selecting Project, then click Build Project.

  8. Run the application by selecting Run, then click Run.

S3_SimpleDB_SNS_SQS_DemoTVMIdentity requires the user to register with a user name and password before using any AWS features.

To register a user for the S3_SimpleDB_SNS_SQS_DemoTVMIdentity demo

  1. In the Android Virtual Device running the S3_SimpleDB_SNS_SQS_DemoTVMIdentity demo, click Login.

  2. On the Login screen, click Register.

  3. In the registration form, enter a user name and password. User names and passwords must be at least six (6) characters long. Once you've entered them, click Register.

  4. Press the back button twice to switch back to the to the S3_SimpleDB_SNS_SQS_DemoTVMIdentity demo.

  5. On the Login screen, enter the user name and password of the user you registered, then click Login. You can now use the AWS features in the demo.

Running the Other Supplied Demos

To build and run the other provided demo applications, please refer to the supplied README for instructions.

How to Include the AWS SDK for Android in an Existing Application

The samples included with the AWS SDK for Android are provided as standalone projects set up for you to try out. To use AWS with an existing application, follow these steps:

  1. Create a libs directory within your Android project directory if one does not already exist.

  2. Copy either a bundled .jar for all services or the specific JARs for the services you wish to use. You have three options:

    • Add aws-android-sdk-VERSION-debug.jar. This .jar creates the largest APK, but allows for full stack traces during development.

    • Add aws-android-sdk-VERSION.jar. This .jar creates a smaller APK and a simple bundle when releasing your application.

    • Add the aws-android-sdk-VERSION-core.jar plus the .jar files for the individual services your project will use. This method creates the smallest APK, but requires a more complicated setup.

    Note, copying both bundled and service .jar files will cause errors.

  3. In Eclipse, go to your project, select Properties -> Java Build Path -> Libraries and click Add JARs. Then select the .jar files you added to your libs directory.

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 http://aws.amazon.com/sdkforandroid.

View the SDK Reference Documentation Online

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 AWS SDK for Android API Reference.