Update readme with info about twilio conversations #476
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -4,22 +4,22 @@ | |
|
|
||
| ## What is it | ||
|
|
||
| This application demonstrates a multi-party video application built with [Twilio's Programmable Video JS SDK](https://github.com/twilio/twilio-video.js), [Twilio's Conversations JS SDK](https://www.npmjs.com/package/@twilio/conversations), and [Create React App](https://github.com/facebook/create-react-app). | ||
|
|
||
| - Deploy to [Twilio Serverless](https://www.twilio.com/docs/runtime/functions-assets-api) in just a few minutes | ||
| - No other infrastructure is required | ||
| - No code changes are required before your first deploy | ||
| - There is no cost associated with deploying the app | ||
| - Go Rooms usage is free, however [standard usage charges](https://www.twilio.com/video/pricing) apply for Programmable Video when using the app with all other Room types. The chat feature is built using the Conversations API and is free-of-cost up to 200 monthly active users, [standard usage charges](https://www.twilio.com/conversations/pricing) apply thereafter. | ||
|
|
||
|  | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| You must have the following installed: | ||
|
|
||
| - [Node.js v12+](https://nodejs.org/en/download/) | ||
| - NPM v6+ (comes installed with newer Node versions) | ||
|
|
||
| ## Install Dependencies | ||
|
|
||
|
|
@@ -43,19 +43,19 @@ This app requires an additional plugin. Install the CLI plugin with: | |
|
|
||
| ## Deploy the app to Twilio | ||
|
|
||
| Before deploying the app, make sure you are using the correct account on the Twilio CLI (using the command `twilio profiles:list` to check). | ||
| The app is deployed to Twilio with a single command: | ||
|
|
||
| $ npm run deploy:twilio-cli | ||
|
|
||
| This performs the following steps: | ||
|
|
||
| - Builds the React app in the `src` directory | ||
| - Generates a random code used to access the Video app | ||
| - Deploys the React app and token server function as a Twilio Serverless service. | ||
| - Prints the URL for the app and the passcode. | ||
|
|
||
| **NOTE:** The Twilio Function that provides access tokens via a passcode should _NOT_ be used in a production environment. This token server supports seamlessly getting started with the collaboration app, and while convenient, the passcode is not secure enough for production environments. You should use an authentication provider to securely provide access tokens to your client applications. You can find more information about Programmable Video access tokens [in this tutorial](https://www.twilio.com/docs/video/tutorials/user-identity-access-tokens). **As a precaution, the passcode will expire after one week**. To generate a new passcode, redeploy the app: | ||
|
|
||
| $ npm run deploy:twilio-cli -- --override | ||
|
|
||
|
|
@@ -83,15 +83,15 @@ If any errors occur after running a [Twilio CLI RTC Plugin](https://github.com/t | |
|
|
||
| ## App Behavior with Different Room Types | ||
|
|
||
| After running the command [to deploy the app to Twilio](#deploy-the-app-to-twilio), the room type will be returned in the command line output. Each room type provides a different video experience. More details about these room types can be found [here](https://www.twilio.com/docs/video/tutorials/understanding-video-rooms). The rest of this section explains how these room types affect the behavior of the video app. | ||
|
|
||
| _Group_ - The Group room type allows up to fifty participants to join a video room in the app. The Network Quality Level (NQL) indicators and dominant speaker are demonstrated with this room type. Also, the VP8 video codec with simulcast enabled along with a bandwidth profile are set by default in order to provide an optimal group video app experience. | ||
|
|
||
| _Small Group_ - The Small Group room type provides an identical group video app experience except for a smaller limit of four participants. | ||
|
|
||
| _Peer-to-peer_ - Although up to ten participants can join a room using the Peer-to-peer (P2P) room type, it is ideal for a one to one video experience. The NQL indicators, bandwidth profiles, and dominant speaker cannot be used with this room type. Thus, they are not demonstrated in the video app. Also, the VP8 video codec with simulcast disabled and 720p minimum video capturing dimensions are also set by default in order to provide an optimal one to one video app experience. If more than ten participants join a room with this room type, then the video app will present an error. | ||
|
|
||
| _Go_ - The Go room type provides a similar Peer-to-peer video app experience except for a smaller limit of two participants. If more than two participants join a room with this room type, then the video app will present an error. | ||
|
|
||
| If the max number of participants is exceeded, then the video app will present an error for all room types. | ||
|
|
||
|
|
@@ -116,12 +116,12 @@ See browser support table for [twilio-video.js SDK](https://github.com/twilio/tw | |
|
|
||
| ### Running a local token server | ||
|
|
||
| This application requires an access token to connect to a Room for Video and a Conversation for Chat. The included local token [server](server/index.ts) provides the application with access tokens. This token server can be used to run the app localally, and it is the server that is used when this app is run in development mode with `npm start`. Perform the following steps to setup the local token server: | ||
|
|
||
| - Create an account in the [Twilio Console](https://www.twilio.com/console). | ||
| - Click on 'Settings' and take note of your Account SID. | ||
| - Create a new API Key in the [API Keys Section](https://www.twilio.com/console/video/project/api-keys) under Programmable Video Tools in the Twilio Console. Take note of the SID and Secret of the new API key. | ||
| - Create a new Conversations service in the [Services section](https://www.twilio.com/console/conversations/services) under the Conversations tab in the Twilio Console. Take note of the SID generated. | ||
| - Store your Account SID, API Key SID, API Key Secret, and Conversations Service SID in a new file called `.env` in the root level of the application (example below). | ||
|
|
||
| ``` | ||
|
|
@@ -131,7 +131,9 @@ TWILIO_API_KEY_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| TWILIO_CONVERSATIONS_SERVICE_SID=ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | ||
| ``` | ||
|
|
||
| Now the local token server (see [server.js](server/index.ts)) can dispense Access Tokens to connect to a Room and a Conversation. See [.env.example](.env.example) for information on additional environment variables that can be used. | ||
|
There was a problem hiding this comment. server.js is no longer? --> (see server/index.ts) |
||
|
|
||
| Note: the use of Twilio Conversations is optional. If you wish to opt out, simply run or build this app with the `REACT_APP_DISABLE_TWILIO_CONVERSATIONS` environment variable set to `true`. | ||
|
There was a problem hiding this comment. Wondering if "Note" should be bolded so that we can draw more attention to this line so that customers know that it's optional? |
||
|
|
||
| ### Running the App locally | ||
|
|
||
|
|
@@ -146,18 +148,16 @@ You will also see any linting errors in the console. Start the token server loca | |
|
|
||
| $ npm run server | ||
|
|
||
| The token server runs on port 8081 and expects a `POST` request at the `/token` route with the following JSON parameters: | ||
|
|
||
| ``` | ||
| { | ||
| "user_identity": string, // the user's identity | ||
| "room_name": string, // the room name | ||
| } | ||
| ``` | ||
|
|
||
| The response will be a token that can be used to connect to a room. The server provided with this application uses the same endpoints as the [plugin-rtc](https://github.com/twilio-labs/plugin-rtc) Twilio CLI plugin that is used to deploy the app. For more detailed information on the server endpoints, please see the [plugin-rtc README](https://github.com/twilio-labs/plugin-rtc#twilio-labsplugin-rtc). | ||
|
|
||
| ### Multiple Participants in a Room | ||
|
|
||
|
|
@@ -175,7 +175,7 @@ This script will build the static assets for the application in the `build/` dir | |
|
|
||
| ### Tests | ||
|
|
||
| This application has unit tests (using [Jest](https://jestjs.io/)) and end-to-end tests (using [Cypress](https://www.cypress.io/)). You can run the tests with the following scripts. | ||
|
|
||
| #### Unit Tests | ||
|
|
||
|
|
@@ -193,11 +193,11 @@ Run end to end tests with | |
|
|
||
| This will open the Cypress test runner. When it's open, select a test file to run. | ||
|
|
||
| Note: Be sure to complete the 'Getting Started' section before running these tests. These Cypress tests will connect to real Twilio rooms and real Twilio conversations, so you may be billed for any time that is used. | ||
|
There was a problem hiding this comment. Same here? Maybe make "Note" bolded? |
||
|
|
||
| ### Application Architecture | ||
|
|
||
| The state of this application (with a few exceptions) is managed by the [room object](https://sdk.twilio.com/js/video/releases/2.13.0/docs/Room.html) that is supplied by the SDK. The `room` object contains all information about the room that the user is connected to. The class hierarchy of the `room` object can be viewed [here](https://www.twilio.com/docs/video/migrating-1x-2x#object-model). | ||
|
|
||
| One great way to learn about the room object is to explore it in the browser console. When you are connected to a room, the application will expose the room object as a window variable: `window.twilioRoom`. | ||
|
|
||
|
|
@@ -226,17 +226,19 @@ In this hook, the `useEffect` hook is used to subscribe to the `dominantSpeakerC | |
|
|
||
| For more information on how React hooks can be used with the Twilio Video SDK, see this tutorial: https://www.twilio.com/blog/video-chat-react-hooks. To see all of the hooks used by this application, look in the `src/hooks` directory. | ||
|
|
||
| The [VideoProvider](src/components/VideoProvider/index.tsx) component contains much of the logic that relates to connecting to video rooms and acquiring local input devices. The VideoProvider component exposes many properties and methods to the rest of the application through the [useVideoContext](src/hooks/useVideoContext/useVideoContext.ts) hook. Similarly, the [ChatProvider](src/components/ChatProvider/index.tsx) contains logic that relates to connecting to a Twilio Conversation, and it exposes properties and methods through the [useChatContext](src/hooks/useChatContext/useChatContext.ts) hook. | ||
|
|
||
| ### Configuration | ||
|
|
||
| The `connect` function from the SDK accepts a [configuration object](https://sdk.twilio.com/js/video/releases/2.13.0/docs/global.html#ConnectOptions). The configuration object for this application can be found in [src/utils/useConnectionOptions/useConnectionOptions.ts](src/utils/useConnectionOptions/useConnectionOptions.ts). In this object, we 1) enable dominant speaker detection, 2) enable the network quality API, and 3) supply various options to configure the [bandwidth profile](https://www.twilio.com/docs/video/tutorials/using-bandwidth-profile-api). | ||
|
|
||
| #### Track Priority Settings | ||
|
|
||
| This application dynamically changes the priority of remote video tracks to provide an optimal collaboration experience. Any video track that will be displayed in the main video area will have `track.setPriority('high')` called on it (see the [VideoTrack](https://github.com/twilio/twilio-video-app-react/blob/master/src/components/VideoTrack/VideoTrack.tsx#L29) component) when the component is mounted. This higher priority enables the track to be rendered at a high resolution. `track.setPriority(null)` is called when the component is unmounted so that the track's priority is set to its publish priority (low). | ||
|
|
||
| ### Google Authentication using Firebase (optional) | ||
|
|
||
| This application can be configured to authenticate users before they use the app. Once users have signed into the app with their Google credentials, their Firebase ID Token will be included in the Authorization header of the HTTP request that is used to obtain an access token. The Firebase ID Token can then be [verified](https://firebase.google.com/docs/auth/admin/verify-id-tokens) by the server that dispenses access tokens for connecting to a room. | ||
|
|
||
| See [.env.example](.env.example) for an explanation of the environment variables that must be set to enable Google authentication. | ||
|
|
||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
small typo - run the app localally. Should be locally