AWS SDK for iOS Documentation
Getting Started 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 iOS

The Amazon Web Services SDK for iOS 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 the code samples.

About the SDK

The AWS SDK for iOS includes:

  • AWS iOS libraries. Build iOS applications on top of APIs 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 libraries for only the services you need.

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

  • Documentation. Reference documentation of AWS SDK for iOS.

Get Set Up

Get Your Credentials

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

To get your AWS Access Key ID and Secret Access Key

  1. Go to the AWS Account page, then click Security Credentials. If you are prompted to log in, do so.

  2. To see your AWS Access Key ID, scroll down to Access Credentials and ensure that the Access Keys tab is selected.

  3. To view your Secret Access Key, click Show.

Important

Your Secret Access Key should be known only to you and AWS. Store it 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 iOS SDK

Minimum requirements for using the AWS SDK for iOS are:

  • Xcode v4 or higher.

  • iOS v4.3 or higher.

Download the SDK from http://aws.amazon.com/sdkforios. The SDK is stored in a compressed file archive named aws-ios-sdk-#.#.#.zip (where '#.#.#' represents the version number, so for version 1.4.4, the filename is aws-ios-sdk-1.4.4).

The AWS SDK for iOS now includes separate frameworks for each AWS service supported by the SDK. In addition to these service-level frameworks, the SDK also includes a runtime framework that contains the base platform that the service frameworks utilize. Separating these frameworks allows developers to choose which services to include in their app—and more importantly—which version. Therefore, as we update the AWS SDK for iOS, you can choose which service frameworks to update in your application based on the changes offered.

