PDF Edit on GitHub

Set Up the SDK for iOS

To get started with the AWS SDK for iOS, you can set up the SDK and start building a new project, or you integrate the SDK in an existing project. You can also run the samples to get a sense of how the SDK works.

To use the AWS SDK for iOS, you will need the following installed on your development machine:

  • Xcode 7 or later
  • iOS 8 or later

At the AWS GitHub repo, you can check out the SDK source code.

Include the SDK for iOS in an Existing Application

The samples included with the SDK for iOS are standalone projects that are already set up for you. You can also integrate the SDK for iOS with your own existing project. There are three ways to import the AWS Mobile SDK for iOS into your project:

  • CocoaPods
  • Carthage
  • Dynamic Frameworks

You should use one of these three ways to import the AWS Mobile SDK but not multiple. Importing the SDK in multiple ways loads duplicate copies of the SDK into the project and causes compiler errors.

CocoaPods

  1. The AWS Mobile SDK for iOS is available through CocoaPods. If you have not installed CocoaPods, install it by running the command:

    $ gem install cocoapods

    $ pod setup

    Depending on your system settings, you may have to use sudo for installing cocoapods as follows:

    $ sudo gem install cocoapods

    $ pod setup

  2. In your project directory (the directory where your *.xcodeproj file is), create a plain text file named Podfile (without any file extension) and add the lines below. Replace YourTarget with your actual target name.:

    source 'https://github.com/CocoaPods/Specs.git'
    
    platform :ios, '8.0'
    use_frameworks!
    
    target :'YourTarget' do
        pod 'AWSAutoScaling'
        pod 'AWSCloudWatch'
        pod 'AWSCognito'
        pod 'AWSCognitoIdentityProvider'
        pod 'AWSDynamoDB'
        pod 'AWSEC2'
        pod 'AWSElasticLoadBalancing'
        pod 'AWSIoT'
        pod 'AWSKinesis'
        pod 'AWSLambda'
        pod 'AWSMachineLearning'
        pod 'AWSMobileAnalytics'
        pod 'AWSS3'
        pod 'AWSSES'
        pod 'AWSSimpleDB'
        pod 'AWSSNS'
        pod 'AWSSQS'
    end
    
  3. Then run the following command:

    $ pod install

  4. Open up *.xcworkspace with Xcode and start using the SDK.

Note

Do NOT use *.xcodeproj. If you open up a project file instead of a workspace, you receive an error.

Carthage

  1. Install the latest version of Carthage.

  2. Add the following to your Cartfile:

    github "aws/aws-sdk-ios"
    
  3. Then run the following command:

    $ carthage update

  4. With your project open in Xcode, select your Target. Under General tab, find Embedded Binaries and then click the + button.

  5. Click the Add Other... button, navigate to the AWS<#ServiceName#>.framework files under Carthage > Build > iOS and select them. Do not check the Destination: Copy items if needed checkbox when prompted.

    • AWSCore.framework
    • AWSAutoScaling.framework
    • AWSCloudWatch.framework
    • AWSCognito.framework
    • AWSCognitoIdentityProvider.framework
    • AWSDynamoDB.framework
    • AWSEC2.framework
    • AWSElasticLoadBalancing.framework
    • AWSIoT.framework
    • AWSKinesis.framework
    • AWSLambda.framework
    • AWSMachineLearning.framework
    • AWSMobileAnalytics.framework
    • AWSS3.framework
    • AWSSES.framework
    • AWSSimpleDB.framework
    • AWSSNS.framework
    • AWSSQS.framework
  6. Under the Build Phases tab in your Target, click the + button on the top left and then select New Run Script Phase. Then setup the build phase as follows. Make sure this phase is below the Embed Frameworks phase.:

    Shell /bin/sh
    
    bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/AWSCore.framework/strip-frameworks.sh"
    
    Show environment variables in build log: Checked
    Run script only when installing: Not checked
    
    Input Files: Empty
    Output Files: Empty
    

