Business Productivity

Push Notifications for Android and iOS with Amazon Chime SDK messaging

Overview

Amazon Chime SDK messaging provides building blocks for developers to make it easier to connect communities with secure, scalable, and persistent messaging. In many cases, developers have use cases that require building chat into mobile applications. For example, they may be connecting delivery drivers to customers, doctors to patients, or two people starting to get to know each other on a dating application. To build these experiences, they require an SDK with messaging support for iOS and Android.

Amazon Chime SDK messaging now supports push notifications so users on iOS or Android devices can receive notifications for new messages or calls regardless of whether they have the application open or not. With push notifications, a user can switch applications or lock their mobile device and receive a notification when a new message or call comes in, allowing them to tap the notification and return to the app to continue to the conversation or join the call.

In this blog you will learn how to enable users of your mobile app to receive channel messages as push notifications even when a user does not have your app open using an integration between Amazon Chime SDK messaging and Amazon Pinpoint. Using the demo app, users can turn on push notifications across all channels, for individual channels, or receive notifications only when they are @ mentioned.

Note: Deploying this demo and receiving traffic from the demo created in this post can incur AWS charges.

Architecture

Infrastructure Setup

The diagram below explains the architecture for the mobile demo application that uses Amazon Chime SDK messaging. It creates the following resources in your AWS Account:

Send Message Flow

The diagram below explains how a message, sent in a channel, is delivered as a push notification to your mobile device. Amazon Chime SDK messaging handles converting your message into the appropriate format that Amazon Pinpoint expects for a push notification in order to successfully deliver it to the mobile device.

Prerequisites

For this walkthrough, you should have the following pre-requisites:

Git repository

Clone the git repository for Amazon Chime SDK Sample Apps by executing:

git clone https://github.com/aws-samples/amazon-chime-sdk.git

Android

Install software

  1. Download and Install OpenJDK8
  2. Download and Install Android Studio
  3. Open Android Studio and ensure you have accepted all of the license agreements so that you can start the emulator to run the mobile demo app

Set up project in Firebase Console

  1. Login to the Firebase Console and create a Firebase project by following the Android guide
  2. Follow the step to Register your app with Firebase and when asked for the Android package name, ensure you enter the following value: com.amazonaws.services.chime.sdkdemo
  3. After you click on Register App, download the google-services.json file, using the link provided, and copy it to the apps/chat-android/app/ directory in the cloned Git repository

Fetch credentials for push notifications

  1. Go to the Firebase Console and open your project that you created
  2. Click on the Settings icon beside Project Overview
  3. On the Project Settings page, click on the Cloud Messaging tab
  4. Under Project Credentials, note down the value of Server Key. If you don’t have any Server Key then click on Add Server Key to create one

iOS

Install software

  1. Install Xcode

An Apple Developer account and a physical iOS device will be required

Create an App ID

  1. Log into your Apple Developer account and click Certificates, Identifiers and Profiles
  2. Click the Identifiers tab, create a new App ID, click continue
  3. Specify Description, Bundle ID and select Push Notifications, click continue
  4. Click on Register

Generate a Certificate Signing Request(CSR) from Keychain Access

  1. Launch the Keychain Access application in your Mac OS X and Select Keychain Access -> Certificate Assistant -> Request a Certificate From a Certificate Authority
  2. Enter email address and check the ‘Save to disk’ option, then click Continue
  3. Save the CSR

Create a certificate for Apple Push Notification Service

  1. Login to Apple Developer account and click Certificates, Identifiers and Profiles
  2. Click Certificates tab, click “+” to create a new certificate
  3. Select Apple Push Notification service SSL (Sandbox & Production) for the type and click Continue.
  4. Select the App ID
  5. Upload CSR created from previous step
  6. Download the development certificate

Generate APNS .p12 certificate

  1. Double click Development certificate generated in previous step to add it to Keychain Access.
  2. Go to Keychain Access, select login keychain and My Certificate from side menu. Find the certificate, select both app certificate and the private key, right click to export 2 items
  3. Enter a certificate name, select .p12 as file format
  4. Click Save
  5. Optional – enter a password for certification protection

Note: We are using APNS_SANDBOX for the mobile demo in this blog

Build and Run Demo

