Skip to content

Commit 59adb4a

Browse files
git-babelgit-babel
committed
Add README.md
1 parent 4acc8e0 commit 59adb4a

File tree

1 file changed

+257
-2
lines changed

1 file changed

+257
-2
lines changed

‎README.md‎

Lines changed: 257 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,257 @@
1-
# sendbird-calls-javascript
2-
SendBird Calls Javascript SDK
1+
# SendBird Calls for JavaScript
2+
3+
## Introduction
4+
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.
5+
6+
## Functional Overview
7+
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.
8+
9+
## SDK Prerequisites
10+
* Modern browsers implementing WebRTC APIs are supported; IE isn't supported.
11+
12+
```javascript
13+
// browser console
14+
(window.RTCPeerConnection) ? console.log('supported') : console.log('not supported')
15+
```
16+
17+
## Install and configure the SDK
18+
Download and install the SDK using npm or yarn.
19+
```shell script
20+
# npm
21+
npm install sendbird-calls
22+
23+
# yarn
24+
yarn add sendbird-calls
25+
```
26+
27+
## Audio Permissions
28+
If user dial or accept for the first time in the given domain, browser prompts for permission to use microphone.
29+
30+
## Initialize the SendBirdCall instance in a client app
31+
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.
32+
```javascript
33+
SendBirdCall.init(APP_ID);
34+
```
35+
36+
## Authenticate a user and connect websocket to server
37+
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.
38+
```javascript
39+
// Authentication
40+
SendBirdCall.authenticate({ USER_ID, ACCESS_TOKEN }, (res, error) => {
41+
if (error) {
42+
// auth failed
43+
} else {
44+
// auth succeeded
45+
}
46+
});
47+
48+
// Websocket Connection
49+
SendBirdCall.connectWebSocket()
50+
.then(/* connect succeeded */);
51+
.catch(/* connect failed */);
52+
```
53+
54+
## Register event handlers
55+
56+
### SendBirdCallListener
57+
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:
58+
59+
```javascript
60+
SendBirdCall.addListener(UNIQUE_HANDLER_ID, {
61+
onRinging: (call) => {
62+
...
63+
}
64+
});
65+
```
66+
<br/>
67+
68+
| Method | Description |
69+
|---------------|------------------------------------------------------------------|
70+
|onRinging() | Invoked when incoming calls are received in the callee’s device. |
71+
72+
### DirectCallListener
73+
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:
74+
75+
```javascript
76+
// call is 'DirectCall' object
77+
call.onEstablished = (call) => {
78+
...
79+
};
80+
81+
call.onConnected = (call) => {
82+
...
83+
};
84+
85+
call.onEnded = (call) => {
86+
...
87+
};
88+
89+
call.onRemoteAudioEnabled = (call) => {
90+
...
91+
};
92+
```
93+
<br/>
94+
95+
| Method | Description |
96+
|-------------------------------|-------------------------------------------------------------------------------------------------------------------|
97+
|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. |
98+
|onConnected() | Invoked when media devices (e.g microphone, speakers) between the caller and callee are connected and can start the call using media devices. |
99+
|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. |
100+
|onRemoteAudioEnabled() | Invoked on the caller’s devices when the callee changes their audio settings. |
101+
102+
## Make a call
103+
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)
104+
105+
```javascript
106+
/*
107+
interface DirectCallOption {
108+
audioEnabled: boolean
109+
}
110+
*/
111+
const callOption = {
112+
audioEnabled: true
113+
};
114+
const call = SendBirdCall.dial(CALLEE_ID, false, callOption, (call, error) => {
115+
if (error) {
116+
// dial failed
117+
}
118+
// dial succeeded
119+
});
120+
121+
call.onEstablished = (call) => {
122+
...
123+
};
124+
125+
call.onConnected = (call) => {
126+
...
127+
};
128+
129+
call.onEnded = (call) => {
130+
...
131+
};
132+
133+
call.onRemoteAudioEnabled = (call) => {
134+
...
135+
};
136+
```
137+
138+
## Receive a call
139+
Receive incoming calls by registering handler object. Accept or decline incoming calls using the `directCall.accept()` or the `directCall.end()` methods.
140+
141+
If the call is accepted, a media session will be established by the SDK.
142+
143+
Event handlers muse be registered before accepting a call. Once registered, this listeners enable reacting to mid-call events via callbacks methods.
144+
145+
```javascript
146+
SendBirdCall.addListener(UNIQUE_HANDLER_ID, {
147+
onRinging: (call) => {
148+
call.onEstablished = (call) => {
149+
...
150+
};
151+
152+
call.onConnected = (call) => {
153+
...
154+
};
155+
156+
call.onEnded = (call) => {
157+
...
158+
};
159+
160+
call.onRemoteAudioEnabled = (call) => {
161+
...
162+
};
163+
164+
/*
165+
interface DirectCallOption {
166+
audioEnabled: boolean
167+
}
168+
*/
169+
const callOption = {
170+
audioEnabled: true
171+
};
172+
call.accept(callOption);
173+
}
174+
});
175+
```
176+
177+
Incoming calls are received via the application's persistent internal server connection, which is established in `SendBirdCall.connectWebSocket()`.
178+
179+
## Handle a current call
180+
181+
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.
182+
183+
```javascript
184+
// mute my microphone
185+
call.mute();
186+
187+
// unmute my microphone
188+
call.unmute();
189+
190+
// receives the event
191+
call.onRemoteAudioEnabled = (call) => {
192+
...
193+
}
194+
```
195+
196+
## End a call
197+
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.
198+
199+
```javascript
200+
// End a call
201+
call.end();
202+
203+
// receives the event
204+
call.onEnded = (call) => {
205+
...
206+
};
207+
```
208+
209+
## Retrieve a call information
210+
The local or remote user’s information is available via the `directCall.localUser` and `directCall.remoteUser` properties.
211+
212+
## Retrieve call history
213+
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.
214+
215+
```javascript
216+
/*
217+
interface DirectCallLogListQueryParams {
218+
myRole: string
219+
endResults: string[],
220+
limit: number
221+
}
222+
*/
223+
const params = {
224+
myRole: 'dc_caller',
225+
endResults: ['DECLINED', 'COMPLETED'],
226+
limit: 100
227+
};
228+
const query = SendBirdCall.createDirectCallLogListQuery(params);
229+
230+
query.next((directCallLog) => {
231+
...
232+
});
233+
```
234+
235+
| Method & Prop | Description |
236+
|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
237+
|next() | Used to query call history from SendBirdCall server. |
238+
|hasNext | If true, there is more call history to be retrieved. |
239+
|isLoading | If true, call history is being retrieved from SendBirdCall server. |
240+
|params.limit | Specifies the number of call logs to return at once. |
241+
|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. |
242+
|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.|
243+
244+
## Additional information: call results
245+
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.
246+
247+
| EndResult | Description |
248+
|------------------|------------------------------------------------------------------------------------------------------------------------|
249+
| NO_ANSWER | The callee hasn’t either accepted or declined the call for a specific period of time. |
250+
| CANCELED | The caller has canceled the call before the callee accepts or declines. |
251+
| DECLINED | The callee has declined the call. |
252+
| COMPLETED | The call has ended by either the caller or callee after completion. |
253+
| TIMED_OUT | SendBird server failed to establish a media session between the caller and callee within a specific period of time.|
254+
| CONNECTION_LOST | Data streaming from either the caller or the callee has stopped due to a WebRTC connection issue while calling. |
255+
| DIAL_FAILED | The dial() method call has failed. |
256+
| ACCEPT_FAILED | The accept() method call has failed. |
257+
| OTHER_DEVICE_ACCEPTED| When the call is accepted on one of the callee’s devices, all the other devices will receive this call result. |

0 commit comments

Comments
 (0)