The AWS SDK for iOS provides a library and documentation for developers to build connected mobile applications using AWS.
- Authentication: APIs and building blocks for developers who want to create user authentication experiences.
- Analytics: Easily collect analytics data for your app. Analytics data includes user sessions and other custom events that you want to track in your app.
- API: Provides a simple solution when making HTTP requests. It provides an automatic, lightweight signing process which complies with AWS Signature Version 4.
- Storage: Provides a simple mechanism for managing user content for your app in public, protected or private storage buckets.
- Push Notifications: Allows you to integrate push notifications in your app with Amazon Pinpoint targeting and campaign management support.
- PubSub: Provides connectivity with cloud-based message-oriented middleware.
- Generated AWS Service Interfaces: Provides direct interaction with any AWS service.
Visit our Web Site to learn more about Amplify Framework.
To get started with the AWS SDK for iOS, check out the Developer Guide 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 9.2 or later
- iOS 8 or later
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:
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.
-
The AWS Mobile SDK for iOS is available through CocoaPods. If you have not installed CocoaPods, install CocoaPods by running the command:
$ gem install cocoapods $ pod setup
Depending on your system settings, you may have to use
sudo
for installingcocoapods
as follows:$ sudo gem install cocoapods $ pod setup
-
In your project directory (the directory where your
*.xcodeproj
file is), create a plain text file namedPodfile
(without any file extension) and add the lines below. ReplaceYourTarget
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
-
Then run the following command:
$ pod install
-
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:ld: library not found for -lPods-AWSCore clang: error: linker command failed with exit code 1 (use -v to see invocation)
-
Install the latest version of Carthage.
-
Add the following to your
Cartfile
:github "aws-amplify/aws-sdk-ios"
-
Then run the following command:
$ carthage update
-
With your project open in Xcode, select your Target. Under General tab, find Embedded Binaries and then click the + button.
-
Click the Add Other... button, navigate to the
AWS<#ServiceName#>.framework
files underCarthage
>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
-
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
Note: Currently, the AWS SDK for iOS builds the Carthage binaries using Xcode 10.1.0. To consume the pre-built binaries your Xcode version needs to be the same, else you have to build the frameworks on your machine by passing
--no-use-binaries
flag tocarthage update
command.
-
Download the SDK from our AWS Mobile SDK page. The SDK is stored in a compressed file archive named
aws-ios-sdk-#.#.#
(where#.#.#
represents the version number, so for version 2.7.0, the filename isaws-ios-sdk-2.7.0
). -
With your project open in Xcode, select your Target. Under General tab, find Embedded Binaries and then click the + button.
-
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
-
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
When we release a new version of the SDK, you can pick up the changes as described below.
-
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
andPods/
then runpod install
to cleanly install the SDK.
-
Run the following command in your project directory. Carthage automatically picks up the new changes.
$ carthage update
-
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
-
Follow the installation process above to include the new version of the SDK.
-
Import the AWSCore header in the application delegate.
import AWSCore
-
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.default().defaultServiceConfiguration = configuration
-
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
-
Make a call to the AWS services.
let dynamoDB = AWSDynamoDB.default() let listTableInput = AWSDynamoDBListTablesInput() dynamoDB.listTables(listTableInput!).continueWith { (task:AWSTask<AWSDynamoDBListTablesOutput>) -> Any? in if let error = task.error as? NSError { print("Error occurred: \(error)") return nil } let listTablesOutput = task.result 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.
-
Import the AWSCore header in the application delegate.
@import AWSCore;
-
Create a default service configuration by adding the following code snippet in the
application:didFinishLaunchingWithOptions:
application delegate method.AWSCognitoCredentialsProvider *credentialsProvider = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:CognitoRegionType identityPoolId:CognitoIdentityPoolId]; AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:DefaultServiceRegionType credentialsProvider:credentialsProvider]; AWSServiceManager.defaultServiceManager.defaultServiceConfiguration = configuration;
-
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;
-
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.
With native AWSTask support in the SDK for iOS, you can chain async requests instead of nesting them. It makes the logic cleaner, while keeping the code more readable. Read Working with AWSTask to learn how to use AWSTask.
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
Swift
AWSDDLog.sharedInstance.logLevel = .verbose
The following logging level options are available:
.off
.error
.warning
.info
.debug
.verbose
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 Off
before publishing to the Apple App Store.
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
The AWS Mobile SDK for iOS zip file 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.
-
Open the Mac OS X terminal and go to the directory containing the expanded archive. For example:
$ cd ~/Downloads/aws-ios-sdk-2.7.0
Note: Remember to replace 2.7.0 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 Mobile SDK for iOS v2.7.0 Documentation (where '2.7.0' is the appropriate version number).
Visit our GitHub Issues to leave feedback and to connect with other users of the SDK.
Amazon Web Services
See the LICENSE file for more info.