Set Up the SDK for iOS

To get started with the AWS Mobile SDK for iOS you can set up the SDK and build a new project, or you can 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 SDK, install the following on your development machine:

  • Xcode 7 or later
  • iOS 8 or later

You can view the source code in the AWS Mobile SDK for iOS GitHub repository.

Include the AWS Mobile SDK for iOS in an Existing Application#

The samples included with the SDK are standalone projects that are already set up. You can also integrate the SDK into your own existing project. Choose one of the following three ways to import the SDK into your project:

  • CocoaPods
  • Carthage
  • Dynamic Frameworks

Note

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. Install CocoaPods by running the following commands from the folder containing your projects *.xcodeproj file.

    $ gem install cocoapods

    ..note:: Depending on your system settings, you may need to run the command as administrator using sudo, as follows:

    $ sudo gem install cocoapods

    $ pod setup

    $ pod init

  2. In your project directory (the directory where your *.xcodeproj file is), open the empty text file named Podfile (without a file extension) and add the following lines to the file. Replace myAppName with your app name. You can also remove pods for services that you don't use. For example, if you don't use AWSAutoScaling, remove or do not include the AWSAutoScaling pod.

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

    $ pod install

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

    Note

    Do not open *.xcodeproj. Opening this project file instead of a workspace results in an error.

Carthage
  1. Install the latest version of Carthage.

  2. Add the following to your Cartfile:

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

    $ carthage update

  4. With your project open in Xcode, choose your Target. In the General tab, find Embedded Binaries, then choose the + button.

  5. Choose the Add Other button, navigate to the AWS<#ServiceName#>.framework files under Carthage > Build > iOS and select AWSCore.framework and the other service frameworks you require. Do not select 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
    • AWSLex.framework
    • AWSMachineLearning.framework
    • AWSMobileAnalytics.framework
    • AWSPinpoint.framework
    • AWSPolly.framework
    • AWSRekognition.framework
    • AWSS3.framework
    • AWSSES.framework
    • AWSSimpleDB.framework
    • AWSSNS.framework
    • AWSSQS.framework
  6. Under the Build Phases tab in your Target, choose the + button on the top left and then select New Run Script Phase.

# 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. For version 2.5.0, the filename is aws-ios-sdk-2.5.0.

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

  3. Choose Add Other. Navigate to the AWS<#ServiceName#>.framework files and select AWSCore.framework and the other service frameworks you require. Select 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
    • AWSLex.framework
    • AWSMachineLearning.framework
    • AWSMobileAnalytics.framework
    • AWSPinpoint.framework
    • AWSPolly.framework
    • AWSRekognition.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.

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

This section describes how to pick up changes when a new SDK is released.

CocoaPods

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

$ pod update

Note

If your pod update command fails, 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 updates your frameworks with the new changes.

$ carthage update

Frameworks
  1. In Xcode select the following frameworks in Project Navigator and press the delete key. 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
    • AWSLex.framework
    • AWSMachineLearning.framework
    • AWSMobileAnalytics.framework
    • AWSPinpoint.framework
    • AWSPolly.framework
    • AWSRekognition.framework
    • AWSS3.framework
    • AWSSES.framework
    • AWSSimpleDB.framework
    • AWSSNS.framework
    • AWSSQS.framework
  2. Follow the manual Frameworks installation process to include the new version of the SDK.

Preparing to Work with ATS#

The App Transport Security (ATS) feature, in the iOS 9.0 SDK or later, might impact how your apps interact with some AWS services.

If you compile your apps with the iOS 9.0 SDK (or Xcode 7) or later, there are additional steps you must complete for your app to successfully connect with any AWS service your app calls. For more information, see Preparing Your App to Work with ATS.

AWS Credentials#

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

Alternatively, you can use AWS Identity and Access Management (IAM) in combination with the AWS Security Token Service AssumeRole API. If you choose IAM, ensure that your role's policy is minimally scoped so that it can only perform the required actions for the service being used.

Import and Call SDK APIs with AWS Credentials#