In this section, you will learn how to set up the Amazon Chime SDK messaging demo applications for Web and Mobile in your AWS account.

Step 1: Deploy CloudFormation Template

  1. Sign in to the AWS Management Console with your primary account. Switch to the us-east-1 (N. Virginia) Region. Note: The AWS CloudFormation template in this section needs to be launched in US east (N. Virginia) Region.
  2. Click on the Launch Stack image below this sentence to launch a Cloudformation template that will setup the required infrastructure for the Amazon Chime SDK chat demo app in your AWS account.
  3. Click Next.
  4. On the Specify Details page, enter the following information:
    1. DemoName – Unique Demo Name for Amazon Cognito resources, such as ‘ChimeSDKMessagingDemo’
    2. FCMServerKey – The Server Key that you noted down after creating your Android project
    3. APNSPublicCertificate – String version of your APNS Public Certificate
    4. APNSPrivateKey – String version of your APNS Private Key
  5. Choose Next, and then Next on the Configure stack options page.
  6. On the Review page, check the I acknowledge that AWS CloudFormation might create IAM resources check box. Then click Create.
  7. Creating the stack generates 7 outputs- cognitoAppClientId, apiGatewayInvokeUrl, attachmentsS3BucketName, cognitoIdentityPoolId, appInstanceArn, cognitoUserPoolId and pinpointApplicationArn. Note these values for the demo app configuration in the next step

Note: If you cannot successfully supply the certificate and private key for creating your APNS Channel, you can follow the steps here to create via the AWS CLI.

Step 2: Modify config files for demo app

Update Amazon Cognito Config

Go to the file amplifyConfiguration.json and replace the following placeholders with values from the outputs of the CloudFormation stack. The file location for Android and iOS are:

  • Android – app/src/main/res/raw/amplifyconfiguration.json
  • iOS – AmazonChimeMessagingSDKDemo/amplifyconfiguration.json

Values to be replaced are:

  • cognitoIdentityPoolId – Value of cognitoIdentityPoolId from CloudFormation outputs
  • cognitoUserPoolId – Value of cognitoUserPoolId from CloudFormation outputs
  • cognitoAppClientId – Value of cognitoAppClientId from CloudFormation outputs
  • attachmentsS3BucketName – Value of attachmentsS3BucketName from CloudFormation outputs (Only iOS)

Update application config

Go to the file for constants used in the demo apps and replace the following placeholders with values from the outputs of the CloudFormation stack. The file location for Android and iOS are:

  • Android – app/src/main/java/com/amazonaws/services/chime/sdkdemo/common/AppConstants.kt
  • iOS – AmazonChimeMessagingSDKDemo/AppConfiguration.swift

Values to be replaced are:

  • APP_INSTANCE_ARN – Value of appInstanceArn from CloudFormation output
  • API_GATEWAY_INVOKE_URL – Value of apiGatewayInvokeUrl from CloudFormation output
  • PINPOINT_APPLICATION_ARN – Value of pinpointApplicationArn from CloudFormation output

Step 3: Deploy the Amazon Chime SDK web demo app locally

In this section, you deploy a simple web app written in the React framework in your local environment. This app demonstrates the Amazon Chime SDK messaging features. Once you set up the app locally, you are able to get started.

  1. Navigate to the root folder of the Amazon Chime SDK chat demo: cd apps/chat
  2. Run the following commands to install all the dependencies for the component library: npm install
  3. Open ./src/Config.js with the editor of your choice and replace placeholders with values from the CloudFormation outputs
  4. Once the configuration for the application is entered, run the following commands in the apps/chat folder to set up your front-end server locally: npm start

Step 4: Set up users

User Registration

On the homepage, you have the option to register a user for the chat application.

User confirmation

During user registration, a user is created in the secure Amazon Cognito directory you set up in step 2. However, this user is in unconfirmed state after registration. To confirm the user, an administrator logs into their Amazon Cognito user pool. The administrator confirms the user by clicking on the username, and choosing Confirm User.

Note: You can automate the user confirmation in Amazon Cognito using multiple mechanisms. Read documentation for more details.

Once a user is confirmed in Amazon Cognito, they can log into the chat application and start using its features.

Step 5: Run mobile demo app

