react-live-chat-loader

React Live Chat Loader

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, Help Scout, Drift, Messenger and Userlike.

Made by the team at ♠ Calibre, your performance companion.

Table of Contents

1. How it works
2. Installation
3. Usage
4. Supported Providers
5. Adding a provider
6. Examples

---

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:

• User hovers over the fake button
• User 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 user 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 users interaction from their last session.

Installation

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

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:

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

export default class App extends React.Component {
  /* ... */

  render() {
    return (
      <LiveChatLoaderProvider providerKey="asdjkasl123123" provider="helpScout">
        /* ... */
      </LiveChatLoaderProvider>
    )
  }
}

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:

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

export default class Index extends React.Component {
  /* ... */

  render() {
    return (
      <>
        /* ... */
        <HelpScout />
      </>
    )
  }
}

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.

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

export const LoadChatButton = () => {
  const [state, loadChat] = useChat()

  return <button onClick={() => loadChat({ open: true })}>Load Chat</button>
}

Options

You can pass the following props to the LiveChatLoaderProvider provider:

• provider: Choose from helpScout, intercom, drift or 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 0 to never load. This value is used in a setTimeout in browsers that don't support requestIdleCallback.

Supported Providers

Currently there are six 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.

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

export default class App extends React.Component {
  render() {
    return (
      <LiveChatLoaderProvider providerKey="asdjkasl123123" provider="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 beacon
• icon: Choose from message, antenna, search, question, beacon
• zIndex: Changes the CSS index value of how the Beacon relates to other objects
• horizontalPosition: Choose from left or right

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.

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

export default class App extends React.Component {
  render() {
    return (
      <LiveChatLoaderProvider providerKey="asd239" provider="intercom">
        /* ... */
        <Intercom />
      </LiveChatLoaderProvider>
    )
  }
}

You can customise the color of the Intercom widget by passing a color prop to the Intercom component.

User or Company context data can be set using window.intercomSettings. See the offical Intercom documentation 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.

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 />
      </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 widget
• loggedInGreeting: 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.

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.

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

export default () => (
  <LiveChatLoaderProvider providerKey="asdhjg127s1s" provider="drift">
    /* ... */
    <Drift />
  </LiveChatLoaderProvider>
)

You can customise the Drift Messenger by passing the following props to the Drift component:

• color: The background color of the messenger
• 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.

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.

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

export default () => (
  <LiveChatLoaderProvider
    providerKey="x014e93c288445c0bf6f8a378a0b1af8e6e1125t71634124a88fe63e38hme701"
    provider="userlike"
  >
    /* ... */
    <Userlike />
  </LiveChatLoaderProvider>
)

You can customise the Userlike Widget 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.

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.

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

export default () => (
  <LiveChatLoaderProvider
    providerKey="E33wn9ftxMDHZx18AaBkfPvY"
    provider="chatwoot"
  >
    /* ... */
    <Chatwoot />
  </LiveChatLoaderProvider>
)

You can customise the Chatwoot Widget by passing the following props to the Chatwoot component:

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

Adding a provider

To contribute a new provider, follow these steps:

1. Create provider file

Create a new provider file at src/providers/providerName.js using the following as a template:

Provider 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 preconnect link.
• load: Function which when called will load and initialize the provider script. It should accept props and use the providerKey as the app_id or api_key. For consistency, it should call a loadScript function.
• 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.js and add it to Providers.

The name of this file will be the providerKey used in the LiveChatLoaderProvider.

2. Create component

Create a new component in src/Components/ProviderName/index.js which replicates the chat widget, using the following as a template:

Component 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-index by 1 so the fake widget sits immediately above the chat widget that is being replaced.

Export the component from src/index.js

3. Update README

Add your new provider to this README under Supported Providers.

4. Add an example page

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.

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:

• In the root of the project, run npm run build to build the package into dist
• Update website/package.json to reference the dist build: "react-live-chat-loader": "../"
• In the website directory run npm install
• In the website directory run the server with npm run dev
• Add a new page to website/pages/ which includes the new component
• Add a link to the provider in website/pages/index.js
• Add a link to the provider in website/components/exampleLinks.js

Examples

• react-live-chat-loader-example-app: example Next.js application

Resources

• How to avoid performance regressions when using live chat tools
• Reducing the Intercom Messenger bundle size by 65%

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Kevin Peng 💻

Ash Kyd 📖

Jeff Reiner 📖 💻

Joan Mira 💻

Nathan Collman 💻

Jaakko Mustalahti 💻

Moti Korets 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

Changelog

2.5.0 (2021-06-08)

🆕 New provider

• Adds Chatwoot component (thanks to @motiko)

🛠 Core

• Updates how we detect if a provider has loaded.