Business Productivity

Real-time collaboration using Amazon Chime SDK messaging

Amazon Chime SDK messaging provides the building blocks needed for developers to easily connect communities of users with secure, scalable, and persistent messaging. Available APIs include sending messages, retrieving message history, editing messages, deleting messages, setting retention policies on stored messages, and streaming export of chat data. Amazon Chime SDK messaging helps enable our customers to build faster and simplify their operations.

In addition to using Amazon Chime SDK messaging for person-to-person messaging use cases, our customers discovered that our APIs are flexible enough to enable a wide range of use cases. They use Amazon Chime SDK messaging as the data transport for their application and build truly unique experiences for their users. We have customers building a wide variety of experiences from collaborative chat, to messaging alongside video broadcasting, to real-time collaboration in online documents and on whiteboards.

Customers using the Amazon Chime SDK to power meetings have used the data channel feature available during meetings for whiteboarding and other collaboration experiences. This works well for some use cases, but customers that want a persistent experience that is also available outside of meetings have turned to Amazon Chime SDK messaging. This approach enables collaboration inside or outside of the meeting, with persistence so that all users share the same experience even if they weren’t present when collaboration started.

In this blog, we show how developers can easily build real-time collaboration applications using Amazon Chime SDK messaging. Using Amazon Chime SDK messaging helps eliminate complexity of persisting, securing, and delivering messages as you scale. For the demo in this blog, we chose Yjs to synchronize distributed data structures because Yjs is a well-supported open-source collaboration solution that integrates easily with Amazon Chime SDK messaging. However, the same concepts applied in this blog for Yjs can apply to almost any other collaboration solutions you may choose.

Application Overview

We built a text editor demo application using Amazon Chime SDK messaging. This text editor allows multiple participants to edit a shared text document. The application persists the user’s changes in a Yjs document. A Yjs document is consisted of basic shared data types such as Array, Map, Text, and others. You can build real-time collaboration applications using these basic shared data types.

The Amazon Chime SDK messaging service is the server side component for the text editor application. The messaging service receives document deltas from each client and persists the document deltas. The messaging service broadcasts the document deltas to each of the users who are members of the relevant channel. The messaging service doesn’t parse the content of the document deltas because the document synchronization logic and other app logic are performed at the client side. This approach allows Amazon Chime SDK messaging to be used for a wide range of applications.

There are four key components of this architecture:

  1. Real-time Collaboration Application – Allows users to collaborate on a shared document.
  2. Amazon Chime SDK Messaging – Persists and broadcasts the document changes and provides document access controls.
  3. Amazon API Gateway – Connects the client to the channel and user creation AWS Lambda.
  4. Channel and User Creation AWS Lambda Function – Uses the Amazon Chime SDK to create channels, create users, and add users to channels.

Prerequisites

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

Note: Deploying and using the demo created in this post will incur charges. If you wish to discontinue use and stop incurring charges, there are steps to delete the demo and all resources at the end of this post. Please contact us for more information about potential volume discounts and service quota increases for high production usage.

Deploying the text editor demo application

Creating AWS resources

  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. Copy the contents of the AWS CloudFormation template from real-time collaboration sample app in GitHub and save it in a new file named real-time-collaboration-template.yaml.
  3. Open the AWS CloudFormation console and choose Create stack.
  4. Choose Upload a template file, and then browse for the real-time-collaboration-template.yaml file.
  5. For Stack name, type real-time-collaboration-demo and choose Next.
  6. On the Specify Details page, enter the stack name:
    DemoName-ChimeCollabDemo
  7. Choose Next, and then Next on the Configure stack options page.
  8. On the Review page, check the I acknowledge that AWS CloudFormation might create IAM resources check box. Then click Create.
  9. Creating the stack generates 3 outputs: ApiGatewayUrl, AppInstanceArn, AdminUserArn. Note these values for the outputs to use to configure the app in the next step.

Deploying the text editor demo application locally

In this section, you install and build the demo app in your local environment.

  1. Clone the project from GitHub.
    git clone https://github.com/aws-samples/amazon-chime-sdk.git
  2. Run the following command to navigate to the root folder:
    cd ./amazon-chime-sdk/apps/real-time-collaboration
  3. Run the following commands to install dependencies from the root folder:
    npm install
    npm run build

Running the text editor demo application locally

In this section, you will run the text editor web app in your local environment. This simple text editor allows multiple users to edit a shared text document. When running this example locally, you can start multiple browser tabs or multiple browsers to observe that changes in one browser are synchronized across all other browsers. You can also host this app as a static website in your account using Amazon Simple Storage Service (S3) website hosting so that you can collaborate with other participants from other devices. You must secure your app by restricting access to the hosted app using security policies for the S3 bucket that are relevant for your use case.

  1. Run the following commands to navigate to the text-editor folder:
    cd ./amazon-chime-sdk/apps/real-time-collaboration/examples/text-editor
  2. Open ./amazon-chime-sdk/apps/real-time-collaboration/examples/text-editor/src/Config.js with the editor of your choice. Add the following configuration to it:
    export const appConfig = {
    ApiGatewayUrl: '<ApiGatewayUrl from CloudFormation Outputs>',
    AppInstanceArn: '<AppInstanceArn from CloudFormation Outputs>',
    AdminUserArn: '<AdminUserArn from CloudFormation Outputs>'
    };
  3. Once the configuration for the application is entered, run the following commands in the text editor folder.
    npm run start
  4. Open your browser and navigate to http://localhost:8080 to start testing. The application updates the url with the Amazon Chime channel created for this session. Type a few words in the text editor.
  5. Copy the url with the Amazon Chime channel into a new web browser window. The new browser window shows the text that you previously typed. Type a few words in the text editor of the new web browser window. You can see the text is synchronized to first web browser session.

