Update edited readme

git-babel · git-babel · commit 48c34f22f5ed · 2019-12-31T18:19:04.000+09:00
diff --git a/README.md b/README.md
@@ -1,10 +1,10 @@
 # SendBird Calls for JavaScript
 
 ## Introduction
-SendBird Calls is a new product enabling real-time calls between users registered within a SendBird application. SDKs are provided for JavaScript, Android, and iOS. Using any one of these, developers can quickly integrate calling functions into their own applications that will allow users to make and receive internet based real-time voice calls on the SendBird platform.
+`SendBird Calls` is the newest addition to our product portfolio. It enables real-time calls between users within your SendBird application. SDKs are provided for iOS, Android, and JavaScript. Using any one of these, developers can quickly integrate voice and video call functions into their own client apps allowing users to make and receive web-based real-time voice and video calls on the SendBird platform.
 
 ## Functional Overview
-When implemented, the SendBird Calls SDK provides the framework to both make and receive one-to-one calls, referred to in the SDK as “direct calls” (analogous to “direct messages” / “DMs” in a messaging context).  Direct calls are made when a caller identifies a user on the SendBird application and initializes a call request (referred to as dialing). The callee, with the SDK’s event handlers implemented, is notified on all authenticated devices, and can choose to accept the call.  If accepted, a network route is established between the caller and callee, and the direct call between the caller and callee begins.  Application administrators can then review call logs in the “Calls” section of the SendBird dashboard.
+Our JavaScript SDK for Calls provides the framework to make and receive voice and video calls. Direct calls in the SDK refers to one-to-one calls similar to that of the direct messages (DMs) in messaging services. To make a direct call, the caller should first initialize the call request by dialing to the callee whose all authenticated devices will be notified. The callee then can choose to accept the call from one of the devices. When the call is accepted, a connection is established between the caller and callee, and marks the start of the direct call. SendBird dashboard provides all call logs in the Calls menu for admins to review.
 
 ## SDK Prerequisites
 * Modern browsers implementing WebRTC APIs are supported; IE isn't supported.
@@ -15,7 +15,7 @@ When implemented, the SendBird Calls SDK provides the framework to both make and
 ```
 
 ## Install and configure the SDK
-Download and install the SDK using npm or yarn.
+Download and install the SDK using `npm` or `yarn`.
 ```shell script
 # npm
 npm install sendbird-calls 
@@ -43,13 +43,13 @@ or include in header as global variable
 If user dial or accept for the first time in the given domain, browser prompts for permission to use microphone.
 
 ## Initialize the SendBirdCall instance in a client app
-As shown below, the `SendBirdCall` instance must be initiated when a client app is launched. If another initialization with another APP_ID takes place, all existing data will be deleted and the `SendBirdCall` instance will be initialized with the new APP_ID.
+As shown below, the `SendBirdCall` instance must be initiated when a client app is launched. If another initialization with another `APP_ID` takes place, all existing data will be deleted and the `SendBirdCall` instance will be initialized with the new `APP_ID`.
 ```javascript
 SendBirdCall.init(APP_ID);
 ```
 
 ## Authenticate a user and connect websocket to server
-In order to make and receive calls, authenticate the user with SendBird server with the the `SendBirdCall.authenticate()` method. To dial or receive calls, `SendBirdCall` should be connected to websocket server. The socket can be connected by using `SendBirdCall.connectWebSocket()` method.
+In order to make and receive calls, authenticate the user with SendBird server with the the `SendBirdCall.authenticate()` method. To make or receive calls, `SendBirdCall` should be connected to websocket server. Connect socket after authentication has completed using `SendBirdCall.connectWebSocket()` method.
 ```javascript
 // Authentication
 SendBirdCall.authenticate({ USER_ID, ACCESS_TOKEN }, (res, error) => {
@@ -62,14 +62,15 @@ SendBirdCall.authenticate({ USER_ID, ACCESS_TOKEN }, (res, error) => {
 
 // Websocket Connection
 SendBirdCall.connectWebSocket()
-  .then(/* connect succeeded */);
+  .then(/* connect succeeded */)
   .catch(/* connect failed */);
 ```
 
 ## Register event handlers
+The SDK provides two types of event handlers for various events on your client application: SendBirdCallListener and DirectCallListener.
 
 ### SendBirdCallListener