Android

  1. Run the following command to navigate to the root folder of the Android chat demo application: cd apps/chat-android
  2. Open the project in Android Studio
  3. Run the application on a simulator or a physical Android device by clicking on Run ‘app’ in the menu
  4. Sign in with username and password of the desired Amazon Cognito user that you created in Step 4

iOS

  1. Run the following command to navigate to the root folder of the iOS chat demo application: cd apps/chat-ios
  2. Run the following command to install dependencies: pod install
  3. Open AmazonChimeMessagingSDKDemo.xcworkspace using Xcode.
  4. Select the team with Push Notifications Capabilities in your Apple Developer account
  5. Connect a physical iPhone device to your Mac, run the app against your connected device
  6. Sign in with username and password of desired Amazon Cognito user that you created in Step 4

Explore the Amazon Chime SDK messaging mobile demo

In the mobile demo app, we have added a few features that show case how to receive push notifications and control which messages sent in a channel are received as push notifications.

Enable push notifications

You can easily enable push notifications for the User you are logged in as by following the steps below:

  1. Open the mobile demo app and type in your Username and Password and click on Sign In
  2. Once signed in, click on the Hamburger Menu in the top right corner and tap on App Instance Settings
  3. You can toggle the Push Notification switch to the ON state which will register your device with Amazon Chime SDK messaging

Disable push notifications

You can disable push notifications for all channels that you are a member of by following the steps below:

  1. Go to the Channels page and click on App Instance Settings
  2. Toggle the Push Notification switch to the OFF state to update your device settings to turn off push notifications off for your device

Manage type of notification per channel

If you want to turn off push notifications only for a specific channel(s), then you can do so from within a channel.

  1. After logging in, go to the Channels page and tap on a Channel Name in order to proceed to the Messages view
  2. Click on the Hamburger Menu in the top right corner and tap on Notification Settings
  3. Once the Loading toast goes away, you can select one of the following options for the level of notifications you want to receive:
    • FULL – You will receive push notifications for every message sent in the channel
    • MUTE – You will not receive any push notifications for that channel
    • MENTIONS – You will receive push notifications only for messages that have tagged you explicitly i.e. the message content must contain your Display Name in the following format “@DisplayName”

Selective push notifications is made possible with the usage of MessageAttributes that are set when sending the message and a Filter Rule that is set as part of the Membership Preferences for the user when they select a Notification Level. For more details on Message Attributes and Filter Rules please read *insert link to message attributes and filter rule*

Push Notifications Action

Once you receive a push notification, based on your notification settings, you can easily view it in the Android Notification Menu dropdown. On clicking the notification, you will be redirecting to the mobile demo app and a screen with the Messages view for that specific Channel will open up.

Sign Out

If you do not want to receive push notifications on the mobile device for the signed in user, make sure you go to the App Instance Settings menu and click on Sign Out in order to deregister the mobile device using Amazon Chime SDK messaging.

Cleanup

If you don’t want to continue to be charged for the use of the chat demo application, you can clean up by deleting the stack and resources created in Step 1.

To delete the stack and its resources:

  1. Go to the Amazon S3 Console and empty the bucket that was created
  2. From the AWS CloudFormation console , Select the stack that you created
  3. Click Delete Stack
  4. In the confirmation message that appears, click Yes, Delete. At this stage, the status for your changes to DELETE_IN_PROGRESS. In the same way you monitored the creation of the stack, monitor its deletion by using the Events tab. When AWS CloudFormation completes the deletion of the stack, it removes the stack from the list

Finally, delete the Amazon Chime app instance created in step 1 using the following commands in CLI:

aws chime delete-app-instance --app-instance-arn <appInstanceArn from STEP 1>

Conclusion

In this post, we walked through how you can enable push notifications for your mobile app built on iOS or Android using the Amazon Chime SDK messaging. We also demonstrated how you can use message attributes in conjunction with filter rules to receive push notifications only for a subset of messages.

With support for mobile push notifications on Android and iOS, customers are now easily able to develop mobile apps without worrying about battery consumption or missing messages in a channel because the mobile application has been suspended by the operating system.

To learn more about what you can build with Amazon Chime SDK messaging, please read our other messaging blog posts: