Englishํ•œ๊ตญ์–ด

Quickstart

Suggest Edits

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โ€™s memberId. 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โ€™s memberId. 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