This section is included to give an overview of how you can connect your app to AWS services. For details about calling a specific service, see the left hand menu.

  1. Import the AWSCore header in the application delegate.

    Swift
    import AWSCore
    import AWSCognito
    
    Objective-C
    #import <AWSCore/AWSCore.h>
    #import <AWSCognito/AWSCognito.h>
    

    Amazon Cognito APIs provide AWS identity services, and are included because they are used in the implementation of most mobile app features through AWS.

  2. Create a default service configuration and establish an AWS identity provider by adding the following code snippet in the application:didFinishLaunchingWithOptions: application delegate method.

    Swift
    let credentialProvider = AWSCognitoCredentialsProvider(regionType: .USEast1, identityPoolId: "YourIdentityPoolId")
    let configuration = AWSServiceConfiguration(region: .USEast1, credentialsProvider: credentialProvider)
    AWSServiceManager.default().defaultServiceConfiguration = configuration
    
    Objective-C
    AWSCognitoCredentialsProvider *credentialsProvider = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1
    identityPoolId:@"YourIdentityPoolId"];
    
    AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSEast1 credentialsProvider:credentialsProvider];
    
    AWSServiceManager.defaultServiceManager.defaultServiceConfiguration = configuration;
    

    The value for YourIdentityPoolId is specific to the Amazon Cognito identity pool you create. To learn more, see Amazon Cognito for iOS.

  3. Include import statements for each AWS service your app will call.

    Swift
    import AWSS3
    import AWSDynamoDB
    import AWSSQS
    import AWSSNS
    ...
    
    Objective-C
    #import <AWSCore/AWSCore.h>
    #import <AWSS3/AWSS3.h>
    #import <AWSDynamoDB/AWSDynamoDB.h>
    #import <AWSSQS/AWSSQS.h>
    #import <AWSSNS/AWSSNS.h>
    ...
    
  4. Make a call to your AWS service. In the example below, the call is to Amazon S3 through the SDKs AWSS3TransferManger API.

    Swift
    let transferManager = AWSS3TransferManager.default()
    
    let uploadRequest = AWSS3TransferManagerUploadRequest()
    uploadRequest.bucket = "myBucket"
    uploadRequest.key = "myTestFile.txt"
    uploadRequest.body = uploadingFileURL
    uploadRequest.contentLength = fileSize
    
    transferManager.upload(uploadRequest).continueWith(executor: AWSExecutor.mainThread(), block: { (task:AWSTask<AnyObject>) -> Any? in
        // Do something with the response
    })
    
    Objective-C
    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, named with the convention of adding default to the framework name. AWSS3TransferManager.default() (Swift) or defaultS3TransferManager (Objective-C) are examples in the preceding code snippet.

    This singleton method creates a service client with defaultServiceConfiguration, which you initialized in the application delegate during a preceding step in this section. The method maintains a strong reference to the client.

Logging#

As of version 2.5.4 of this SDK, logging utilizes CocoaLumberjack, a flexible, fast, open source logging framework. It supports many capabilities including the ability to set logging level per output target, for instance, concise messages logged to the console and verbose messages to a log file.

CocoaLumberjack logging levels are additive such that when the level is set to verbose, all messages from the levels below verbose are logged. It is also possible to set custom logging to meet your needs. For more information, see CocoaLumberjack

Changing Logging Level#

You can change the logging level to suit the phase of your development cycle by importing AWSCore and calling:

Swift

AWSDDLog.sharedInstance().logLevel = .verbose

The following logging level options are available:

  • .off
  • .error
  • .warning
  • .info
  • .debug
  • .verbose

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

Objective-C

[AWSDDLog sharedInstance].logLevel = AWSDDLogLevelVerbose;

The following logging level options are available:

  • AWSDDLogLevelOff
  • AWSDDLogLevelError
  • AWSDDLogLevelWarning
  • AWSDDLogLevelInfo
  • AWSDDLogLevelDebug
  • AWSDDLogLevelVerbose

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

Targeting Log Output#

CocoaLumberjack can direct logs to file or used as a framework that integrates with the Xcode console.

To initialize logging to files, use the following code:

Swift
let fileLogger: AWSDDFileLogger = AWSDDFileLogger() // File Logger
fileLogger.rollingFrequency = TimeInterval(60*60*24)  // 24 hours
fileLogger.logFileManager.maximumNumberOfLogFiles = 7
AWSDDLog.add(fileLogger)
Objective-C
AWSDDFileLogger *fileLogger = [[AWSDDFileLogger alloc] init]; // File Logger
fileLogger.rollingFrequency = 60 * 60 * 24; // 24 hour rolling
fileLogger.logFileManager.maximumNumberOfLogFiles = 7;
[AWSDDLog addLogger:fileLogger];

To initialize logging to your Xcode console, use the following code:

Swift
AWSDDLog.add(AWSDDTTYLogger.sharedInstance()) // TTY = Xcode console
Objective-C
[AWSDDLog addLogger:[AWSDDTTYLogger sharedInstance]]; // TTY = Xcode console

To learn more, see CocoaLumberjack on GitHub.

Sample Apps#

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

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

AWS services demonstrated:

Amazon Cognito Sync Sample (Swift, Objective-C)

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

AWS services demonstrated:

Amazon DynamoDB Object Mapper Sample (Swift, Objective-C)

This sample demonstrates how to insert, update, delete, query items using DynamoDBObjectMapper.

AWS services demonstrated:

Amazon S3 Transfer Utility Sample (Swift, Objective-C)

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

AWS services demonstrated:

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

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

AWS services demonstrated:

Install the Reference Documentation in Xcode#

The AWS Mobile 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 macOS terminal.

To install the DocSet for Xcode#

Open the macOS terminal and go to the directory containing the expanded archive. For example:

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

Note

Replace 2.5.0 in the preceding example with the version number of the AWS Mobile 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 Mobile SDK for iOS v2.0 Documentation (where '2.0' is the appropriate version number).