diff --git a/README.md b/README.md index 55297bda..b073c69e 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,37 @@ -# js-chat -PubNub JavaScript Chat SDK +# PubNub JavaScript Chat SDK + +Chat SDK offers a set of handy methods to create your own feature-rich chat or add a chat to your existing application. + +## Supported frameworks + +Chat SDK is written in TypeScript and relies on the existing [JavaScript SDK](https://www.pubnub.com/docs/sdks/javascript). It's framework-agnostic and lets you build a chat app using any JavaScript-based framework, like: + +* React +* React Native +* Vue +* Angular + +## Features + +Chat SDK offers a wide range of features to build direct, group, and public chats. + +Explore these documentation sections for details: + +* **Channels** - manage [channels](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/create), [join](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/join) or [leave](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/leave) them, [invite](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/invite) other chat members, or [reference channel names](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/references) in messages through hashtags. +* **Users** - manage [users](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/create), track user's [presence](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/presence), [mention](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/mentions) users, manage [permissions](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/permissions) or [report](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/moderation) users for misbehaving. +* **Messages** - manage [messages](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/send-receive), add [reactions](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/reactions), [forward](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/forwards) messages to others, [pin](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/pinned) them to channels, add [quotes](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/quote) or [links](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/links), create [threads](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/threads) or send [files](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/files), [report](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/moderation) offensive messages, or shows users how many messages they missed while they were offline through [unread messages](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/unread). + +Also, add [typing indicators](https://www.pubnub.com/docs/chat/chat-sdk/build/features/typing-indicator), [push notifications](/docs/chat/chat-sdk/build/features/push-notifications), and more. + +## Samples + +Test our TypeScript sample chat apps created in various JavaScript frameworks: + +| Source code | Framework | Description | +| :--- | :---| :---| +| [Direct chat](https://github.com/pubnub/js-chat/tree/master/samples/getting-started) | React | Basic 1:1 support chat letting you exchange messages between a user and a support agent. | +| [Group chat](https://github.com/pubnub/js-chat/tree/master/samples/react-native-group-chat) | React Native | Feature-full group chat letting you test most of the features offered by the Chat SDK. | + +## Chat SDK docs + +You'll find all the information about working with Chat SDK in the official [PubNub Chat SDK documentation](pubnub.com/docs/chat/chat-sdk/overview). diff --git a/samples/README.md b/samples/README.md index b2483c54..39ca1679 100644 --- a/samples/README.md +++ b/samples/README.md @@ -4,12 +4,7 @@ This folder contains sample applications created with Chat SDK and various frame Follow the instructions behind the links to run a chosen app. -- [Vue](/samples/vue/README.md) -- [Angular](/samples/angular/README.md) +* [getting-started](https://github.com/pubnub/js-chat/tree/master/samples/getting-started) +* [react-native-group-chat](https://github.com/pubnub/js-chat/tree/master/samples/react-native-group-chat) -It also contains e2e automation tests covered with Playwright framework. - -Follow the instructions behind the link to setup Playwright framework locally or execute e2e tests. - -- [Setup](https://playwright.dev/docs/intro) -- [Test run](https://playwright.dev/docs/running-tests) +This folder also contains [e2e automation tests](https://github.com/pubnub/js-chat/tree/master/samples/e2e-tests) covered with Playwright framework. diff --git a/samples/e2e-tests/README.md b/samples/e2e-tests/README.md new file mode 100644 index 00000000..a81603db --- /dev/null +++ b/samples/e2e-tests/README.md @@ -0,0 +1,8 @@ +# End-to-end automation tests + +This folder contains e2e automation tests covered with Playwright framework. + +Follow the instructions behind the link to set up Playwright framework locally or execute e2e tests. + +* [Setup](https://playwright.dev/docs/intro) +* [Test run](https://playwright.dev/docs/running-tests) diff --git a/samples/getting-started/README.md b/samples/getting-started/README.md new file mode 100644 index 00000000..042bd365 --- /dev/null +++ b/samples/getting-started/README.md @@ -0,0 +1,36 @@ +# Getting started app + +This Getting Started app shows how to set up a direct (1:1) chat using Chat SDK and React. + +It comes with a pre-defined UI to showcase what the final product might look like. + +This app is written using: + +* [PubNub Chat SDK](https://github.com/pubnub/js-chat) +* [TypeScript](https://www.typescriptlang.org/) (v5.0.2) +* [React](https://legacy.reactjs.org/versions/) (v18.2.0) +* [Vite](https://vitejs.dev/) (v4.3.9) + +## Prerequisites + +To run the Getting Started app, make sure to have the following: + +* [yarn](https://classic.yarnpkg.com/en/docs/install)(>=1.22.19) +* [Node.js](https://nodejs.org/en/download/)(>=18.10.0) +* Code Editor (e.g. [Visual Studio Code](https://code.visualstudio.com/download)) +* PubNub [Publish & Subscribe keys](https://www.pubnub.com/docs/basics/initialize-pubnub) that you can obtain from [Admin Portal](https://admin.pubnub.com/) after setting up an [account](https://www.pubnub.com/docs/setup/account-setup). The autogenerated **Demo Keyset** in **My First App** on the Admin Portal already contains the configuration required to complete this guide (enabled **App Context** and selected region). + +## Usage + +To run the app locally, follow the steps in the [Getting Started guide](https://www.pubnub.com/docs/chat/chat-sdk/build/sample-chat). + +## Features + +The app shows these PubNub features: + +* Direct (1:1) [channel creation](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/create). +* [User creation](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/create). +* [Sending and receiving](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/send-receive) messages. +* Showing [time indicator](https://www.pubnub.com/docs/chat/chat-sdk/build/features/utility-methods) for published messages based on the PubNub timetoken. + +Still, these are only some of the features available in Chat SDK. For the complete overview, check [Chat SDK docs](https://www.pubnub.com/docs/chat/chat-sdk/overview). diff --git a/samples/react-native-group-chat/README.md b/samples/react-native-group-chat/README.md new file mode 100644 index 00000000..72f837dd --- /dev/null +++ b/samples/react-native-group-chat/README.md @@ -0,0 +1,112 @@ +# Group chat app + +This React Native Group Chat app shows how to use Chat SDK to set up a conversation between multiple chat users. + +The app comes with a pre-defined UI to showcase what the final product might look like. + +This app is written using: + +* [PubNub Chat SDK](https://github.com/pubnub/js-chat) +* [TypeScript](https://www.typescriptlang.org/) (v^5.1.3) +* [Expo](https://expo.dev/) (v~49.0.8) +* [React](https://legacy.reactjs.org/versions/) (v18.2.0) +* [React Native](https://reactnative.dev/) (v0.72.4) + +## Prerequisites + +To run the React Native Group Chat app, make sure to have the following: + +* [yarn](https://classic.yarnpkg.com/en/docs/install)(>=1.22.19) +* [Node.js](https://nodejs.org/en/download/)(>=18.10.0) +* [Xcode](https://developer.apple.com/xcode/) +* Code Editor (e.g. [Visual Studio Code](https://code.visualstudio.com/download)) +* PubNub [Publish & Subscribe keys](https://www.pubnub.com/docs/basics/initialize-pubnub) that you can obtain from [Admin Portal](https://admin.pubnub.com/) after setting up an [account](https://www.pubnub.com/docs/setup/account-setup). You must enable **App Context** (with selected region, User Metadata Events, Channel Metadata Events, and Membership Metadata Events) and **Message Persistence** on your keyset to manage user and channel data in the app. + +## Usage + +To run the app on an iOS simulator, follow these steps: + +1. Open the terminal, select the location, and download the Chat SDK. + + ```ssh showLineNumbers + git clone git@github.com:pubnub/js-chat.git + ``` + +1. Go to the downloaded repository folder. + + ```bash showLineNumbers + cd js-chat-master + ``` + +1. Install all the required dependencies. + + ```bash showLineNumbers + yarn + ``` + +1. Go to the `lib` folder that contains the TypeScript sources. + + ```bash showLineNumbers + cd lib + ``` + +1. Bundle the TypeScript library and compile it to a JavaScript script. + + ```bash showLineNumbers + yarn build + ``` + +1. Go to the `samples/react-native-group-chat` folder with the app's source code. + + ```bash showLineNumbers + cd ../samples/react-native-group-chat + ``` + +1. Add your publish and subscribe keys. + + Open the app in the code editor. Under the `samples/react-native-group-chat` folder, create a `.env` file and use it to specify values for [your publish and subscribe keys](/docs/chat/chat-sdk/build/sample-chat#get-pubsub-keys) from your app's keyset on the Admin Portal. + + ```ts showLineNumbers + EXPO_PUBLIC_PUBNUB_PUB_KEY= + EXPO_PUBLIC_PUBNUB_SUB_KEY= + ``` + +1. Run the app in the terminal. + + ```bash showLineNumbers + yarn ios + ``` + +1. When the Xcode iOS simulator opens up successfully, you will see a login screen to the app. Log into the app and start playing with all available [Chat SDK features](#features). + +## Features + +The app showcases these PubNub features: + +Channels: + +* [Group channel creation](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/create) +* [Channel references](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/references) +* [Inviting](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/invite) users to channels +* [Joining](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/join) channels + +Users: + +* [User profile editing](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/updates) +* [User mentions](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/mentions) +* [Global (app) presence](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/presence#global-presence) + +Messages: + +* [Sending and receiving](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/send-receive) messages +* [Threads](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/threads) +* [Unread messages](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/unread) +* [Reactions](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/reactions) +* [Quotes](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/quotes) +* [Plain links](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/files) + +Other: + +* [Typing indicator](https://www.pubnub.com/docs/chat/chat-sdk/build/features/typing-indicator) + +Still, these are only some of the features available in Chat SDK. For the complete overview, check [Chat SDK docs](https://www.pubnub.com/docs/chat/chat-sdk/overview).