-Register a device-specific event handler using the `SendBirdCall.addListener()` method. Before adding the  `onRinging()`, a user can't receive an onRinging event. Therefore, it is recommended to add this handler at the beginning of the app. Responding to device-wide events (e.g. incoming calls) is then managed as shown below:
+Register a device-specific event handler using the `SendBirdCall.addListener()` method. Before adding the  `onRinging()`, a user can't receive an `onRinging` event. Therefore, it is recommended to add this handler at the beginning of the app. Once the listener is added, responding to device-wide events (for example, incoming calls) is then managed as shown below:
 
 ```javascript
 SendBirdCall.addListener(UNIQUE_HANDLER_ID, {
@@ -78,14 +79,15 @@ SendBirdCall.addListener(UNIQUE_HANDLER_ID, {
   }
 });
 ```
+`UNIQUE_HANDLER_ID` is any unique string value (for example, UUID).
 <br/>
 
 | Method        | Description                                                      |
 |---------------|------------------------------------------------------------------|
 |onRinging()    | Invoked when incoming calls are received in the callee’s device. |
 
 ### DirectCallListener
-Register a call-specific event handler by attaching handler function to the properties of call object directly. Responding to call-specific events (e.g. call connected) is then managed as shown below:
+Register a call-specific event handler by attaching handler function to the properties of call object directly. Responding to call-specific events (for example, call connected) is then managed as shown below:
 
 ```javascript
 // call is 'DirectCall' object
@@ -109,13 +111,13 @@ call.onRemoteAudioEnabled = (call) => {
 
 | Method                        | Description                                                                                                       |
 |-------------------------------|-------------------------------------------------------------------------------------------------------------------|
-|onEstablished()                | Invoked on the caller’s device and the callee’s device, when the callee has accepted the call by running the method call.accept(), but they are not yet connected to media devices. |
-|onConnected()                  | Invoked when media devices (e.g microphone, speakers) between the caller and callee are connected and can start the call using media devices. |
-|onEnded()                      | Invoked  when the call has ended on the caller’s device or the callee’s device. This is triggered automatically when either party runs the method call.end()  This event listener is also invoked if there are other reasons for ending the call. A table of which can be seen at the bottom. |
-|onRemoteAudioEnabled()         | Invoked on the caller’s devices when the callee changes their audio settings. |
+|onEstablished()                | On the caller’s device and the callee’s device, the callee has accepted the call by running the method call.accept(), but they are not yet connected to media devices. |
+|onConnected()                  | Media devices (for example, microphone and speakers) between the caller and callee are connected and can start the call using media devices. |
+|onEnded()                      | The call has ended on the caller’s device or the callee’s device. This is triggered automatically when either party runs the method call.end(). This event listener is also invoked if there are other reasons for ending the call. A table of which can be seen at the bottom. |
+|onRemoteAudioEnabled()         | On the caller’s devices, the callee changes their audio settings. |
 
 ## Make a call
-Initiate a call by providing the callee’s user id into the `SendBirdCall.dial()` method.  Use the `callOption` object to choose initial call configuration (e.g. muted/unmuted) 
+Initiate a call by providing the callee’s user id into the `SendBirdCall.dial()` method.  Use the `callOption` object to choose initial call configuration (for example, muted/unmuted) 
 
 ```javascript
 /*
@@ -126,6 +128,7 @@ interface DirectCallOption {
 const callOption = {
   audioEnabled: true
 };
+
 const call = SendBirdCall.dial(CALLEE_ID, false, callOption, (call, error) => {
     if (error) {
       // dial failed
@@ -151,11 +154,11 @@ call.onRemoteAudioEnabled = (call) => {
 ```
 
 ## Receive a call
-Receive incoming calls by registering handler object. Accept or decline incoming calls using the `directCall.accept()` or the `directCall.end()` methods.
+Receive incoming calls by registering the event handler. Accept or decline incoming calls using the `directCall.accept()` or the `directCall.end()` methods.
 
-If the call is accepted, a media session will be established by the SDK.
+If the call is accepted, a media session will automatically be established by the SDK. 
 
-Event handlers muse be registered before accepting a call. Once registered, this listeners enable reacting to mid-call events via callbacks methods.
+The event handler muse be registered before accepting a call. Once registered, the listeners enable reacting to mid-call events via callbacks methods.
 
 ```javascript
 SendBirdCall.addListener(UNIQUE_HANDLER_ID, {
@@ -184,6 +187,7 @@ SendBirdCall.addListener(UNIQUE_HANDLER_ID, {
     const callOption = {
       audioEnabled: true
     };
+
     call.accept(callOption);
   }
 });
@@ -192,7 +196,6 @@ SendBirdCall.addListener(UNIQUE_HANDLER_ID, {
 Incoming calls are received via the application's persistent internal server connection, which is established in `SendBirdCall.connectWebSocket()`.
 
 ## Handle a current call
-
 While a call is in progress, mute or unmute the caller’s audio using the `directCall.mute()` or `directCall.unmute()` method(s). If the callee changes their audio settings, the caller is notified via the `directCall.onRemoteAudioEnabled` listener.
 
 ```javascript
@@ -204,28 +207,34 @@ call.unmute();
 
 // receives the event
 call.onRemoteAudioEnabled = (call) => {
-  ...
+  if (call.isRemoteAudioEnabled) {
+    // The peer has been muted.
+    // Consider displaying an unmuted icon.
+  } else {
+    // The peer has been muted.
+    // Consider displaying and toggling a muted icon.
+  }
 }
 ```
 
 ## End a call
-A caller ends using the `directCall.end()` method. The event can be processed via the `directCall.onEnded()` listener. This listener is also called/fired when the callee ends call.
+A caller can end a call using the `directCall.end()` method. The event can be processed via the `directCall.onEnded()` listener. The listener is also called/fired when the callee ends the call.
 
 ```javascript
 // End a call
 call.end();
 
 // receives the event
 call.onEnded = (call) => {
-  ...
+  // Consider releasing or destroying call-related view from here.
 };
 ```
 
 ## Retrieve a call information
 The local or remote user’s information is available via the `directCall.localUser` and `directCall.remoteUser` properties.
 
 ## Retrieve call history
-SendBird’s servers automatically store details of calls. These details can be used later to display a call history for users. A user’s call history is available via a `DirectCallLogListQuery` instance. 
+SendBird servers automatically store details of calls, which can be used later to display a call history for users. A user’s call history is available via a `DirectCallLogListQuery` instance. 
 
 ```javascript
 /*
@@ -243,18 +252,21 @@ const params = {
 const query = SendBirdCall.createDirectCallLogListQuery(params);
 
 query.next((directCallLog) => {
-  ...
+  if (query.hasNext && !query.isLoading) {
+    // query.next() can be called once more
+    // if a user wants to fetch more call logs.
+  }
 });
 ```
 
 | Method & Prop    | Description                                                                                                                                                                                                                                                                                                       |
 |------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-|next()            | Used to query call history from SendBirdCall server.                                                                                                                                                                                                                                                              |
+|next()            | Used to query call history from `SendBirdCall` server.                                                                                                                                                                                                                                                              |
 |hasNext           | If true, there is more call history to be retrieved.                                                                                                                                                                                                                                                              |
 |isLoading         | If true, call history is being retrieved from SendBirdCall server.                                                                                                                                                                                                                                                |
 |params.limit      | Specifies the number of call logs to return at once.                                                                                                                                                                                                                                                              |
-|params.myRole     | Returns call logs of the specified role. For example, if myRole is 'dc_callee', query will return only the callee’s call logs.                                                                                                                                                                                                  |
-|params.endResults | Returns the call logs for specified results. If you specify more than one result, they are processed as OR condition and all call logs corresponding with the specified end results will be returned. For example, if endResults is ['NO_ANSWER', 'CANCELED'], only the NO_ANSWER and CANCELED call logs will be returned.|
+|params.myRole     | Returns call logs of the specified role. For example, if myRole is `'dc_callee'`, query will return only the callee’s call logs.                                                                                                                                                                                                  |
+|params.endResults | Returns the call logs for specified results. If you specify more than one result, they are processed as `OR` condition and all call logs corresponding with the specified end results will be returned. For example, if endResults is `['NO_ANSWER', 'CANCELED']`, only the `NO_ANSWER` and `CANCELED` call logs will be returned.|
 
 ## Additional information: call results
 To access the additional information relating to why a call ended, consider that you can get `directCall.endResult` property whenever needed. However, it would be most relevant perhaps, to call it within the  `onEnded()` callback.  