Description of the Frameworks

  • /AWSRuntime.framework. Contains all third-party dependencies as well as the base platform that is used to send to and process requests from AWS services. All individual service frameworks depend on this framework.

  • /AWSAutoScaling.framework. Contains all the classes necessary to use Auto Scaling. Must be used with AWSRuntime.framework.

  • /AWSCloudWatch.framework. Contains all the classes necessary to use Amazon CloudWatch. Must be used with AWSRuntime.framework.

  • /AWSDynamoDB.framework. Contains all the classes necessary to use Amazon DynamoDB. Must be used with AWSRuntime.framework. This framework contains the latest version of the Amazon DynamoDB service, currently version 2012-08-10. If you wish to use the older version of Amazon DynamoDB, please see the legacy AWSiOSSDK.framework.

  • /AWSEC2.framework. Contains all the classes necessary to use Amazon EC2. Must be used with AWSRuntime.framework.

  • /AWSElasticLoadBalancing.framework. Contains all the classes necessary to use Elastic Load Balancing. Must be used with AWSRuntime.framework.

  • /AWSS3.framework. Contains all the classes necessary to use Amazon S3. Must be used with AWSRuntime.framework.

  • /AWSSimpleDB.framework. Contains all the classes necessary to use Amazon SimpleDB. Must be used with AWSRuntime.framework.

  • /AWSSES.framework. Contains all the classes necessary to use Amazon SES. Must be used with AWSRuntime.framework.

  • /AWSSNS.framework. Contains all the classes necessary to use Amazon SNS. Must be used with AWSRuntime.framework.

  • /AWSSQS.framework. Contains all the classes necessary to use Amazon SQS. Must be used with AWSRuntime.frameworkr.

  • /AWSSecurityTokenService.framework. Contains all the classes necessary to use AWS Security Token Service (STS). Must be used with AWSRuntime.framework.

  • /AWSPersistence.framework. Contains all the classes necessary to use the AWS Persistence Framework for Core Data. Must be used with AWSRuntime.framework and AWSDynamoDB.framework.

  • /legacy/AWSiOSSDK.framework. This all-in-one framework contains all the classes and dependencies for the entire AWS SDK for iOS. If you include this framework in your project, it provides access to all services. Going forward, we intend to update only the individual frameworks, which will provide you greater control. This framework also supports the older version of the Amazon DynamoDB service, version 2011-12-05. This framework does not include the AWS Persistence Framework for Core Data. If you wish to use that functionality in your app, you will need to migrate to the service-specific frameworks as described above.

  • /Documentation. Contains the documentation for the AWS SDK for iOS.

  • /samples. Contains code built using the included frameworks. Samples are named based on the services that they demonstrate.

  • /src. Contains the implementation and header files for the AWS iOS libraries.

  • /src-persistence. Contains the implementation and header files for the AWS Persistence Framework for Core Data libraries.

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

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

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 (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 (SQS), to create, view, delete, and send messages to a queue.

  • Amazon Simple Storage Service (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

Providing Credentials to the Samples

To prepare the samples

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

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

  • For 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 Finder, navigate to the samples/S3_SimpleDB_SNS_SQS_Demo folder and double-click the AWSiOSDemo.xcodeproj file to open the project in Xcode.

  2. In Xcode's Project Navigator, expand the AWSiOSDemo/Classes folder, then open Constants.h.

  3. In Constants.h, edit the ACCESS_KEY_ID and SECRET_KEY definitions with the corresponding keys for your AWS account, then save and close the file.

  4. To build and run the project, press Command+R.

To allow anonymous registration for S3_SimpleDB_SNS_SQS_DemoTVM

  1. In Finder, navigate to the samples/S3_SimpleDB_SNS_SQS_DemoTVM folder, and double-click AWSiOSDemoTVM.xcodeproj to open the project in Xcode.

  2. In Xcode's Project Navigator, expand the AWSiOSDemoTVM/Classes folder, then open Constants.h.

  3. In Constants.h, edit the TOKEN_VENDING_MACHINE_URL definition to reflect the location of your TVM installation, then save and close the file.

  4. To build and run the project, press Command+R.

To require a user name and password for S3_SimpleDB_SNS_SQS_DemoTVMIdentity

  1. In Finder, navigate to the samples/S3_SimpleDB_SNS_SQS_DemoTVMIdentity folder. Double-click AWSiOSDemoTVMIdentity.xcodeproj to open the project in Xcode.

  2. In Xcode's Project Navigator, expand the AWSiOSDemoTVMIdentity/Classes folder, then open Constants.h.

  3. In Constants.h, edit the TOKEN_VENDING_MACHINE_URL definition to reflect the location of your TVM installation.

  4. Edit the APP_NAME definition to reflect the name of your mobile application, then save and close the file.

    Note

    Changing the APP_NAME to a new APP_NAME will require any existing registered users to register again.

  5. To build and run the project, press Command+R.

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. With the S3_SimpleDB_SNS_SQS_DemoTVMIdentity project running, touch one of the service demo buttons, such as S3 - List Buckets. If you are not logged in you will be presented with a Login form.

  2. On the Login form, touch Register.

  3. In the registration form, enter a user name and password, then touch Register.

  4. Press the Home button, then touch the Identity application icon.

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

Running the Other Supplied Demos

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

Install the Reference Documentation in Xcode

The AWS SDK for iOS includes documentation in DocSet format that you can view within Xcode. The easiest way to install the documentation is to use the Mac OS X terminal.

To install the DocSet for Xcode

  1. Open the Mac OS X terminal and go to the directory containing the expanded archive. For example:

    $ cd ~/Downloads/aws-ios-sdk-1.4.4

    Note

    Remember to replace 1.4.4 in the example above with the actual version number of the AWS iOS SDK that you downloaded.

  2. Create a directory called ~/Library/Developer/Shared/Documentation/DocSets:

    $ mkdir -p ~/Library/Developer/Shared/Documentation/DocSets

  3. Copy (or move) Documentation/com.amazon.aws.ios.docset from the SDK installation files to the directory you created in the previous step:

    $ mv Documentation/com.amazon.aws.ios.docset ~/Library/Developer/Shared/Documentation/DocSets/

  4. If Xcode was running during this procedure, restart Xcode.

Include the AWS SDK for iOS in Existing Applications

The samples included with the AWS SDK for iOS are provided as standalone projects set up for you already. If you have an existing application in which you'd like to use AWS, follow these steps:

  1. In Xcode, on the File menu, click Open, then double-click your project.

  2. Control-click Frameworks Group, then click Add files to <project name>.

  3. In Finder, navigate to AWSRuntime.framework, and all of the additional service frameworks you want to use, then click Add.

  4. In your source code, import the appropriate headers for the services you are using. The header file import convention is FRAMEWORKNAME/FRAMEWORKNAME.h, as in the following example.

    #import <AWSRuntime/AWSRuntime.h>
    #import <AWSS3/AWSS3.h>
    #import <AWSDynamoDB/AWSDynamoDB.h>
    #import <AWSSQS/AWSSQS.h>
    #import <AWSSNS/AWSSNS.h>

Where Do I Go from Here?

For more information about the AWS SDK for iOS, including a complete list of supported AWS products, go to http://aws.amazon.com/sdkforios.

Other Resources

Document Conventions
Terms of UseDid this page help you?  Yes | No |  Tell us about it...