Need help with aws-mobile-appsync-sdk-ios?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

233 Stars 107 Forks Other 401 Commits 65 Opened issues


iOS SDK for AWS AppSync.

Services available


Need anything else?

Contributors list

AWS AppSync SDK for iOS

Release CocoaPods Carthage compatible Build Status Documentation Status Swift Twitter Follow

The AWS AppSync SDK for iOS enables you to access your AWS AppSync backend and perform operations like

, and
. The SDK also includes support for offline operations. This SDK is based off of the Apollo project found here. Please log questions for this client SDK in this repo and questions for the AppSync service in the official AWS AppSync forum.


Note: AWS AppSync uses Swift 5.1. Use Xcode 11.0 or greater to build.

Installing the SDK

Via Swift Package Manager

  1. Swift Package Manager is distributed with Xcode. To start adding the AWS SDK to your iOS project, open your project in Xcode and select File > Swift Packages > Add Package Dependency.

  2. Enter the URL for the AWS AppSync SDK for iOS GitHub repo (
    ) into the search bar and click Next.
  3. You'll see the repository rules for which version of the SDK you want Swift Package Manager to install. Choose the first rule, Version, and select Up to Next Major as it will use the latest compatible version of the dependency that can be detected from the

    branch, then click Next.
  4. Choose the AWSAppSync package product and click Finish.

  5. In your source file, import the SDK using

    import AWSAppSync

Via CocoaPods

  1. Add the following line to your Podfile:

    pod 'AWSAppSync', '~> 3.2.1'


    # Uncomment the next line to define a global platform for your project
    # platform :ios, '9.0'

    target 'EventsApp' do

    Comment the next line if you're not using Swift and don't want to use dynamic frameworks


    Pods for EventsApp

    pod 'AWSAppSync', '~> 3.2.1' end

  2. Run

    pod install
    to install the AppSync SDK, then open the
    file (not the
    file) in Xcode.
  3. Now Build your project to start using the SDK. Whenever a new version of the SDK is released you can update by running

    pod update
    and rebuilding your project to use the new features.
  4. In your source file, import the SDK using

    import AWSAppSync

Via Carthage

XCFrameworks (recommended)

Carthage supports XCFrameworks in Xcode 12 or above. Follow the steps below to consume the AWS SDK for iOS using XCFrameworks:

  1. Install Carthage 0.37.0 or greater.

  2. Add the following to your

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

    $ carthage update --use-xcframeworks
  4. On your application targets’ General settings tab, in the Embedded Binaries section, drag and drop each xcframework you want to use from the Carthage/Build folder on disk.

Note: If you are using XCFrameworks (i.e., either Carthage or Dynamic Frameworks), the module

is named as
to work around a Swift issue. To use
, import it as:
    import AWSMobileClientXCF

and use it your app code without the

Frameworks with "fat libraries" (not recommended)

To build platform-specific framework bundles with multiple architectures in the binary, (Xcode 11 and below)

  1. Add the following to your Cartfile:

    github "awslabs/aws-mobile-appsync-sdk-ios"
  2. Once complete, run

    carthage update
    and open the
    with Xcode and chose your
    . In the
    tab, find
    Embedded Binaries
    , then choose the
  3. Choose the

    Add Other
    button, navigate to the
    files under
    Carthage > Build > iOS
    and select
    and its required dependencies:
* AWSAppSync.framework
* AWSCore.framework
* Reachability.framework
* SQLite.framework
* AppSyncRealTimeClient.framework
* Starscream.framework

Do not select the Destination: Copy items if needed check box when prompted.

  1. Under the

    Build Phases
    tab in your
    , 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
    • Show environment variables in build log: Checked
    • Run script only when installing: Not checked
    • Input Files: Empty
    • Output Files: Empty
  2. Now Build your project to start using the SDK. Whenever a new version of the SDK is released you can update by running

    carthage update
    and rebuilding your project to use the new features.

    Note: Currently, the AWSAppSync SDK for iOS builds the Carthage binaries using Xcode 12.0. To consume the pre-built binaries your Xcode version needs to be the same. Otherwise you will have to build the frameworks on your machine by passing

    flag to
    carthage update
  3. In your source file, import the SDK using

    import AWSAppSync


