Skip to content

Commit 6f7df2d

Browse files
chrisallochrisallo
committed
Merge branch 'main' of github.com:sendbird/sendbird-chat-sdk-javascript into main
2 parents 320a1e4 + cb41eb5 commit 6f7df2d

File tree

1 file changed

+248
-2
lines changed

1 file changed

+248
-2
lines changed

‎README.md

+248-2
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,248 @@
1-
# sendbird-chat-sdk-javascript
2-
Sendbird Chat SDK for JavaScript.
1+
# [Sendbird](https://sendbird.com) Chat SDK for JavaScript
2+
3+
![Platform](https://img.shields.io/badge/platform-JAVASCRIPT-orange.svg)
4+
![Languages](https://img.shields.io/badge/language-TYPESCRIPT-orange.svg)
5+
[![npm](https://img.shields.io/npm/v/sendbird.svg?style=popout&colorB=red)](https://www.npmjs.com/package/sendbird)
6+
7+
## Table of contents
8+
9+
1. [Introduction](#introduction)
10+
1. [Requirements](#requirements)
11+
1. [Getting started](#getting-started)
12+
1. [Sending your first message](#sending-your-first-message)
13+
1. [Additional information](#additional-information)
14+
1. [Hiring](#we-are-hiring)
15+
16+
<br />
17+
18+
## Introduction
19+
20+
The Sendbird Chat SDK for JavaScript allows you to add real-time chat into your client app with minimal effort. Sendbird offers a feature rich, scalable, and proven chat solution depended on by companies like Reddit, Hinge, PubG and Paytm.
21+
22+
### How it works
23+
24+
The Chat SDK provides the full functionality to provide a rich chat experience, implementing it begins by adding a user login, listing the available channels, selecting or creating an [open channel](https://sendbird.com/docs/chat/v4/javascript/guides/open-channel) or [group channel](https://sendbird.com/docs/chat/v4/javascript/guides/group-channel), and receive messages and other events through [channel event delegates](https://sendbird.com/docs/chat/v4/javascript/guides/event-delegate) and the ability to send a message. Once this basic functionality is in place, congratulations, you now have a chat app!
25+
26+
Once this is in place, take a look at [all the other features](https://sendbird.com/features/chat-messaging/features) that Sendbird supports and add what works best for your users.
27+
28+
### Documentation
29+
30+
Find out more about Sendbird Chat for JavaScript in [the documentation](https://sendbird.com/docs/chat/v4/javascript/getting-started/about-chat-sdk). If you have any comments, questions or feature requests, let us know in the [Sendbird community](https://community.sendbird.com).
31+
32+
<br />
33+
34+
## Requirements
35+
36+
This section shows you the prerequisites you need to check for using Sendbird Chat SDK for JavaScript. If you have any comments or questions regarding bugs and feature requests, visit [Sendbird community](https://community.sendbird.com).
37+
38+
### Supported browsers
39+
40+
| Browser | Supported versions |
41+
| :---------------: | :--------------------- |
42+
| Internet Explorer | Not supported |
43+
| Edge | 13 or higher |
44+
| Chrome | 16 or higher |
45+
| Firefox | 11 or higher |
46+
| Safari | 7 or higher |
47+
| Opera | 12.1 or higher |
48+
| iOS Safari | 7 or higher |
49+
| Android Browser | 4.4 (Kitkat) or higher |
50+
51+
<br />
52+
53+
## Getting started
54+
55+
The quickest way to get started is by using one of the sample apps from the [samples repo](https://github.com/sendbird/sendbird-chat-sample-react), create an application in the [Sendbird dashboard](https://dashboard.sendbird.com) and copy the `App ID` to the sample app and you’re ready to go.
56+
<br />
57+
58+
## Step by step
59+
60+
### Step 1: Create a Sendbird application from your dashboard
61+
62+
Before installing Sendbird Chat SDK, you need to create a Sendbird application on the [Sendbird Dashboard](https://dashboard.sendbird.com). You will need the `App ID` of your Sendbird application when initializing the Chat SDK.
63+
64+
> **Note**: Each Sendbird application can be integrated with a single client app. Within the same application, users can communicate with each other across all platforms, whether they are on mobile devices or on the web.
65+
66+
<br />
67+
68+
### Step 2: Install the Chat SDK
69+
70+
You can install the Chat SDK with either `npm` or `yarn`.
71+
72+
**npm**
73+
74+
```bash
75+
$ npm install @sendbird/chat
76+
```
77+
78+
> Note: To use npm to install the Chat SDK, Node.js must be first installed on your system.
79+
80+
**yarn**
81+
82+
```bash
83+
$ yarn add @sendbird/chat
84+
```
85+
86+
### Step 3: Import the Chat SDk
87+
88+
```javascript
89+
import SendbirdChat from "@sendbird/chat";
90+
// your chat app implementation
91+
```
92+
93+
If you are using TypeScript and have trouble importing Sendbird, please check your `tsconfig.json` file and change the value of `allowSyntheticDefaultImports` to true in `compilerOptions`.
94+
95+
<br />
96+
97+
## Sending your first message
98+
99+
Now that the Chat SDK has been imported, we're ready to start sending a message.
100+
101+
### Authentication
102+
103+
In order to use the features of the Chat SDK, you should initiate the `SendbirdChatSDK` instance through user authentication with Sendbird server. This instance communicates and interacts with the server based on an authenticated user account, and then the user’s client app can use the Chat SDK's features.
104+
105+
Here are the steps to sending your first message using Chat SDK:
106+
107+
### Step 4: Initialize the Chat SDK
108+
109+
Before authentication, you need to intialize the SDK by calling `SendbirdChat.init`.
110+
111+
The `init` method requires an appId, which is available from your Sendbird dashboard.
112+
113+
To improve performance, this SDK is modular. You must import and provide the required modules when calling `init`.
114+
115+
```javascript
116+
import SendbirdChat from "@sendbird/chat";
117+
import { OpenChannelModule } from "@sendbird/chat/openChannel";
118+
119+
const sb = SendbirdChat.init({
120+
appId: APP_ID,
121+
modules: [new OpenChannelModule()],
122+
});
123+
```
124+
125+
### Step 5: Connect to Sendbird server
126+
127+
Once the SDK is initialized, your client app can then connect to the Sendbird server. If you attempt to call a Sendbird SDK method without connecting, an `ERR_CONNECTION_REQUIRED (800101)` error would return.
128+
129+
Connect a user to Sendbird server either through a unique user ID or in combination with an access or session token. Sendbird prefers the latter method, as it ensures privacy with the user. The former is useful during the developmental phase or if your service doesn't require additional security.
130+
131+
#### A. Using a unique user ID
132+
133+
Connect a user to Sendbird server using their unique user ID. By default, Sendbird server can authenticate a user by a unique user ID. Upon request for a connection, the server queries the database to check for a match. Any untaken user ID is automatically registered as a new user to the Sendbird system, while an existing ID is allowed to log indirectly. The ID must be unique within a Sendbird application, such as a hashed email address or phone number in your service.
134+
135+
This allows you to get up and running without having to go deep into the details of the token registration process, however make sure to enable enforcing tokens before launching as it is a security risk to launch without.
136+
137+
```javascript
138+
// The USER_ID below should be unique to your Sendbird application.
139+
try {
140+
const user = await sb.connect(USER_ID);
141+
// The user is connected to Sendbird server.
142+
} catch (err) {
143+
// Handle error.
144+
}
145+
```
146+
147+
#### B. Using a combination of unique user ID and token
148+
149+
Sendbird prefers that users connect using an access or session token, as it ensures privacy and security for the users.
150+
When [Creating a user](https://sendbird.com/docs/chat/v3/platform-api/guides/user#2-create-a-user) you can choose to generate a users access token or session token.
151+
A comparison between an access tokens and session tokens can be found [here](https://sendbird.com/docs/chat/v3/platform-api/user/managing-session-tokens/issue-a-session-token).
152+
Once a token is issued, a user is required to provide the issued token in the `sb.connect()` method which is used for logging in.
153+
154+
1. Using the Chat Platform API, create a Sendbird user with the information submitted when a user signs up your service.
155+
2. Save the user ID along with the issued access token to your persistent storage which is securely managed.
156+
3. When the user attempts to log in to the Sendbird application, load the user ID and access token from the storage, and then pass them to the `sb.connect()` method.
157+
4. Periodically replacing the user's access token is recommended to protect the account.
158+
159+
```javascript
160+
try {
161+
const user = await sb.connect(USER_ID, ACCESS_TOKEN);
162+
// The user is connected to Sendbird server.
163+
} catch (err) {
164+
// Handle error.
165+
}
166+
```
167+
168+
### Step 6: Create a new open channel
169+
170+
Create an open channel in the following way. [Open channels](https://sendbird.com/docs/chat/v4/ios/guides/open-channel) are where all users in your Sendbird application can easily participate without an invitation.
171+
172+
```javascript
173+
try {
174+
const params = new OpenChannelParams();
175+
const channel = await sb.openChannel.createChannel(params);
176+
177+
// An open channel is successfully created.
178+
// Channel data is return from a successful call to createChannel
179+
...
180+
} catch (err) {
181+
// Handle error.
182+
}
183+
```
184+
185+
### Step 7: Enter the channel
186+
187+
Enter the channel to send and receive messages.
188+
189+
```javascript
190+
await channel.enter();
191+
// The current user successfully enters the open channel
192+
// and can chat with other users in the channel.
193+
...
194+
```
195+
196+
### Step 8: Send a message to the channel
197+
198+
Finally, send a message to the channel. There are [three types](https://sendbird.com/docs/chat/v4/platform-api/guides/messages#-3-resource-representation): a user message, which is a plain text, a file message, which is a binary file, such as an image or PDF, and an admin message, which is a plain text sent through the [dashboard](https://dashboard.sendbird.com/auth/signin) or [Chat Platform API](https://sendbird.com/docs/chat/v4/platform-api/guides/messages#2-send-a-message).
199+
200+
```javascript
201+
const params = new UserMessageParams();
202+
params.message = TEXT_MESSAGE;
203+
204+
channel.sendUserMessage(params)
205+
.onFailed((err: Error, message: UserMessage) => {
206+
// Handle error.
207+
})
208+
.onSucceeded((message: UserMessage) => {
209+
// The message is successfully sent to the channel.
210+
// The current user can receive messages from other users through the onMessageReceived() method of the channel event handler.
211+
...
212+
});
213+
```
214+
215+
<br />
216+
217+
## Additional information
218+
219+
Sendbird wants customers to be confident that Chat SDK will be useful, work well, and fit within their needs. Thus, we have compiled a couple of optional guidelines. Take a few minutes to read and apply them at your convenience.
220+
221+
### XSS prevention
222+
223+
XSS (Cross-site scripting) is a type of computer security vulnerability. XSS helps attackers inject client-side scripts into web pages viewed by other users. Users can send any type of string data without restriction through Chat SDKs. Make sure that you check the safety of received data from other users before rendering it into your DOM.
224+
225+
> **Note**: For more about the XSS prevention, visit the [OWASP's XSS Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html) page.
226+
227+
### Use functions of Sendbird objects with Immutable-js
228+
229+
If you are using the [Immutable-js](https://immutable-js.github.io/immutable-js/) in your web app, instead of the `Immutable.Map()`, call the `Immutable.fromJS()` which converts deeply nested objects to an `Immutable Map`.
230+
So you can call the functions of Sendbird objects because the `fromJS()` method returns internal objects. But if you use a `Map` function, you can't call any functions of a Sendbird object.
231+
232+
```javascript
233+
const userIds = ["John", "Harry"];
234+
235+
const channel = await sb.groupChannel.createChannelWithUserIds(
236+
userIds,
237+
false,
238+
NAME,
239+
COVER_URL,
240+
DATA
241+
);
242+
243+
const immutableObject = Immutable.fromJS(channel);
244+
```
245+
246+
## We are hiring
247+
248+
At Sendbird, we are a diverse group of humble, friendly, and hardworking individuals united by a shared purpose to build the next generation of mobile & social technologies, across chat, voice, and video, that are changing the way we work and live. We're always looking for great people to join our team. [Check out our careers page](https://sendbird.com/careers) for more information.

0 commit comments

Comments
 (0)