Obtaining AWS credentials and Channel Access

The text editor demo application uses a simple process to authenticate users and grant users access to a channel. This approach is great for use cases where you want users to easily and quickly collaborate on a shared document without requiring a user account and document access that is explicitly granted by the document author.

While this demo app has simple authentication processes, Amazon Chime SDK messaging provides user creation, channel moderation, and channel permission APIs that allows you to build fine grain document access permission for your specific use cases. For example, you can implement document access business logic where the document author is the channel moderator. The document author grants document access to other users. You can further implement read only document permission by restricting a user from sending messages, making the document read only.

Because Amazon Chime SDK messaging works with almost any identity provider, you can replace the Channel and User Lambda function shown in the diagram in the Application Overview section with your own identity provider and eliminate guest access altogether. To learn more about integrating your identity provider with Amazon Chime SDK Messaging, read our blog post.

Real-time Collaboration Application

A real-time collaboration application consists of three broad components: the application presentation, the client data synchronization framework, and the backend service. The app presentation provides the interface for the user to modify the underlying shared document. The client data synchronization framework merges the document changes into the shared objects and publishes the document changes to the backend service. The backend service persists and distributes the changes to the participants of the document.

The client data synchronization framework is responsible for publishing new local document changes and merging new document changes from other document collaborators into the local document. We chose Yjs as the client framework, but the same concepts can apply to almost any other collaboration solutions. A Yjs document consists of one or more shared objects. Document changes from one Yjs document can be merged to other Yjs documents without merge conflicts. The application presentation takes the user inputs and persists the updates into the local copy of the Yjs document. Yjs uses a Yjs provider to exchange document changes with other document collaborators.

We implemented a Yjs provider for Amazon Chime SDK messaging to send and receive document changes. The backend service persists and distributes the document changes between the document collaborators. Amazon Chime SDK messaging provides a secure, scalable, low-latency, and persistent data transport for the document changes. By using the Yjs provider for Amazon Chime SDK messaging, you can send document changes to the Amazon Chime SDK messaging service. The provider establishes a persistent WebSocket connection to Amazon Chime SDK messaging service to receive new document changes at low-latency. Because the merging logic is performed in the client, Amazon Chime SDK messaging service doesn’t parse the content of the document change.

Synchronizes document changes and transient states

Amazon Chime SDK messaging enables the client data synchronization framework to exchange both persistent and transient data. Yjs sends document changes. The document changes are persisted so that the latest document can be reconstructed with the document changes. Yjs also sends transient data such as mouse cursor location and text selection as awareness information. The Yjs provider for Amazon Chime SDK messaging sends messages using SendChannelMessage API with type as PERSISTENT for document changes and NON_PERSISTENT for awareness information. Amazon Chime SDK messaging service deliveries both the document changes and awareness information to the document collaborators, but only document changes are persisted in Amazon Chime SDK messaging service.

The provider implements a simple document change strategy. The provider batches multiple document changes made within 500 milliseconds into a single message. This simple strategy balances application responsiveness and number of messages sent for the text editor. You can use a different batching strategy for your particular use cases.

Retrieving the latest document state

A document collaborator gets the latest copy of the document by applying the document changes stored in Amazon Chime SDK messaging service. During application initialization, the Yjs provider for Amazon Chime SDK messaging calls ListChannelMessages API to retrieve the document changes persisted in Amazon Chime SDK messaging. The provider applies the persisted document changes on top of the collaborator’s local document to catch up to the latest document state.

As a next step, we can further optimize the Yjs provider. Rather than creating the latest document with only document changes, a snapshot of the document state can optimize the process of retrieving the latest document. The snapshot can be generated either at the client or service side. For the client side approach, one of the document collaborators is elected to take the snapshot. The client serializes the local document state. The client uploads the document to an object store service such as S3. The client sends a message to the Amazon Chime SDK messaging service with the S3 bucket ARN provided in the Metadata field of the SendChannelMessage request. For the service side approach, a Lambda Function creates a new snapshot using the previous snapshot and the recent document changes. The Lambda consumes the streaming chat export with Amazon Kinesis Data Streams. Similar to the client side approach, the Lambda stores the snapshot in S3 and provides the S3 bucket ARN in the Metadata field of the request. During application initialization, the provider calls ListChannelMessages API to retrieve the persisted document changes until the provider finds the most recent snapshot. The provider applies the recent persisted document changes on top of the most recent snapshot to get the latest document state.

Clean Up

To avoid incurring charges for the use of the text editor demo application, you can clean up by deleting the AWS CloudFormation stack and resources created in the section for deploying the demo app.

To delete the stack and its resources:

  1. From the AWS CloudFormation console in us-east-1, select the stack that you created for this demo.
  2. Click Delete Stack.
  3. 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.

Conclusion

In this post, we covered how you can use Amazon Chime SDK messaging as building blocks to easily build secure and scalable real-time collaboration apps. Amazon Chime SDK messaging can be used with almost any collaboration solutions you may choose.

The Amazon Chime SDK messaging features are available today in the US East (N. Virginia) region at low per-message rates. To get started with Amazon Chime SDK messaging, read our developer guide.