Implement a live chat beacon in your React application without performance regressions.
An npm module that allows you to mitigate the negative performance and user experience impact of chat tools.
react-live-chat-loadershows a fake widget until the page has become idle or users are ready to interact with chat. Currently works with Intercom, Help Scout, Drift and Messenger.
Made by the team at ♠ Calibre, your performance companion.
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:
Under the hood React Live Chat Loader makes use of
requestIdleCallbackto track how long the page has been idle for and checks if the user is on a slow connection (using
navigator.connection.effectiveType) or has data-saver enabled (using
navigator.connection.saveData) to prevent loading.
To download react-live-chat-loader run:
npm install --save react-live-chat-loader
Or if you're using yarn, run:
yarn add react-live-chat-loader
To allow you to trigger a single live chat within your application, React Live Chat Loader has a
Context Providerwhich should be added at the root level of your application.
You pass your
providerKeyand
providerto the
LiveChatLoaderProvider.
For example, to add a
LiveChatLoaderProviderfor Help Scout you would do the following:
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
HelpScoutcomponent and add it to your application:
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
useChathook which has the current state of the chat and a function to load the chat.
import { useChat } from 'react-live-chat-loader'export const LoadChatButton = () => { const [state, loadChat] = useChat()
return Load Chat }
You can pass the following props to the
LiveChatLoaderProviderprovider:
provider: Choose from
helpScout,
intercom,
driftor
messenger(see below)
providerKey: Provider API Key (see below)
idlePeriod: How long to wait in ms before loading the provider. Default is
2000. Set to
0to never load. This value is used in a
setTimeoutin browsers that don't support
requestIdleCallback.
Currently there are four supported providers:
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.
import { LiveChatLoaderProvider, HelpScout } from 'react-live-chat-loader'
export default class App extends React.Component {
render() {
return (
<livechatloaderprovider providerkey="asdjkasl123123" provider="helpScout">
/* ... */
<helpscout></helpscout>
</livechatloaderprovider>
)
}
}
You can customise the Help Scout beacon by passing the following props to the
HelpScout
component:
color
: The background color of the beaconicon
: Choose from message
, antenna
, search
, question
, beacon
zIndex
: Changes the CSS index value of how the Beacon relates to other objectshorizontalPosition
: Choose from left
or right
Currently the Help Scout component only supports the icon button style.
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.
import { LiveChatLoaderProvider, Intercom } from 'react-live-chat-loader'
export default class App extends React.Component {
render() {
return (
<livechatloaderprovider providerkey="asd239" provider="intercom">
/* ... */
<intercom></intercom>
</livechatloaderprovider>
)
}
}
You can customise the color of the Intercom widget by passing a color
prop to
the Intercom
component.
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.
import { LiveChatLoaderProvider, Messenger } from 'react-live-chat-loader'
export default class App extends React.Component {
render() {
return (
<livechatloaderprovider provider="messenger" providerkey="111222333444555" appid="111222333444555" locale="en_US">
/* ... */
<messenger></messenger>
</livechatloaderprovider>
)
}
}
For a list of locale option values, refer to Facebook Localization documentation.
You can customise the Messenger widget by passing the following props to the
Messenger
component:
color
: The theme color of the widgetloggedInGreeting
: The greeting text that will be displayed if the user is currently logged in to Facebook.loggedOutGreeting
: The greeting text that will be displayed if the user 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.For a list of options, refer to Facebook Customer Chat Plugin documentation.
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.
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.
import { LiveChatLoaderProvider, Drift } from 'react-live-chat-loader'
export default () => (
<livechatloaderprovider providerkey="asdhjg127s1s" provider="drift">
/* ... */
<drift></drift>
</livechatloaderprovider>
)
You can customise the Drift Messenger by passing the following props to the
Drift
component:
color
: The background color of the messengericon
: 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.To contribute a new provider, follow these steps:
Create a new provider file at
src/providers/providerName.jsusing the following as a template:
const domain = 'https://provider.domain.com'
const loadScript = () => {
// Detect the provider is already loaded and return early
if (alreadyLoaded) return
// Call provider script here
}
const load = ({ providerKey }) => {
loadScript()
// Initialise provider script
}
const open = () => // Open provider
const close = () => // Close provider
export default {
domain,
load,
open,
close
}
The provider must export the following:
domain: A string of the domain where the provider script is loaded from that will be used in a
preconnectlink.
load: Function which when called will load and initialize the provider script. It should accept props and use the
providerKeyas the
app_idor
api_key. For consistency, it should call a
loadScriptfunction.
open: Function which when called will open the provider chat.
close: Function which when called will close the provider chat.
Import the new file in
src/providers/index.jsand add it to
Providers.
The name of this file will be the
providerKeyused in the
LiveChatLoaderProvider.
Create a new component in
src/Components/ProviderName/index.jswhich replicates the chat widget, using the following as a template:
import React from 'react'
import { useChat } from '../../'
import STATES from '../../utils/states'
const styles = {
// Add widget styles here
button: {
// Add button styles here
}
}
const Provider = ({ color }) => {
const [state, loadChat] = useChat({ loadWhenIdle: true })
if (state === STATES.COMPLETE) return null
return (
<div>
<button onclick="{()"> loadChat({ open: true })}
onMouseEnter={() => loadChat({ open: false })}
style={{
...styles.button,
backgroundColor: color
}}
>
Button
</button>
</div>
)
}
Provider.defaultProps = {
color: '#976ad4'
}
export default Provider
Do not worry about loading animations as the widget will be shown instantly on page load. Increase the
z-indexby
1so the fake widget sits immediately above the chat widget that is being replaced.
Export the component from
src/index.js
Add your new provider to this README under Supported Providers.
Add a new page to
website/pages/which showcases the provider. If you don't want to include your
providerKeyleave this blank and the maintainers will set one up.
The new provider page can be tested locally by creating a distribution version of the package and referencing this from the
wesbite.
Unfortunately if you try to include the package locally from source you'll most likely run into a Duplicate React error.
To create the distribution version and reference it, do the following:
yarn buildto build the package into
dist
website/package.jsonto reference the
distbuild:
"react-live-chat-loader": "../dist"
websitedirectory run
npm install
websitedirectory run the server with
npm run dev
website/pages/which includes the new component
website/pages/index.js
website/components/exampleLinks.js
Thanks goes to these wonderful people (emoji key):
Kevin Peng 💻 |
Ash Kyd 📖 |
Jeff Reiner 📖 💻 |
This project follows the all-contributors specification. Contributions of any kind welcome!