mxalbert1996 / aws-mobile-appsync-sdk-android Goto Github PK

The AWS AppSync SDK for Android enables you to access your AWS AppSync backend and perform operations like queries, mutations, and subscription. The SDK also includes support for offline operations. This SDK is derrived from 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.

1. A sample app using the events sample schema can be found here: https://github.com/aws-samples/aws-mobile-appsync-events-starter-android

Step by step documentation can be found here: https://aws-amplify.github.io/docs/android/api

In the project's build.gradle, add a dependency to the dependencies inside the buildscript block:

classpath 'com.amazonaws:aws-android-sdk-appsync-gradle-plugin:3.1.1'

Also, add the maven plugins repository to your repositories.

Do this for the repositories block under buildscript:

buildscript {
    repositories {
        // Add this maven block.
        maven {
            url "https://plugins.gradle.org/m2/"
        }
        google()
        jcenter()
    }
}

And also under allprojects, too:

allprojects {
    repositories {
        // Add this maven block.
        maven {
            url "https://plugins.gradle.org/m2/"
        }
        google()
        jcenter()
    }
}

Sample project's build.gradle

// Top-level build file where you can add configuration options common to all sub-projects/modules.
buildscript {
    repositories {
        maven {
            url "https://plugins.gradle.org/m2/"
        }
        google()
        jcenter()
    }

    dependencies {
        classpath 'com.android.tools.build:gradle:4.0.1'
        classpath 'com.amazonaws:aws-android-sdk-appsync-gradle-plugin:3.1.1'
    }
}

allprojects {
    repositories {
        maven {
            url "https://plugins.gradle.org/m2/"
        }
        google()
        jcenter()
    }
}

... other stuff ...

In the app's build.gradle, add the following plugin:

apply plugin: 'com.amazonaws.appsync'

Add the following dependency:

implementation 'com.amazonaws:aws-android-sdk-appsync:3.1.1'

Sample app's build.gradle

apply plugin: 'com.android.application'
apply plugin: 'com.amazonaws.appsync'

android {
    // Typical items
}

dependencies {
    // Typical dependencies
    implementation 'com.amazonaws:aws-android-sdk-appsync:3.1.1'
}

To determine if the device is offline, add permissions to access the network state:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

To interact with AppSync, your client needs to define GraphQL queries and mutations.

For example, create a file named ./app/src/main/graphql/com/amazonaws/demo/posts/posts.graphql:

query GetPost($id:ID!) {
    getPost(id:$id) {
        id
        title
        author
        content
        url
        version
    }
}

mutation AddPost($id: ID!, $author: String!, $title: String, $content: String, $url: String, $ups: Int!, $downs: Int!, $expectedVersion: Int!) {
    putPost(id: $id, author: $author, title: $title, content: $content, url: $url, ups: $ups, downs: $downs, version: $expectedVersion) {
        id
        title
        author
        url
        content
    }
}

Next, fetch the schema.json file from the AppSync console and place it alongside the posts.graphql file:

./app/src/main/graphql/com/amazonaws/demo/posts/schema.json

Now build the project and the generated source files will be available to use within the app. They will not show up in your source directory, but are added in the build path.

AWSAppSyncClient client = AWSAppSyncClient.builder()
    .context(context)
    .apiKey(new BasicAPIKeyAuthProvider(Constants.APPSYNC_API_KEY)) // API Key based authorization
    .region(Constants.APPSYNC_REGION)
    .serverUrl(Constants.APPSYNC_API_URL)
    .build();

Alternatively, you can use the awsconfiguration.json file to supply the configuration information required to create a AWSAppSyncClient object.

Create a file named awsconfiguration.json under your app's res/raw directory.

{
    "AppSync": {
        "Default": {
            "ApiUrl": "YOUR-GRAPHQL-ENDPOINT",
            "Region": "us-east-1",
            "ApiKey": "YOUR-API-KEY",
            "AuthMode": "API_KEY"
        }
    }
}

The AWSConfiguration represents the configuration information present in awsconfiguration.json file. By default, the information under Default section will be used.

AWSAppSyncClient client = AWSAppSyncClient.builder()
    .context(context)
    .awsConfiguration(new AWSConfiguration(context))
    .build();

You can override the Default configuration by using the AWSConfiguration#setConfiguration() method.

{
    "AppSync": {
        "Default": {
            "ApiUrl": "YOUR-GRAPHQL-ENDPOINT",
            "Region": "us-east-1",
            "ApiKey": "YOUR-API-KEY",
            "AuthMode": "API_KEY"
        },
        "Custom": {
            "ApiUrl": "YOUR-GRAPHQL-ENDPOINT",
            "Region": "us-east-2",
            "ApiKey": "YOUR-API-KEY",
            "AuthMode": "API_KEY"
        }
   }
}

AWSConfiguration awsConfig = new AWSConfiguration(context);
awsConfig.setConfiguration("Custom");

AWSAppSyncClient client = AWSAppSyncClient.builder()
    .context(context)
    .awsConfiguration(awsConfig)
    .build();

