Quickstart
This document explains the initial setting for the JavaScript SDK("SDK" below).
The SDK helps install a channel button on the web service.
General case
If the web service consists of multiple pages which load new static resources for each page request, see the following guide.
Web services that work in this way are commonly referred to as the MPA.
See MPA(Multi-Page Application) for more details.
Step 1: Installation
Insert the following script in the HTML file's <body>
tag.
<script>
(function(){var w=window;if(w.ChannelIO){return w.console.error("ChannelIO script included twice.");}var ch=function(){ch.c(arguments);};ch.q=[];ch.c=function(args){ch.q.push(args);};w.ChannelIO=ch;function l(){if(w.ChannelIOInitialized){return;}w.ChannelIOInitialized=true;var s=document.createElement("script");s.type="text/javascript";s.async=true;s.src="https://cdn.channel.io/plugin/ch-plugin-web.js";var x=document.getElementsByTagName("script")[0];if(x.parentNode){x.parentNode.insertBefore(s,x);}}if(document.readyState==="complete"){l();}else{w.addEventListener("DOMContentLoaded",l);w.addEventListener("load",l);}})();
</script>
Step 2: Boot
To use the SDK, you should boot.
See the following code to boot for the unknown user.
ChannelIO('boot', {
"pluginKey": "YOUR_PLUGIN_KEY" // fill your plugin key
});
See the following code to boot for the member user.
To integrate the users between the web service and the ChannelTalk, you should set information in boot option.
See the memberId and profile for more details.
Use member hash to protect sensitive information of your users
If you set the
memberId
using predictable values such as user ID or email, an unauthorized third party might acquire your userโsmemberId
. The unauthorized access might allow the malicious third party to gain your userโs sensitive information, including mobile number and chat logs which can lead to a security breach. Enable member hash for your channel to improve the security level.
The information of the same person can be unified
When booting as a member user from an anonymous user state, users can be unified into one if Channel finds a strong evidence that the two users are the same person. See unifying customer information for details.
ChannelIO('boot', {
"pluginKey": "YOUR_PLUGIN_KEY", // fill your plugin key
"memberId": "USER_MEMBER_ID", // fill user's member id
"profile": { // fill user's profile
"name": "USER_NAME", // fill user's name
"mobileNumber": "USER_MOBILE_NUMBER", // fill user's mobile number
"landlineNumber": "USER_LANDLINE_NUMBER", // fill user's landline number
"CUSTOM_VALUE_1": "VALUE_1", // custom property
"CUSTOM_VALUE_2": "VALUE_2" // custom property
}
});
See boot and boot option for more details about the boot.
See ChannelIO for various methods provided by the SDK.
Single Page Application
If the web service is Single Page Application(SPA) or you want to use the SDK through the JavaScript Class, see the following codes.
Use the SDK on client-side only.
You canโt execute the SDK beforehand on the server-side.
Step 1: Add a Service
Service for JavaScript
class ChannelService {
constructor() {
this.loadScript();
}
loadScript() {
(function(){var w=window;if(w.ChannelIO){return w.console.error("ChannelIO script included twice.");}var ch=function(){ch.c(arguments);};ch.q=[];ch.c=function(args){ch.q.push(args);};w.ChannelIO=ch;function l(){if(w.ChannelIOInitialized){return;}w.ChannelIOInitialized=true;var s=document.createElement("script");s.type="text/javascript";s.async=true;s.src="https://cdn.channel.io/plugin/ch-plugin-web.js";var x=document.getElementsByTagName("script")[0];if(x.parentNode){x.parentNode.insertBefore(s,x);}}if(document.readyState==="complete"){l();}else{w.addEventListener("DOMContentLoaded",l);w.addEventListener("load",l);}})();
}
boot(option, callback) {
window.ChannelIO('boot', option, callback);
}
shutdown() {
window.ChannelIO('shutdown');
}
showMessenger() {
window.ChannelIO('showMessenger');
}
hideMessenger() {
window.ChannelIO('hideMessenger');
}
openChat(chatId, message) {
window.ChannelIO('openChat', chatId, message);
}
track(eventName, eventProperty) {
window.ChannelIO('track', eventName, eventProperty);
}
onShowMessenger(callback) {
window.ChannelIO('onShowMessenger', callback);
}
onHideMessenger(callback) {
window.ChannelIO('onHideMessenger', callback);
}
onBadgeChanged(callback) {
window.ChannelIO('onBadgeChanged', callback);
}
onChatCreated(callback) {
window.ChannelIO('onChatCreated', callback);
}
onFollowUpChanged(callback) {
window.ChannelIO('onFollowUpChanged', callback);
}
onUrlClicked(callback) {
window.ChannelIO('onUrlClicked', callback);
}
clearCallbacks() {
window.ChannelIO('clearCallbacks');
}
updateUser(userInfo, callback) {
window.ChannelIO('updateUser', userInfo, callback);
}
addTags(tags, callback) {
window.ChannelIO('addTags', tags, callback);
}
removeTags(tags, callback) {
window.ChannelIO('removeTags', tags, callback);
}
setPage(page) {
window.ChannelIO('setPage', page);
}
resetPage() {
window.ChannelIO('resetPage');
}
showChannelButton() {
window.ChannelIO('showChannelButton');
}
hideChannelButton() {
window.ChannelIO('hideChannelButton');
}
setAppearance(appearance) {
window.ChannelIO('setAppearance', appearance);
}
}
export default new ChannelService();
Service for TypeScript
declare global {
interface Window {
ChannelIO?: IChannelIO;
ChannelIOInitialized?: boolean;
}
}
interface IChannelIO {
c?: (...args: any) => void;
q?: [methodName: string, ...args: any[]][];
(...args: any): void;
}
interface BootOption {
appearance?: string;
customLauncherSelector?: string;
hideChannelButtonOnBoot?: boolean;
hidePopup?: boolean;
language?: string;
memberHash?: string;
memberId?: string;
mobileMessengerMode?: string;
pluginKey: string;
profile?: Profile;
trackDefaultEvent?: boolean;
trackUtmSource?: boolean;
unsubscribe?: boolean;
unsubscribeEmail?: boolean;
unsubscribeTexting?: boolean;
zIndex?: number;
}
interface Callback {
(error: Error | null, user: CallbackUser | null): void;
}
interface CallbackUser {
alert: number
avatarUrl: string;
id: string;
language: string;
memberId: string;
name?: string;
profile?: Profile | null;
tags?: string[] | null;
unsubscribeEmail: boolean;
unsubscribeTexting: boolean;
}
interface UpdateUserInfo {
language?: string;
profile?: Profile | null;
profileOnce?: Profile;
tags?: string[] | null;
unsubscribeEmail?: boolean;
unsubscribeTexting?: boolean;
}
interface Profile {
[key: string]: string | number | boolean | null;
}
interface FollowUpProfile {
name?: string | null;
mobileNumber?: string | null;
email?: string | null;
}
interface EventProperty {
[key: string]: string | number | boolean | null;
}
type Appearance = 'light' | 'dark' | 'system' | null;
class ChannelService {
constructor() {
this.loadScript();
}
loadScript() {
(function(){var w=window;if(w.ChannelIO){return w.console.error("ChannelIO script included twice.");}var ch=function(){ch.c(arguments);};ch.q=[];ch.c=function(args){ch.q.push(args);};w.ChannelIO=ch;function l(){if(w.ChannelIOInitialized){return;}w.ChannelIOInitialized=true;var s=document.createElement("script");s.type="text/javascript";s.async=true;s.src="https://cdn.channel.io/plugin/ch-plugin-web.js";var x=document.getElementsByTagName("script")[0];if(x.parentNode){x.parentNode.insertBefore(s,x);}}if(document.readyState==="complete"){l();}else{w.addEventListener("DOMContentLoaded",l);w.addEventListener("load",l);}})();
}
boot(option: BootOption, callback?: Callback) {
window.ChannelIO?.('boot', option, callback);
}
shutdown() {
window.ChannelIO?.('shutdown');
}
showMessenger() {
window.ChannelIO?.('showMessenger');
}
hideMessenger() {
window.ChannelIO?.('hideMessenger');
}
openChat(chatId?: string | number, message?: string) {
window.ChannelIO?.('openChat', chatId, message);
}
track(eventName: string, eventProperty?: EventProperty) {
window.ChannelIO?.('track', eventName, eventProperty);
}
onShowMessenger(callback: () => void) {
window.ChannelIO?.('onShowMessenger', callback);
}
onHideMessenger(callback: () => void) {
window.ChannelIO?.('onHideMessenger', callback);
}
onBadgeChanged(callback: (alert: number) => void) {
window.ChannelIO?.('onBadgeChanged', callback);
}
onChatCreated(callback: () => void) {
window.ChannelIO?.('onChatCreated', callback);
}
onFollowUpChanged(callback: (profile: FollowUpProfile) => void) {
window.ChannelIO?.('onFollowUpChanged', callback);
}
onUrlClicked(callback: (url: string) => void) {
window.ChannelIO?.('onUrlClicked', callback);
}
clearCallbacks() {
window.ChannelIO?.('clearCallbacks');
}
updateUser(userInfo: UpdateUserInfo, callback?: Callback) {
window.ChannelIO?.('updateUser', userInfo, callback);
}
addTags(tags: string[], callback?: Callback) {
window.ChannelIO?.('addTags', tags, callback);
}
removeTags(tags: string[], callback?: Callback) {
window.ChannelIO?.('removeTags', tags, callback);
}
setPage(page: string) {
window.ChannelIO?.('setPage', page);
}
resetPage() {
window.ChannelIO?.('resetPage');
}
showChannelButton() {
window.ChannelIO?.('showChannelButton');
}
hideChannelButton() {
window.ChannelIO?.('hideChannelButton');
}
setAppearance(appearance: Appearance) {
window.ChannelIO?.('setAppearance', appearance);
}
}
export default new ChannelService();
Step2: Installation
You can install the SDK through the Service.
ChannelService.loadScript();
Step 3: Boot
To use the SDK, you should boot.
See the following code to boot for the unknown user.
ChannelService.boot({
"pluginKey": "YOUR_PLUGIN_KEY", // fill your plugin key
});
See the following code to boot for the member user.
To integrate the users between the web service and the ChannelTalk, you should set information in boot option.
See the memberId and profile for more details.
Use member hash to protect sensitive information of your users
If you set the
memberId
using predictable values such as user ID or email, an unauthorized third party might acquire your userโsmemberId
. The unauthorized access might allow the malicious third party to gain your userโs sensitive information, including mobile number and chat logs which can lead to a security breach. Enable member hash for your channel to improve the security level.
The information of the same person can be unified
When booting as a member user from an anonymous user state, users can be unified into one if Channel finds a strong evidence that the two users are the same person. See unifying customer information for details.
ChannelService.boot({
"pluginKey": "YOUR_PLUGIN_KEY", // fill your plugin key
"memberId": "USER_MEMBER_ID", // fill user's member id
"profile": { // fill user's profile
"name": "USER_NAME", // fill user's name
"mobileNumber": "USER_MOBILE_NUMBER", // fill user's mobile number
"landlineNumber": "USER_LANDLINE_NUMBER", // fill user's landline number
"CUSTOM_VALUE_1": "VALUE_1", // custom property
"CUSTOM_VALUE_2": "VALUE_2" // custom property
});
See boot and boot option for more details about boot.
See ChannelIO for various methods provided by the SDK.
Updated 28 days ago