Frameworks

  1. Download the SDK from http://aws.amazon.com/mobile/sdk. The SDK is stored in a compressed file archive named aws-ios-sdk-#.#.# (where ‘#.#.#’ represents the version number, so for version 2.2.2, the filename is aws-ios-sdk-2.2.2).

  2. With your project open in Xcode, select your Target. Under General tab, find Embedded Binaries and then click the + button.

  3. Click the Add Other... button, navigate to the AWS<#ServiceName#>.framework files and select them. Check the Destination: Copy items if needed checkbox when prompted.

    • AWSCore.framework
    • AWSAutoScaling.framework
    • AWSCloudWatch.framework
    • AWSCognito.framework
    • AWSCognitoIdentityProvider.framework
    • AWSDynamoDB.framework
    • AWSEC2.framework
    • AWSElasticLoadBalancing.framework
    • AWSIoT.framework
    • AWSKinesis.framework
    • AWSLambda.framework
    • AWSMachineLearning.framework
    • AWSMobileAnalytics.framework
    • AWSS3.framework
    • AWSSES.framework
    • AWSSimpleDB.framework
    • AWSSNS.framework
    • AWSSQS.framework
  1. Under the Build Phases tab in your Target, click the + button on the top left and then select New Run Script Phase. Then setup the build phase as follows. Make sure this phase is below the Embed Frameworks phase.:

    Shell /bin/sh
    
    bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/AWSCore.framework/strip-frameworks.sh"
    
    Show environment variables in build log: Checked
    Run script only when installing: Not checked
    
    Input Files: Empty
    Output Files: Empty
    

Update the SDK to a Newer Version

When a new version of the SDK is released, you can pick up the changes as described below.

CocoaPods

Run the following command in your project directory. CocoaPods automatically picks up the new changes.

$ pod update

Note

If your pod is having an issue, you can delete Podfile.lock and Pods/ and then run pod install to cleanly install the SDK.

Carthage

Run the following command in your project directory. Carthage automatically picks up the new changes.

$ carthage update

Frameworks

  1. In Xcode select the following frameworks in Project Navigator and hit delete on your keyboard. Then select Move to Trash:

    • AWSCore.framework
    • AWSAutoScaling.framework
    • AWSCloudWatch.framework
    • AWSCognito.framework
    • AWSCognitoIdentityProvider.framework
    • AWSDynamoDB.framework
    • AWSEC2.framework
    • AWSElasticLoadBalancing.framework
    • AWSIoT.framework
    • AWSKinesis.framework
    • AWSLambda.framework
    • AWSMachineLearning.framework
    • AWSMobileAnalytics.framework
    • AWSS3.framework
    • AWSSES.framework
    • AWSSimpleDB.framework
    • AWSSNS.framework
    • AWSSQS.framework
  2. Follow the installation process above to include the new version of the SDK.

Preparing iOS 9 Apps

The release of iOS 9 includes changes that might impact how your apps interact with some AWS services. If you compile your apps with Apple’s iOS 9 SDK (or Xcode 7), there are additional steps you must complete for your app to successfully connect with any AWS service you need to call. For more information, see Preparing Your Apps for iOS 9.

Getting Started with Swift

  1. Import the AWSCore header in the application delegate.

    import AWSCore
    
  2. Create a default service configuration by adding the following code snippet in the application:didFinishLaunchingWithOptions: application delegate method.

    let credentialsProvider = AWSCognitoCredentialsProvider(
        regionType: CognitoRegionType,
        identityPoolId: CognitoIdentityPoolId)
    let configuration = AWSServiceConfiguration(
        region: DefaultServiceRegionType,
        credentialsProvider: credentialsProvider)
    AWSServiceManager.defaultServiceManager().defaultServiceConfiguration = configuration
    
  3. In Swift file you want to use the SDK, import the appropriate headers for the services you are using. The header file import convention is import AWSServiceName, as in the following examples:

    import AWSS3
    import AWSDynamoDB
    import AWSSQS
    import AWSSNS
    import AWSCognito
    
  4. Make a call to the AWS services.

    let dynamoDB = AWSDynamoDB.defaultDynamoDB()
    let listTableInput = AWSDynamoDBListTablesInput()
    dynamoDB.listTables(listTableInput).continueWithBlock{ (task: AWSTask?) -> AnyObject? in
        if let error = task.error {
            print("Error occurred: \(error)")
            return nil
        }
    
        let listTablesOutput = task.result as AWSDynamoDBListTablesOutput
    
        for tableName in listTablesOutput.tableNames {
            print("\(tableName)")
        }
    
        return nil
    }
    

Note

Most of the service client classes have a singleton method to get a default client. The naming convention is + defaultSERVICENAME (e.g. + defaultDynamoDB in the above code snippet). This singleton method creates a service client with defaultServiceConfiguration, which you set up in step 5, and maintains a strong reference to the client.