When making calls to AWS AppSync, there are several ways to authenticate those calls. API key authorization (API_KEY) is the simplest way to onboard. After onboarding, we recommend you use one of the other modes:

1. Amazon IAM (AWS_IAM)
2. Amazon Cognito UserPools (AMAZON_COGNITO_USER_POOLS)
3. Any OpenID Connect Provider (OPENID_CONNECT)

For authorization using the API key, update the awsconfiguration.json file and code snippet as follows:

Add the following snippet to your awsconfiguration.json file.

{
    "AppSync": {
        "Default": {
            "ApiUrl": "YOUR-GRAPHQL-ENDPOINT",
            "Region": "us-east-1",
            "ApiKey": "YOUR-API-KEY",
            "AuthMode": "API_KEY"
        }
    }
}

In order to use the information in the Default section from awsconfiguration.json file, add the following code:

AWSAppSyncClient client = AWSAppSyncClient.builder()
    .context(context)
    .awsConfiguration(new AWSConfiguration(context))
    .build();

For authorization using Amazon IAM credentials, using Amazon IAM or Amazon STS or Amazon Cognito, update the awsconfiguration.json file and code snippet as follows:

Add the following snippet to your awsconfiguration.json file.

{
    "CredentialsProvider": {
        "CognitoIdentity": {
            "Default": {
                "PoolId": "YOUR-COGNITO-IDENTITY-POOLID",
                "Region": "us-east-1"
            }
        }
    },
    "AppSync": {
        "Default": {
            "ApiUrl": "YOUR-GRAPHQL-ENDPOINT",
            "Region": "us-east-1",
            "AuthMode": "AWS_IAM"
       }
    }
}

Add the following code to use the information in the Default section from awsconfiguration.json file.

AWSConfiguration awsConfig = new AWSConfiguration(context);

CognitoCachingCredentialsProvider credentialsProvider =
    new CognitoCachingCredentialsProvider(context, awsConfig);

AWSAppSyncClient client = AWSAppSyncClient.builder()
    .context(context)
    .awsConfiguration(awsConfig)
    .credentialsProvider(credentialsProvider)
    .build();

For authorization using the Amazon Cognito UserPools, update the awsconfiguration.json file and code snippet as follows:

Add the following snippet to your awsconfiguration.json file.

{
    "CognitoUserPool": {
        "Default": {
            "PoolId": "POOL-ID",
            "AppClientId": "APP-CLIENT-ID",
            "AppClientSecret": "APP-CLIENT-SECRET",
            "Region": "us-east-1"
        }
    },
    "AppSync": {
        "Default": {
            "ApiUrl": "YOUR-GRAPHQL-ENDPOINT",
            "Region": "us-east-1",
            "AuthMode": "AMAZON_COGNITO_USER_POOLS"
        }
    }
}

Add the following dependency to your app in order to use Amazon Cognito UserPools:

dependencies {
    implementation 'com.amazonaws:aws-android-sdk-cognitoidentityprovider:2.16.12'
}

Add the following code to use the information in the Default section from awsconfiguration.json file.

AWSConfiguration awsConfig = new AWSConfiguration(context);

CognitoUserPool cognitoUserPool = new CognitoUserPool(context, awsConfig);
BasicCognitoUserPoolsAuthProvider basicCognitoUserPoolsAuthProvider =
    new BasicCognitoUserPoolsAuthProvider(cognitoUserPool);

AWSAppSyncClient awsAppSyncClient = AWSAppSyncClient.builder()
    .context(context)
    .awsConfiguration(awsConfig)
    .cognitoUserPoolsAuthProvider(basicCognitoUserPoolsAuthProvider)
    .build();

For authorization using any OIDC (OpenID Connect) Identity Provider, update the awsconfiguration.json file and code snippet as follows:

Add the following snippet to your awsconfiguration.json file.

{
    "AppSync": {
        "Default": {
            "ApiUrl": "YOUR-GRAPHQL-ENDPOINT",
            "Region": "us-east-1",
            "AuthMode": "OPENID_CONNECT"
        }
    }
}

Add the following code to use the information in the Default section from awsconfiguration.json file.

AWSAppSyncClient client = AWSAppSyncClient.builder()
    .context(context)
    .awsConfiguration(new AWSConfiguration(context))
    .oidcAuthProvider(() -> "jwt-token-from-oidc-provider")
    .build();

public void addPost() {
    GraphQLCall.Callback<AddPostMutation.Data> postsCallback = new GraphQLCall.Callback<>() {
        @Override
        public void onResponse(Response<AddPostMutation.Data> response) {
            // Called on a non-UI thread
            runOnUiThread(() -> { /* do stuff on UI thread */ });
        }

        @Override
        public void onFailure(ApolloException failure) {
            // Error handling
        }
    };
    
    AddPostMutation addPostMutation = AddPostMutation.builder()
        .id(UUID.randomUUID().toString())
        .title(title)
        .author(author)
        .url(url)
        .content(content)
        .ups(0)
        .downs(0)
        .expectedVersion(1)
        .build();
        
    client.mutate(addPostMutation).enqueue(postsCallback);
}

This library is licensed under the Apache License 2.0.