Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/calibreapp/react-live-chat-loader

Implement a live chat beacon in your React application without performance regressions.
https://github.com/calibreapp/react-live-chat-loader

chatwoot drift facebook helpscout intercom live-chat messenger performance performance-optimization react react-components reactjs userlike web-performance

Last synced: about 2 months ago
JSON representation

Implement a live chat beacon in your React application without performance regressions.

Awesome Lists containing this project

README 

        
# React Live Chat Loader



[![NPM package](https://img.shields.io/npm/v/react-live-chat-loader?color=informational)](https://www.npmjs.com/package/react-live-chat-loader)

[![License](https://img.shields.io/github/license/calibreapp/react-live-chat-loader?color=informational)](https://github.com/calibreapp/react-live-chat-loader/blob/main/LICENSE)

[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-success)](CODE_OF_CONDUCT.md)

[![Contribution guidelines](https://img.shields.io/badge/PRs-welcome-success)](CONTRIBUTING.md)



An npm module that allows you to mitigate the negative performance and user

experience impact of chat tools. `react-live-chat-loader` shows a fake widget

until the page has become idle or users are ready to interact with chat. Currently works with [Intercom](#intercom), [Help Scout](#help-scout), [Drift](#drift), [Messenger](#messenger), [Userlike](#userlike), [Front](#front), [Chatwoot](#chatwoot) and [Hubspot](#hubspot).



Made by the team at [♠ Calibre](https://calibreapp.com/), your performance companion.



## 🖇️ Table of Contents



1. [How it Works](#-how-it-works)

2. [Installation](#-installation)

3. [Usage](#-usage)

4. [Supported Providers](#-supported-providers)

5. [Adding a Provider](#-adding-a-provider)

6. [Examples](#%EF%B8%8F-examples)

7. [Contributing](#-contributing)

8. [Resources](#-resources)

9. [License](#-license)



## 💡 How it Works



Chat widgets rely heavily on JavaScript which comes at a cost. Given the

significant impact that comes from the download, parse, compile and execution of

chat JavaScript, React Live Chat Loader implements a "fake", fast loading button

and waits for one of the following events before loading the actual widget:



- Person hovers over the fake button

- Person clicks the fake button

- The page has been idle for a significant amount of time



Under the hood React Live Chat Loader makes use of `requestIdleCallback` to

track how long the page has been idle for and checks if the person is on a slow

connection (using `navigator.connection.effectiveType`) or has data-saver enabled

(using `navigator.connection.saveData`) to prevent loading.



> ⚠️ **Please note**: Some chat widget providers open automatically based on the people’s interaction from their last session.



## 📥 Installation



To download react-live-chat-loader run:



```bash

npm install --save react-live-chat-loader

```



Or if you're using yarn, run:



```bash

yarn add react-live-chat-loader

```



## 🛠 Usage



To allow you to trigger a single live chat within your application, React Live

Chat Loader has a `Context Provider` which should be added at the root level of

your application.



You pass your `providerKey` and `provider` to the `LiveChatLoaderProvider`.



For example, to add a `LiveChatLoaderProvider` for Help Scout you would do the

following:



```jsx

import { LiveChatLoaderProvider } from 'react-live-chat-loader'



export default class App extends React.Component {

  /* ... */



  render() {

    return (

      

        /* ... */

      

    )

  }

}

```



You can then include the relevant chat where you would like it to appear.



For example, for Help Scout you would import the `HelpScout` component and add it

to your application:



```jsx

import { HelpScout } from 'react-live-chat-loader'



export default class Index extends React.Component {

  /* ... */



  render() {

    return (

      <>

        /* ... */

        

      >

    )

  }

}

```



To display chat from a custom button you can import the `useChat`

hook which has the current state of the chat and a function to load the

chat.



```jsx

import { useChat } from 'react-live-chat-loader'



export const LoadChatButton = () => {

  const [state, loadChat] = useChat()



  return  loadChat({ open: true })}>Load Chat

}

```



### Options



You can pass the following props to the `LiveChatLoaderProvider` provider:



- `provider`: Choose from `helpScout`, `intercom`, `drift`, `front` or `messenger` ([see below](#-supported-providers))

- `providerKey`: Provider API Key ([see below](#-supported-providers))

- `idlePeriod`: How long to wait in ms before loading the provider. Default is

  `2000`. Set to `0` to never load. This value is used in a `setTimeout` in

  browsers that don't support `requestIdleCallback`.

- `beforeInit`: A function to be called after the script has loaded, but before the chat provider has been initialized (optional)

- `onReady`: A function to be called once the script has been loaded, the chat provider has been initialized and is ready for use (optional)



## 💬 Supported Providers



Currently there are eight supported providers:



Help Scout



To use Help Scout import the `LiveChatLoaderProvider` and set the `provider` prop

as `helpScout` and the `providerKey` prop as your Beacon API Key.



Then import the `HelpScout` component.



```jsx

import { LiveChatLoaderProvider, HelpScout } from 'react-live-chat-loader'



export default class App extends React.Component {

  render() {

    return (

      

        /* ... */

        

      

    )

  }

}

```



You can customise the Help Scout placeholder by passing the following props to the

`HelpScout` component:



- `color`: The background color of the placeholder

- `icon`: Choose from `message`, `antenna`, `search`, `question`, `beacon`

- `zIndex`: Changes the CSS index value of how the placeholder relates to other objects

- `horizontalPosition`: Choose from `left` or `right`

- `containerClass`: Class to be added to the placeholder element, defaults to `live-chat-loader-placeholder`



Currently the Help Scout component only supports the icon button style.



Intercom



To use Intercom import the `LiveChatLoaderProvider` and set the `provider` prop

as `intercom` and the `providerKey` prop as your Intercom App ID.



Then import the `Intercom` component.



```jsx

import { LiveChatLoaderProvider, Intercom } from 'react-live-chat-loader'



export default class App extends React.Component {

  render() {

    return (

      

        /* ... */

        

      

    )

  }

}

```



You can customise the Intercom placeholder icon by passing the following props to the `Intercom` component:



- `color`: The background color of the placeholder widget

- `containerClass`: Class to be added to the placeholder element, defaults to `live-chat-loader-placeholder`



[Messenger Settings](https://developers.intercom.com/installing-intercom/docs/javascript-api-attributes-objects#messenger-attributes), User context and Company context settings can be set using `window.intercomSettings`. See the [official Intercom documentation](https://developers.intercom.com/installing-intercom/docs/javascript-api-attributes-objects#section-data-attributes) for more details.



Messenger



To use Messenger, import the `LiveChatLoaderProvider` and then set the `provider` prop as `messenger` and the `providerKey` prop as your Facebook Page ID.



If you are using other Facebook features like share, you should set the `appID` prop as your Facebook App ID as the Customer Chat SDK includes all the features that Facebook provide.



You can optionally set the `locale` prop, the default value is `en_US`.



Then import the `Messenger` component.



```jsx

import { LiveChatLoaderProvider, Messenger } from 'react-live-chat-loader'



export default class App extends React.Component {

  render() {

    return (

      

        /* ... */

        

      

    )

  }

}

```



For a list of locale option values, refer to [Facebook Localization documentation](https://developers.facebook.com/docs/internationalization).



You can customise the Messenger widget by passing the following props to the

`Messenger` component:



- `color`: The theme color of the widget

- `loggedInGreeting`: The greeting text that will be displayed if the person is currently logged in to Facebook.

- `loggedOutGreeting`: The greeting text that will be displayed if the person is

  currently not logged in to Facebook.

- `greetingDialogDisplay`: Sets how the greeting dialog will be displayed.

- `greetingDialogDelay`: Sets the number of seconds of delay before the greeting dialog is shown after the plugin is loaded.

- `containerClass`: Class to be added to the placeholder element, defaults to `live-chat-loader-placeholder`



For a list of options, refer to [Facebook Customer Chat Plugin documentation](https://developers.facebook.com/docs/messenger-platform/discovery/customer-chat-plugin#customization).



> ⚠️ **Please note**: Facebook Messenger will not load on localhost and you will need to configure your domain through the setup wizard in Facebook for it to load correctly.



Drift



To use Drift import the `LiveChatLoaderProvider` and set the `provider` prop

as `drift` and the `providerKey` prop as your Drift App ID.



Then import the `Drift` component.



```jsx

import { LiveChatLoaderProvider, Drift } from 'react-live-chat-loader'



export default () => (

  

    /* ... */

    

  

)

```



You can customise the Drift placeholder by passing the following props to the

`Drift` component:



- `color`: The background color of the placeholder

- `icon`: Choose from `A`, `B`, `C`, `D`; you're presented with these preset icons when signing up for Drift, or in the "Drift Widget > Design > Widget icon" entry under the "App Settings" header on the Drift settings page.

- `containerClass`: Class to be added to the placeholder element, defaults to `live-chat-loader-placeholder`



Userlike



To use Userlike import the `LiveChatLoaderProvider` and set the `provider` prop

as `userlike` and the `providerKey` prop as your Userlike Widget secret.



Then import the `Userlike` component.



```jsx

import { LiveChatLoaderProvider, Userlike } from 'react-live-chat-loader'



export default () => (

  

    /* ... */

    

  

)

```



You can customise the Userlike placeholder by passing the following props to the

`Userlike` component:



- `color`: The contrasting color, can be `black` or `white`.

- `backgroundColor`: The main color

- `position`: The button position, can be `right` or `left`.

- `vOffset`: The amount of vertical margin.

- `hOffset`: The amount of horizontal margin.

- `style`: The shape style, can be `round` or `square`.

- `containerClass`: Class to be added to the placeholder element, defaults to `live-chat-loader-placeholder`



Chatwoot



To use Chatwoot import the `LiveChatLoaderProvider` and set the `provider` prop

as `chatwoot` and the `providerKey` prop as your Chatwoot secret.



You can optionally set the `locale` and `baseUrl` props.



Then import the `Chatwoot` component.



```jsx

import { LiveChatLoaderProvider, Chatwoot } from 'react-live-chat-loader'



export default () => (

  

    /* ... */

    

  

)

```



You can customise the Chatwoot placeholder by passing the following props to the

`Chatwoot` component:



- `color`: The background color, set to same color value you choose in Chatwoot dashboard.

- `containerClass`: Class to be added to the placeholder element, defaults to `live-chat-loader-placeholder`



Front



To use Front import the `LiveChatLoaderProvider` and set the `provider` prop

as `front` and the `providerKey` prop as your Front Chat `chatId`.



Then import the `Front` component.



```jsx

import { LiveChatLoaderProvider, Front } from 'react-live-chat-loader'



export default () => {

  return (

    

      /* ... */

      

    

  )

}

```



You can customise the Front placeholder icon by passing the following props to the `Front` component:



- `color`: The background color of the placeholder widget.

- `containerClass`: Class to be added to the placeholder element, defaults to `live-chat-loader-placeholder`



See the [official Front documentation](https://help.front.com/) for more details.



Hubspot



To use Hubspot import the `LiveChatLoaderProvider` and set the `provider` prop

as `hubSpot` and the `providerKey` prop as your Hubspot API Key.



Then import the `Hubspot` component.



```jsx

import { LiveChatLoaderProvider, Hubspot } from 'react-live-chat-loader'



export default class App extends React.Component {

  render() {

    return (

      

        /* ... */

        

      

    )

  }

}

```



You can customise the Hubspot placeholder by passing the following props to the

`Hubspot` component:



- `backgroundColor`: The background color of the placeholder

- `loader`: A react component shown while the Hubspot libraries are loading



## ➕ Adding a Provider



To add a new live chat provider, follow the steps in [Contributing: Adding a Provider](CONTRIBUTING.md#-adding-a-provider).



## 🖥️ Examples



The [website](https://github.com/calibreapp/react-live-chat-loader/tree/master/website) directory of this repository includes a [Next.js](https://nextjs.org) app with example implementations of all currently supported providers.



For the initial setup of the example app, be sure first to run `npm install` + `npm run build` in the root level of the repository before running `npm install` in the `website` directory.



The following scripts in the example app will then be available:



- `npm run dev` (run a local server)

- `npm run build` (run next build)

- `npm run start` (run next start)



Visit [react-live-chat-loader.vercel.app](https://react-live-chat-loader.vercel.app/) for a hosted version of the example app.



> 📝  Note that some providers require safe-listed, publicly accessible domains served over HTTPS — a service like [ngrok](https://ngrok.com/) can help achieve this locally.



## 🙌 Contributing



Happy to hear you’re interested in contributing to React Live Chat Loader! Please find our contribution guidelines [here](CONTRIBUTING.md).



### Past Contributors



Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):



  

    
Kevin Peng
💻

    
Ash Kyd
📖

    
Jeff Reiner
📖 💻

    
Joan Mira
💻

    
Nathan Collman
💻

    
Jaakko Mustalahti
💻

    
Moti Korets
💻

  

  

    
Michael Stramel
💻

    
Myles Linder
💻

    
Laura Gutiérrez López de la Franca
💻

    
Kirill Vakalov
💻

    
Luís Rudge
💻

  



This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!



## 📚 Resources



- [How to avoid performance regressions when using live chat tools](https://calibreapp.com/blog/fast-live-chat)

- [Reducing the Intercom Messenger bundle size by 65%](https://www.intercom.com/blog/reducing-intercom-messenger-bundle-size/)



## 💼 License



This project is [MIT licensed](LICENSE).