|
| 1 | +# Contributing |
| 2 | + |
| 3 | +Thank you for your interest in contributing to React Live Chat Loader! 🙌🏻 Below, you will find everything you need to get started. |
| 4 | + |
| 5 | +## 🖇️ Table of Contents |
| 6 | + |
| 7 | +1. [Code of Conduct](CODE_OF_CONDUCT.md) |
| 8 | +2. [Reporting Bugs](#reporting-bugs) |
| 9 | +3. [Suggesting Features](#suggesting-features) |
| 10 | +4. [Creating Pull Requests](#creating-pull-requests) |
| 11 | +5. [Adding a Provider](#adding-a-provider) |
| 12 | + |
| 13 | +## 📣 Code of Conduct |
| 14 | +This project and everyone participating in it are governed by this [Code of Conduct ](CODE_OF_CONDUCT.md). By participating, we expect you to act accordingly to this code. Please report unacceptable behaviour to [email protected]. |
| 15 | + |
| 16 | +## 🐛 Reporting Bugs |
| 17 | +Before creating a bug report, see if the problem [has already been reported](https://github.com/calibreapp/react-live-chat-loader/issues). If yes, and **the issue is still open**, add a comment to the existing issue instead of creating a new one. |
| 18 | + |
| 19 | +When creating a bug report, please **provide as much information and context as possible** to help the maintainers quickly identify and resolve problems: |
| 20 | + |
| 21 | +1. **Describe the bug.** Please provide a clear and concise description of what the bug is. |
| 22 | +2. **Explain how to reproduce.** Outline the steps to reproduce the behaviour, including any relevant information such as operating system, browser type and version, etc. |
| 23 | +3. **Outline the expected behaviour.** Describe what you expected to happen clearly and concisely. |
| 24 | +4. **Add screenshots.** If applicable, add screenshots to help explain the problem. |
| 25 | + |
| 26 | +You will be [guided to provide relevant information](.github/ISSUE_TEMPLATE/---bug-report.md) as you create the issue. |
| 27 | + |
| 28 | +## 💡 Suggesting Features |
| 29 | + |
| 30 | +Before suggesting a new feature, see if [has already been suggested](https://github.com/calibreapp/react-live-chat-loader/issues?q=is%3Aissue+is%3Aopen+Feature+request). If yes, and **the issue is still open**, add a comment to the existing issue instead of creating a new one. |
| 31 | + |
| 32 | +When filing a feature request, please **provide as much information and context as possible** to help the maintainers triage issues: |
| 33 | + |
| 34 | +1. **What problem would this feature solve?** A clear and concise description of what the problem is. |
| 35 | +2. **Describe the solution you’d like to see.** A clear and concise description of what you would like to happen. Are you willing to work on implementing this solution? |
| 36 | +3. **Describe alternatives you’ve considered.** A clear and concise description of any alternative solutions or features you’ve considered. |
| 37 | + |
| 38 | +You will be [guided to provide relevant information](.github/ISSUE_TEMPLATE/---feature-request.md) as you create the feature request. |
| 39 | + |
| 40 | +## 📝 Creating Pull Requests |
| 41 | +We welcome contributions to React Live Chat Loader that: |
| 42 | + |
| 43 | +* improve the quality, security and performance of the library |
| 44 | +* resolve existing issues and feature requests |
| 45 | +* add new live chat providers |
| 46 | + |
| 47 | +Please follow these steps to have your contribution considered by the maintainers: |
| 48 | + |
| 49 | +1. Follow instructions in the [pull request template](.github/pull_request_template.md). |
| 50 | +2. Sign a CLA. |
| 51 | +3. Verify that checks are passing. |
| 52 | + |
| 53 | +You must meet the above requirements to have your pull request reviewed. The maintainer(s) may ask you to complete additional work, tests, or other changes before your pull request is accepted and merged. |
| 54 | + |
| 55 | +## ➕ Adding a Provider |
| 56 | + |
| 57 | +To contribute a new provider, follow these steps: |
| 58 | + |
| 59 | +### 1. Create provider file |
| 60 | + |
| 61 | +Create a new provider file at `src/providers/providerName.js` using the |
| 62 | +following as a template: |
| 63 | + |
| 64 | +<details> |
| 65 | +<summary>Provider Template</summary> |
| 66 | + |
| 67 | +```js |
| 68 | +const domain = 'https://provider.domain.com' |
| 69 | + |
| 70 | +const loadScript = () => { |
| 71 | + // Detect the provider is already loaded and return early |
| 72 | + if (alreadyLoaded) return |
| 73 | + |
| 74 | + // Call provider script here |
| 75 | +} |
| 76 | + |
| 77 | +const load = ({ providerKey }) => { |
| 78 | + loadScript() |
| 79 | + // Initialise provider script |
| 80 | +} |
| 81 | + |
| 82 | +const open = () => // Open provider |
| 83 | +const close = () => // Close provider |
| 84 | + |
| 85 | +export default { |
| 86 | + domain, |
| 87 | + load, |
| 88 | + open, |
| 89 | + close |
| 90 | +} |
| 91 | +``` |
| 92 | + |
| 93 | +</details> |
| 94 | + |
| 95 | +The provider must export the following: |
| 96 | + |
| 97 | +- `domain`: A string of the domain where the provider script is loaded from |
| 98 | + that will be used in a `preconnect` link. |
| 99 | +- `load`: Function which when called will load and initialize the provider |
| 100 | + script. It should accept props and use the `providerKey` as the `app_id` or |
| 101 | + `api_key`. For consistency, it should call a `loadScript` function. |
| 102 | +- `open`: Function which when called will open the provider chat. |
| 103 | +- `close`: Function which when called will close the provider chat. |
| 104 | + |
| 105 | +Import the new file in `src/providers/index.js` and add it to `Providers`. |
| 106 | + |
| 107 | +The name of this file will be the `providerKey` used in the |
| 108 | +`LiveChatLoaderProvider`. |
| 109 | + |
| 110 | +### 2. Create component |
| 111 | + |
| 112 | +Create a new component in `src/Components/ProviderName/index.js` which |
| 113 | +replicates the chat widget, using the following as a template: |
| 114 | + |
| 115 | +<details> |
| 116 | +<summary>Component Template</summary> |
| 117 | + |
| 118 | +```jsx |
| 119 | +import React from 'react' |
| 120 | + |
| 121 | +import { useChat } from '../../' |
| 122 | +import STATES from '../../utils/states' |
| 123 | + |
| 124 | +const styles = { |
| 125 | + // Add widget styles here |
| 126 | + button: { |
| 127 | + // Add button styles here |
| 128 | + } |
| 129 | +} |
| 130 | + |
| 131 | +const Provider = ({ color }) => { |
| 132 | + const [state, loadChat] = useChat({ loadWhenIdle: true }) |
| 133 | + |
| 134 | + if (state === STATES.COMPLETE) return null |
| 135 | + |
| 136 | + return ( |
| 137 | + <div> |
| 138 | + <button |
| 139 | + onClick={() => loadChat({ open: true })} |
| 140 | + onMouseEnter={() => loadChat({ open: false })} |
| 141 | + style={{ |
| 142 | + ...styles.button, |
| 143 | + backgroundColor: color |
| 144 | + }} |
| 145 | + > |
| 146 | + Button |
| 147 | + </button> |
| 148 | + </div> |
| 149 | + ) |
| 150 | +} |
| 151 | + |
| 152 | +Provider.defaultProps = { |
| 153 | + color: '#976ad4' |
| 154 | +} |
| 155 | + |
| 156 | +export default Provider |
| 157 | +``` |
| 158 | + |
| 159 | +</details> |
| 160 | + |
| 161 | +Do not worry about loading animations as the widget |
| 162 | +will be shown instantly on page load. Increase the `z-index` by `1` so the fake |
| 163 | +widget sits immediately above the chat widget that is being replaced. |
| 164 | + |
| 165 | +Export the component from `src/index.js` |
| 166 | + |
| 167 | +### 3. Update README |
| 168 | + |
| 169 | +Add your new provider to this README under [Supported Providers](#supported-providers). |
| 170 | + |
| 171 | +### 4. Add an example page |
| 172 | + |
| 173 | +Add a new page to `website/pages/` which showcases the provider. If you don't want to include your `providerKey` leave this blank and the maintainers will set one up. |
| 174 | + |
| 175 | +The new provider page can be tested locally by creating a distribution version of the package and referencing this from the `website`. |
| 176 | + |
| 177 | +Unfortunately if you try to include the package locally from source you'll most likely run into a [Duplicate React](https://reactjs.org/warnings/invalid-hook-call-warning.html#duplicate-react) error. |
| 178 | + |
| 179 | +To create the distribution version and reference it, do the following: |
| 180 | + |
| 181 | +- In the root of the project, run `npm run build` to build the package into `dist` |
| 182 | +- Update `website/package.json` to reference the `dist` build: `"react-live-chat-loader": "../"` |
| 183 | +- In the `website` directory run `npm install` |
| 184 | +- In the `website` directory run the server with `npm run dev` |
| 185 | +- Add a new page to `website/pages/` which includes the new component |
| 186 | +- Add a link to the provider in `website/pages/index.js` |
| 187 | +- Add a link to the provider in `website/components/exampleLinks.js` |
0 commit comments