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

awslabs
233 Stars 107 Forks Other 401 Commits 65 Opened issues

Description

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

Queries
,
Mutations
, and
Subscriptions
. 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.

Setup

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 (

    https://github.com/awslabs/aws-mobile-appsync-sdk-ios
    ) 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

    main
    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'
    

    Example:

    # 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

    use_frameworks!

    Pods for EventsApp

    pod 'AWSAppSync', '~> 3.2.1' end

  2. Run

    pod install
    to install the AppSync SDK, then open the
    .xcworkspace
    file (not the
    .xcodeproj
    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

    Cartfile
    :
    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

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

and use it your app code without the

XCF
suffix.
    AWSMobileClient.default.initialize() 
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
    *.xcworkspace
    with Xcode and chose your
    Target
    . In the
    General
    tab, find
    Embedded Binaries
    , then choose the
    +
    button.
  3. Choose the

    Add Other
    button, navigate to the
    AWS.framework
    files under
    Carthage > Build > iOS
    and select
    AWSAppSync.framework
    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
    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.
    bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/AWSCore.framework/strip-frameworks.sh"
    

    Options:

    • 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

    --no-use-binaries
    flag to
    carthage update
    command.
  3. In your source file, import the SDK using

    import AWSAppSync
    .

Codegen

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.

Sample

You can find a sample app which uses the AppSync SDK here: https://github.com/aws-samples/aws-mobile-appsync-events-starter-ios

Documentation

You can find a step by step walk through of setting up codegen backend and accessing it via the iOS client here: https://docs.amplify.aws/sdk/api/graphql/q/platform/ios

Contributing

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

The

AWSAppSync
target is configured to run both Unit and Integration tests in its
Test
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

Posts
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:
      AWSAppSyncIntegrationTests/ConsoleResources/appsync-integrationtests-cloudformation.yaml
    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
        AppSyncTest
        .
      • 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
        AppSyncTest-APIKey
        and
        AppSyncTest-IAM
        .
    5. Select the
      ApiKey
      Auth Type
    6. Once the stack is complete, click on the Output tab.
    7. Copy the appropriate values to the test configuration file
      AppSyncIntegrationTests/appsync_test_credentials.json
      :
      • 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
      AppSyncIntegrationTests/appsync_test_credentials.json
      :
      • AppSyncEndpoint
      • AppSyncRegion
      • CognitoIdentityPoolId
      • CognitoIdentityPoolRegion
      • BucketName
      • BucketRegion
      • AppSyncMultiAuthAPIKey

Note: You must either provide all values in the

AppSyncIntegrationTests/appsync_test_credentials.json
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

appsync_test_credentials.json
(see sample below) in the
AWSAppSyncIntegrationTests
folder and replace the values for
AppSyncEndpoint
,
CognitoIdentityPoolId
,
AppSyncEndpointAPIKey
,
AppSyncAPIKey
and regions if required:
{
  "AppSyncEndpoint": "https://iambasedendpoint.appsync-api.us-east-1.amazonaws.com/graphql",
  "AppSyncRegion": "us-east-1",
  "CognitoIdentityPoolId": "us-east-1:abcd1234-1234-12324-b4b7-aaa0c0831234",
  "CognitoIdentityPoolRegion": "us-east-1",
  "AppSyncEndpointAPIKey": "https://apikeybasedendpoint.appsync-api.us-east-1.amazonaws.com/graphql",
  "AppSyncEndpointAPIKeyRegion": "us-east-1",
  "AppSyncAPIKey": "da2-sad3lkh23422",
  "BucketName": "bucketName",
  "BucketRegion": "us-east-1",
  "AppSyncMultiAuthAPIKey": "da2-sd34s5ffxz"
}

Note: The

AppSyncEndpointAPIKey
endpoint uses
API_KEY
based auth, while
AppSyncEndpoint
uses the
AWS_IAM
based auth.

Option 2: Edit defaults in source code

Edit the file

AWSAppSyncTestCommon/AppSyncClientTestConfigurationDefaults
with appropriate values.

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

License

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.