To use the AppSync SDK, you will need to use

amplify codegen
from the AWS Amplify CLI. This command will generate Swift-language files corresponding to your schema. You can interact with these classes instead of operating on GraphQL query documents, directly. You can find the instructions to use the codegen here.


You can find a sample app which uses the AppSync SDK here:


You can find a step by step walk through of setting up codegen backend and accessing it via the iOS client here:


Contributing guidelines are noted here.

Testing Contributions

If you are contributing to the SDK, it is recommended to add some unit and/or integration tests and evaluate against existing tests.

Invoking tests


target is configured to run both Unit and Integration tests in its
configuration. After completing integration test setup following the instructions below, you can run both suites by invoking "Product > Test" (⌘-U) in Xcode.

To run only one suite of tests (Unit or Integration), select the appropriate target from the Scheme selector and invoke "Product > Test" (⌘-U). While Unit tests run much faster than Integration tests, we recommend running both before submitting a PR.

Setting up unit tests

Unit Tests do not require any specific setup and can be run directly from your Xcode IDE. - NOTE: Currently, any test that requires network activity is placed in Integration tests, even if the test hits localhost and not a valid service.

Setting up integration tests

To run integration tests, you will need the following: - Two AppSync API instances with an

schema. - The first AppSync instance should be configured to use a Cognito Identity Pool with unauthenticated identities supported. - The Cognito Identity Pool's unauth role should have the
AppSync Invoke Full Access
permission. - The second instance should be configured to use API Key authentication.

You can get the backend setup by following the steps below:

  1. Create a stack with an AppSync API using API Key authentication
    1. Go to the AWS CloudFormation console.
    2. Click on Create stack and then select Upload a template file. Click Choose File, and navigate to the Cloud Formation Template in this project:
    3. Click Next
    4. Type a "Stack name" and a "ResourceNamePrefix"
      • We recommend using a "ResourceNamePrefix" that makes it easy to tell that the stack is used for AppSync tests, such as
      • Because you will create two stacks for these tests, one using API Key authentication and one using IAM (Cognito Identity) authentication, we recommend selecting a stack name that makes it easy to differentiate between the two, such as
    5. Select the
      Auth Type
    6. Once the stack is complete, click on the Output tab.
    7. Copy the appropriate values to the test configuration file
      • AppSyncApiKey
      • AppSyncEndpointAPIKey
      • AppSyncEndpointAPIKeyRegion
  2. Create another CloudFormation Stack following steps 1-6 above, but select the "IAM" Auth Type in step 5.
    1. Copy the appropriate values to the test configuration file
      • AppSyncEndpoint
      • AppSyncRegion
      • CognitoIdentityPoolId
      • CognitoIdentityPoolRegion
      • BucketName
      • BucketRegion
      • AppSyncMultiAuthAPIKey

Note: You must either provide all values in the

or in code. There is no mechanism to handle partial overrides of one source with the other. All values must be specified before running the integration tests.

Option 1: Use a test configuration file

Add a file

(see sample below) in the
folder and replace the values for
and regions if required:
  "AppSyncEndpoint": "",
  "AppSyncRegion": "us-east-1",
  "CognitoIdentityPoolId": "us-east-1:abcd1234-1234-12324-b4b7-aaa0c0831234",
  "CognitoIdentityPoolRegion": "us-east-1",
  "AppSyncEndpointAPIKey": "",
  "AppSyncEndpointAPIKeyRegion": "us-east-1",
  "AppSyncAPIKey": "da2-sad3lkh23422",
  "BucketName": "bucketName",
  "BucketRegion": "us-east-1",
  "AppSyncMultiAuthAPIKey": "da2-sd34s5ffxz"

Note: The

endpoint uses
based auth, while
uses the
based auth.

Option 2: Edit defaults in source code

Edit the file

with appropriate values.

Now you should be able to run the integration tests by invoking "Product > Test" (⌘-U) in Xcode.


This library is licensed under the Amazon Software License.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.