Getting Started with Objective-C

  1. Import the AWSCore header in the application delegate:

    #import <AWSCore/AWSCore.h>
    
  2. Create a default service configuration by adding the following code snippet in the application:didFinishLaunchingWithOptions: application delegate method.

    AWSCognitoCredentialsProvider *credentialsProvider = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1
            identityPoolId:CognitoPoolID];
    
    AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSEast1
            credentialsProvider:credentialsProvider];
    
    AWSServiceManager.defaultServiceManager.defaultServiceConfiguration = configuration;
    
  3. Import service headers where you want to use the services. The header file import convention for frameworks is #import <FRAMEWORKNAME/SERVICENAME.h>, as in the following examples:

    #import <AWSCore/AWSCore.h>
    #import <AWSS3/AWSS3.h>
    #import <AWSDynamoDB/AWSDynamoDB.h>
    #import <AWSSQS/AWSSQS.h>
    #import <AWSSNS/AWSSNS.h>
    #import <AWSCognito/AWSCognito.h>
    
  4. Make a call to the AWS services:

    AWSS3Transfermanager *transferManager = [AWSS3Transfermanager defaultS3TransferManager];
    AWSS3TransferManagerUploadRequest *uploadRequest = [AWSS3TransferManagerUploadRequest new];
    uploadRequest.bucket = yourBucket;
    uploadRequest.key = yourKey;
    uploadRequest.body = yourDataURL;
    uploadRequest.contentLength = [NSNumber numberWithUnsignedLongLong:fileSize];
    
    [[transferManager upload:uploadRequest] continueWithBlock:^id(AWSTask *task) {
        // Do something with the response
        return nil;
    }];
    

    Note

    Most of the service client classes have a singleton method to get a default client. The naming convention is + defaultSERVICENAME (e.g. + defaultS3TransferManager in the above code snippet). This singleton method creates a service client with defaultServiceConfiguration, which you set up in step 5, and maintains a strong reference to the client.

Logging

Changing log levels during development may make debugging easier. You can change the log level by importing AWSCore.h and calling:

Swift

AWSLogger.defaultLogger().logLevel = .Verbose

The following logging level options are available:

  • .None
  • .Error
  • .Warn
  • .Info
  • .Debug (This is the default.)
  • .Verbose

Objective-C

[AWSLogger defaultLogger].logLevel = AWSLogLevelVerbose;

The following logging level options are available:

  • AWSLogLevelNone
  • AWSLogLevelError
  • AWSLogLevelWarn
  • AWSLogLevelInfo
  • AWSLogLevelDebug (This is the default.)
  • AWSLogLevelVerbose

We recommend setting the log level to None before publishing to the Apple App Store.

Get AWS Credentials with Amazon Cognito or AWS Identity and Access Management

We recommend using Amazon Cognito as your credential provider to access AWS services from your mobile app. Cognito provides a secure mechanism to access AWS services without having to embed credentials in your app. To learn more, see Authenticate Users with Amazon Cognito Identity.

Alternatively, you can use AWS Identity and Access Management (IAM). If you choose IAM, ensure that your role’s policy is minimally scoped so that it can only perform the desired actions for the service being used.

Sample Apps

The AWS SDK for iOS includes sample apps that demonstrate common use cases.

Cognito Your User Pools Sample (Objective-C)

This sample demonstrates how sign up and sign in a user to display an authenticated portion of your app.

Cognito Sync Sample (Swift, Objective-C)

This sample demonstrates how to securely manage and sync your mobile app data and create unique identities via login providers including Facebook, Google, and Login with Amazon.

AWS Services Demonstrated:

DynamoDB Object Mapper Sample (Swift, Objective-C)

This sample demonstrates how to insert / update / delete / query items using DynamoDB Object Mapper.

AWS Services Demonstrated:

S3 Transfer Utility Sample (Swift, Objective-C)

This sample demonstrates how to use the Amazon S3 Transfer Utility to download / upload files.

AWS Services Demonstrated:

SNS Mobile Push and Mobile Analytics Sample (Swift, Objective-C)

This sample demonstrates how to set up Amazon SNS Mobile Push and record events using Amazon Mobile Analytics.

AWS Services Demonstrated:

Install the Reference Documentation in Xcode

The AWS SDK for iOS includes documentation in the DocSets 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

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

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

Note

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

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

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

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/

If Xcode was running during this procedure, restart Xcode. To browse the documentation, go to Help, click Documentation and API Reference, and select AWS SDK for iOS v2.0 Documentation (where ‘2.0’ is the appropriate version number).