README
react-channel-plugin
Channel IO (Channel Talk) plugin wrapper for React.
Installation
Installation via NPM
$ yarn add react-channel-plugin
Getting started
Example code of react channel plugin.
import React from 'react';
import {
ReactChannelIO,
useChannelIOApi,
useChannelIOEvent,
} from 'react-channel-plugin';
import { CHANNEL_ID_PLUGIN_KEY } from './config';
const App = () => {
return (
<ReactChannelIO pluginKey={CHANNEL_ID_PLUGIN_KEY} locale="en" autoBoot>
<AppPage />
</ReactChannelIO>
);
};
const AppPage = () => {
const { showMessenger } = useChannelIOApi();
useChannelIOEvent('onShowMessenger', () => {
console.log('Messenger opened!');
});
return (
<button onClick={showMessenger}>
<span>Open</span>
</button>
);
};
API
React provider and hooks for Channel IO API.
ReactChannelIO
<ReactChannelIO /> is React Context provider, which will provides context (APIs and event listeners) to react-channel-plugin hooks. Also it receives Channel IO plugin options and initialize Channel IO instance. Make sure place <ReactChannelIO /> upper than hooks used at your app.
Props
/**
* Please refer ChannelIO offical docs.
* - ref: https://developers.channel.io/docs/web-boot-option
*/
type ChannelIOBootOption = {};
interface ReactChannelIOProps extends ChannelIOBootOption {
/**
* Indicates whether ChannelIO should be automatically booted or not.
* If `true` no need to call `boot` manually.
*
* - Default: `false`
*/
autoBoot?: boolean;
/**
* Timeout before call `boot`.
* Only work when `autoBoot` set as `true`.
*
* - Default: `1000`
*/
autoBootTimeout?: number;
/**
* Need to reboot channel plugin when boot option changed?
*
* - Default: `true`
*/
rebootOnOptionChanged?: boolean;
/**
* Since ChannelIO does not support `customLauncherSelector` after plugin booted,
* add onClick event listener at element which has `customLauncherSelector`
* whenever DOM tree mutated. (observed by `MutationObserver`)
*
* - Default: `true`
*/
useCustomLauncherSelectorTweak?: boolean;
/**
* Print debug logs via `console.debug`.
* Set `false` when use plugin at production env.
*/
verbose?: boolean;
/**
* Emitted when channel plugin booted.
*/
onBoot?: (err?: any, user?: ChannelIOUser) => void;
}
Example
import React from 'react';
import { ReactChannelIO } from 'react-channel-plugin';
import { CHANNEL_ID_PLUGIN_KEY } from './config';
const App = () => {
const userProfile = { ... };
return (
<ReactChannelIO
pluginKey={CHANNEL_ID_PLUGIN_KEY}
hideChannelButtonOnBoot={true}
locale="en"
profile={userProfile}
autoBoot
autoBootTimeout={2000}
>
<span>Child component of the ReactChannelIO</span>
</ReactChannelIO>
);
};
useChannelIOApi
Provides API of Channel IO as React hook. Please refer official docs to see detail description of each API.
bootshutdownshowMessengershowhideMessengerhideloungeopenChattrackclearCallbacksupdateUseraddTagsremoveTagssetPageresetPageshowChannelButtonhideChannelButton
Example
import { useChannelIOApi } from 'react-channel-plugin';
const AppPage = () => {
const { showMessenger, updateUser } = useChannelIOApi();
return (
<>
<button onClick={showMessenger}>
<span>Open</span>
</button>
<button
onClick={() => {
updateUser({
profile: {
name: 'John Doe',
email: 'john.doe@example.com',
mobileNumber: '+821012345678',
},
});
}}
>
<span>Update user</span>
</button>
</>
);
};
useChannelIOEvent
Provides event callbacks from Channel IO as React hook. Provide callback method name as first parameter of hook method. Please refer official docs to see detail description of each callback.
onBootonShowMessengeronShowonHideMessengeronHideonBadgeChangedonChangeBadgeonChatCreatedonCreateChatonProfileChangedonChangeProfileonUrlClickedonClickRedirect
Example
import { useChannelIOApi } from 'react-channel-plugin';
const AppPage = () => {
useChannelIOEvent('onShowMessenger', () => {
console.log('Messenger opened!');
});
useChannelIOEvent('onChangeProfile', user => {
console.log('User updated:', user);
});
return null;
};
Pure APIs
You can use Channel IO API wrapper without using React. Usages are same with official API, but typed via TypeScript.
WARNING: DO NOT USE with <ReactChannelIO />, because there is change to overrides attached callbacks of react-channel-plugin and which will cause malfunctioning.
import { ChannelIO } from 'react-channel-plugin';
ChannelIO('boot');
ChannelIO('onChatCreated', () => {
console.log('User chat created!');
});
Playground
Playground for react-channel-plugin.
https://ukjinjang.github.io/react-channel-plugin
TypeScript
Please use typescript version higher than 3.8.
Thanks to awesome util downlevel-dts, we can convert d.ts file to use at older version of TypeScript even code using newer feature (like Labeled Tuple Elements).
Unit Test
To run unit test components that use react-channel plugin's hook with react-testing-library, pass ReactChannelIO provider to wrapper option of render method.
import '@testing-library/jest-dom/extend-expect';
import { render } from '@testing-library/react';
// ...
render(<ComponentWithChannelHook {...props} />, {
wrapper: ({ children }) => {
return (
<ReactChannelIO
children={children}
pluginKey={CHANNEL_ID_PLUGIN_KEY}
{...pluginProps}
/>
);
},
});
Brower compatibility
| Browser (last 2 versions) | |
|---|---|
| Google Chrome | ✅ |
| MS Edge (Chromium) | ✅ |
| Mozilla Firefox | ✅ |
| Electron | ✅ |
| IE 11 | ⚠️ † |
† Since Cypress not supports IE 11, tested by hand (and may not fully tested).
Issues
react-channel-plugin is a light-weight wrapper of Channel IO JavaScript SDK. Because of this, the issue you're having likely isn't a react-channel-plugin issue, but an issue with Channel IO service itself. So please check it again, before submit new issue.