diff --git a/README.md b/README.md index d2e64bb..10389c3 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ This project demonstrates what an events experience is like, built using React. | | Chat with other participants* | | | | Promote a viewer to co-host* | | -> * Requires a PubNub account to work on these features. +> * Requires a PubNub account to work. ## Requirements and supported platforms @@ -43,18 +43,106 @@ Refer to [this guide](#how-to-get-a-dolbyio-account) on how to obtain your Dolby [![Deploy to Netlify from fork](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/dolbyio-samples/comms-app-react-events) -## Running locally +## Getting Started -Please see [the events package readme](./events/README.md) for information on how to run the app locally. +The following steps will quickly get you started testing the Dolby.io Communications APIs capabilities. + +### Pre-requisites + +To build this app, you will need a Dolby.io account (see the **How to get a Dolby.io account** section). + +You will also need to install the following: + +* [Node v18.0.0 or higher](https://nodejs.org/en/download) +* [NPM v8.11 or higher](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +* [Yarn v1.22.19](https://classic.yarnpkg.com/lang/en/docs/install/#mac-stable) + +### Basic terminology + +As you browse through the source code and documents, you might come across some of these terms: + +* **A host** is a participant with additional permissions to manage the conference and other participants. +* **A viewer** is a participant who can only receive video and audio stream from the conference. +* A **proxy-app-server** is an intermediary API server that communicates with the Dolby.io Communications Platform in order to provide functionality such as RTS/RTMP/HLS streaming or consuming web-hook data. You can see our sample implementation [here](./backend). ### How to get a Dolby.io account -To setup your Dolby.io account, go to the [Dolby.io dashboard](https://dolby.io) and register for an account. After confirming your email address, you will be logged in. +To set up your Dolby.io account, go to [Dolby.io](https://dolby.io) and register for an account. After confirming your email address, you will be logged in. > If you did not receive a verification email, check your Spam or Junk email folders. +#### Setting up your [Dolby.io](https://dashboard.dolby.io) app + +To set up your app for events, you will need to: + +1. Go to the _Dashboard_, and click `add new app` if you do not have an existing app. ![dashboard](events/documentation//dashboard-events.png) +2. To enable events streaming, your app should be opted into the open beta program. You can find this at the bottom of the `Communications APIs` sidebar navigation when you click on your app. + + ![dashboard](events/documentation/open-beta.png) + +## How to run the Events app + +To run the application locally, clone the repository and then perform the following steps. + +### Install dependencies + +**note** : This guide is written with [Yarn](https://yarnpkg.com/) in mind. We have not validated this project with other package managers. + +Open a terminal window in the root directory of your project folder. Install the project's dependencies using the following command. + +```bash +yarn +``` + +### Repo structure + +The code in this repository is organised in the following way + +* The `/events/src/` directory contains all the front-end code for the events app. Within this directory: + * `hooks/` contains wrapper functions around our SDK for re-usable functionality. + * `components/` contains UI components that encapsulate and provide functionality. + * `utils/` provides some generic helper functions. + * `context/` contains the React Context for the side drawer and the main component window. + +* The `/backend/` contains the code for the proxy server. + +This project is built with the [Comms UI Kit for React](https://github.com/dolbyio/comms-uikit-react) library for simplicity and re-use of standard Communications API-based components. + +### Set up `.env` file + +Create a new file called `.env` in the `events` folder and copy the contents of `.env.example` into it. + +You will need to provide the values for `KEY` and `SECRET` from your Dolby.io app. To obtain your key and secret from the Dolby.io dashboard: + +1. Go to the _Dashboard_ and click on the `API Keys` next to your application. + ![dashboard](events/documentation/dashboard.png) +2. On the next screen, copy the `App key` and `App secret` and paste them in your `.env` file against the marked variables. + ![token](events/documentation/client_access_token.png) + +To enable chat and the ability to promote a viewer to host, you will need to provide your `PUBNUB_PUBLISH_KEY`, `PUBNUB_SUBSCRIBE_KEY`, and `PUBNUB_SECRET_KEY` as well. To setup PubNub, please go through the [enabling chat guide in our customization guide](customization.md/#enabling-chat-and-promoting-a-viewer-to-co-host). + +The secrets will not be exposed on the frontend. + +#### Running the app + +To run the application locally, execute the command below inside the `/events` directory. + +```bash +yarn dev +``` + +#### Open the app in a browser + +Once the dev server starts, open in the browser. The application will launch at this address and will look like the screenshot below. + +![built](events/documentation/home.png) + +## Making the App your own + +Follow our [customization guide](./customization.md) to better understand how you can extend the app to make it your own. + ## More resources Want to experience the app without building it? Try our Virtual Events [Demo app](https://events.experience.dolby.io). -Looking for more sample apps and projects? Head to the [Dolby.io Project Gallery](https://docs.dolby.io/communications-apis/page/gallery). \ No newline at end of file +Looking for more sample apps and projects? Head to the [Dolby.io Project Gallery](https://dolby.io/project-gallery/). diff --git a/events/customization.md b/customization.md similarity index 93% rename from events/customization.md rename to customization.md index 566487f..80d6970 100644 --- a/events/customization.md +++ b/customization.md @@ -2,7 +2,7 @@ ## Changing the labels in the app -To change the labels in the app, you can modify [en.json](src/translations/en.json) and change the labels as necessary. +To change the labels in the app, you can modify [en.json](events/src/translations/en.json) and change the labels as necessary. To add a new string, add a new key-value pair to the JSON file. You can then reference that new key in the code as follows: ```javascript @@ -38,9 +38,7 @@ To add a company logo in place of our placeholder `logo` in the events app, you // You will need to wrap your `img` in a div tag to make sure it fits in fine and doesn't bloat the size of the TopBar. ``` -## Enabling chat - -### Chat +## Enabling chat and promoting a viewer to co-host The chat and "promoting a viewer to a co-host" features in this sample app are powered by [PubNub](https://www.pubnub.com). PubNub allows us to asynchronously send messages across all instances of an event with low latency and thus offering a compelling experience. You can get started with PubNub by following [this guide](https://www.pubnub.com/docs/general/basics/set-up-your-account). diff --git a/events/README.md b/events/README.md deleted file mode 100644 index 2dd1a1b..0000000 --- a/events/README.md +++ /dev/null @@ -1,94 +0,0 @@ -# Dolby.io Events React App - -## Getting Started - -The following steps will quickly get you started testing the Dolby.io Communications APIs capabilities. - -### Pre-requisites - -To get started building this app you will need a Dolby.io account. You will also need the following - - -- [NPM v8.11 or higher](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) -- [Yarn v1.22.19](https://classic.yarnpkg.com/lang/en/docs/install/#mac-stable) -- [Node v18.0.0 or higher](https://nodejs.org/en/download) - -### Basic terminology - -As you browse through the source code and documents, you might come across some of these terms - -- **A host** is a participant with additional permissions to manage the conference and other participants. -- **A viewer** is a participant who can only receive video and audio stream from the conference. -- A **proxy-app-server** is an intermediary API server that communicates with the Dolby.io Communications Platform in order to provide functionality such as RTS/RTMP/HLS streaming or consuming web-hook data. You can see our sample implementation [here](./api-proxy). - -### How to get a Dolby.io account - -To setup your Dolby.io account, go to the [Dolby.io dashboard](https://dolby.io) and register for an account. After confirming your email address, you will be logged in. - -> If you did not receive a verification email, check your Spam or Junk email folders. - -#### Setting up your [Dolby.io](https://dashboard.dolby.io) app - -To set up your app for events, you will need to: - -1. Go to the _Dashboard_, and click `add new app` if you do not have an existing app. ![dashboard](./documentation/dashboard-events.png) -2. To enable events streaming, your app should be opted into the open beta program. You can find this at the bottom of the `Communications APIs` sidebar navigation when you click on your app. ![dashboard](./documentation/open-beta.png) - -## How to run the Events app - -Run the following steps after cloning the repository to run the application locally. - -### Install dependencies - -**note** : This guide is written with [Yarn](https://yarnpkg.com/) in mind. We have not validated this project with other package managers. - -Open a terminal window in the root directory of your project folder. Install the project's dependencies using the following command. - -```bash -yarn -``` - -### Repo structure - -The code in this repository is organised in the following way - -- The `src/` directory contains all the front-end code for the events app. Within this directory - - `hooks/` contains wrapper functions around our SDK for re-usable functionality. - - `components/` contains UI components that encapsulate and provide functionality. - - `utils/` provides some generic helper functions. - - `context/` contains the React Context for the side drawer and the main component window. -- The `api-proxy/` contains the code for the proxy server. - -This project is built with the [Comms UI Kit for react](https://github.com/dolbyio/comms-uikit-react) library for simplicity and re-use of standard Communications API based components. - -### Set up `.env` file - -Create a new file called `.env` in the `events` folder, and copy the contents of `.env.example` into it. - -You will need to provide the values for `KEY` and `SECRET` from your dolby.io app. To obtain your key and secret from the Dolby.io dashboard, - -1. Go to the _Dashboard_, and click on the `API Keys` next to your application. - ![dashboard](docs/img/dashboard.png) -2. On the next screen, copy the `App key` and `App secret` and paste them in your `.env` file against the marked variables. - ![token](docs/img/client_access_token.png) - -If you want chat and the ability to promote a viewer to host, you will need to provide your `PUBNUB_PUBLISH_KEY`, `PUBNUB_SUBSCRIBE_KEY`, and `PUBNUB_SECRET_KEY` as well. To setup PubNub, please go through the [PubNub setup guide](customization.md/#enabling-chat-and-hot-swapping). - -The secrets will not be exposed on the frontend. - -#### Start the app - -Execute the following command to run the application locally in a terminal window inside the `/events/` directory. - -```bash -yarn dev -``` - -#### Open the app in a browser - -After the appropriate message appears in the terminal window, open in the browser. The application will launch at this address and will look like the screenshot below. - -![built](./documentation/home.png) - -## Making the App your own - -Follow our [customization guide](./customization.md) to better understand how you can extend the app to make it your own. \ No newline at end of file diff --git a/backend/img/client_access_token.png b/events/documentation/client_access_token.png similarity index 100% rename from backend/img/client_access_token.png rename to events/documentation/client_access_token.png diff --git a/backend/img/dashboard.png b/events/documentation/dashboard.png similarity index 100% rename from backend/img/dashboard.png rename to events/documentation/dashboard.png