aws-mobile-appsync-sdk-ios

by awslabs

iOS SDK for AWS AppSync.

225 Stars 98 Forks Last release: about 2 months ago (3.1.6) Other 346 Commits 45 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

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 CocoaPods

  1. Add the following line to your Podfile:

    pod 'AWSAppSync', '~> 3.1.6'
    

    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.1.6' 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

  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 11.5. 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](https://aws-amplify.github.io/docs/cli/codegen?sdk=ios) which helps generate a strongly typed API for your schema. You can find the instructions to use the codegen here: https://aws-amplify.github.io/docs/ios/api

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://aws-amplify.github.io/docs/ios/api

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.