Головна → 💾 JavaScript API → Методи JS API

Методи JS API

showChatWidget, updateUser, setLocalization та багато іншого
Написано Марина
Оновлено 1 місяць тому

Віджет HelpCrunch надає вам JavaScript API. За допомогою нього ви можете контролювати та налаштовувати свій чат і поведінку віджета.

  1. showChatWidget
  2. hideChatWidget
  3. openChat
  4. closeChat
  5. init
  6. updateUser
  7. userAuth
  8. updateUserData
  9. trackEvent
  10. setLocalization
  11. sendProactiveChatAutoMessage
  12. sendUserMessage
  13. typeUserMessage
  14. logOut
  15. muteNotificationSound
  16. setChatButtonOffset
  17. setOperatingHours
  18. openKBArticle
  19. onError
  20. setMediaCSS

showChatWidget

Показує віджет чату (кнопку запуску чату) після ініціалізації або після того, як його було приховано за допомогою hideChatWidget.

Без параметрів і повернень.

HelpCrunch('showChatWidget');

hideChatWidget

Приховує віджет чату (кнопку запуску чату) після того, як його показав showChatWidget.

Без параметрів і повернень.

HelpCrunch('hideChatWidget');

openChat

Відкриває чат HelpCrunch. Можна викликати без відображення віджета.

Без параметрів і повернень.

HelpCrunch('openChat');

closeChat

Закриває чат HelpCrunch після того, як його відкрив openChat.

Без параметрів і повернень.

HelpCrunch('closeChat');

init 

Ініціалізує віджет HelpCrunch на сторінці вашого сайту. Усі методи веб-SDK, викликані до цього методу, запустяться після завершення ініціалізації.

Ви можете скористатися цим методом із усіма необхідними параметрами прямо зі свого облікового запису HelpCrunch на сторінці Налаштування → Канали → Веб-віджети → [Оберіть ваш віджет] → Налаштування.

Параметри:

  • organization domain: рядок. Домен вашої організації, який ви ввели під час реєстрації. Ви можете перевірити його у URL-адресі свого облікового запису HelpCrunch (наприклад DOMAIN.helpcrunch.com)
  • options: об'єкт
    • appId: рядок
    • user (за бажанням): об’єкт. Якщо користувач автентифікований на вашому сайті, ви можете надіслати дані користувача прямо під час ініціалізації, щоб автоматично автентифікувати користувача в чаті HelpCrunch і пізніше робити менше запитів до сервера. Дізнайтеся більше про це в розділі про режим автентифікації користувача.
    • signature (за бажанням): рядок. Потрібен лише в режимі автентифікації користувача, коли ви хочете захистити свої дані користувача за допомогою підпису безпеки на бекенді. Докладніше про це — в розділі підпис захисту.

Ініціалізація за замовчуванням:

HelpCrunch('init', '<your organization domain / string>', {
  appId:  '<application id / string>',
});

Ініціалізація з усіма даними користувача/ліда:

HelpCrunch('init', '<your organization domain / string>', {
  appId:  '<application id / string>',
  user: {
    email: '<user email / email>',
    name: '<user name / string>',
    phone: '<phone number / string>',
    company: '<company name / string>',
    user_id: '<user id /string>',
    security_hash: '<security hash / string>',
    custom_data: {
      money_spent: 2500,
      subscription: 'gold',
      accepted_agreement: true,
    },
  },
  signature: '<signature / string>',
});

updateUser

Використовуйте його, щоб додати або оновити поточні параметри клієнта, як-от ім’я, електронна адреса, телефон, компанія та customData (об’єкт із будь-якими довільними даними, які ви хочете записати). Якщо для поточного відвідувача не існує ініціалізованого користувача, цей метод створить нового користувача, і ви зможете побачити його на сторінці "Контакти" у своєму обліковому записі HelpCrunch. Цей метод корисний, коли користувач вносить будь-які зміни у свої основні атрибути, і ви хочете миттєво побачити це у своєму обліковому записі HelpCrunch.

Параметри:

  • user: об’єкт. Перегляд детального профілю користувача в розділі користувача у веб-SDK
  • signature (за бажанням): рядок. Потрібен лише в режимі автентифікації користувача, коли ви хочете захистити дані користувача за допомогою підпису безпеки на бекенді. Докладніше про це — в розділі "Підпис захисту".
  • callback (за бажанням): функція
var user = {
  email: '<user email / email>',
  name: '<user name / string>',
  company: '<company name / string>',
  user_id: '<user id / string>',
  phone: '<phone number / string>',
  security_hash: '<security_hash /string>',
  custom_data: {
    money_spent: 2500,
    subscription: 'gold',
    accepted_agreement: true,
  },
};
HelpCrunch('updateUser', user, 'e8aa8af95cd6a05b80308dcb3dd6901d', function() {});

Приклад:

Користувач змінює (або додає) свою електронну адресу у вашому односторінковому застосунку. Щоб побачити цю зміну в панелі адміністратора HelpCrunch, ви можете просто викликати:

var userEmail = '[email protected]';
HelpCrunch('updateUser', { email: userEmail });

userAuth

За допомогою методу userAuth можна авторизувати клієнта. Для цього методу потрібні два параметри – email і user_id. Однак ви можете додати й інші параметри, наприклад name, company, phone.

Зверніть увагу, що атрибут user_id має бути унікальним для кожного користувача! Переконайтеся, що ви передаєте його як рядок.

Зазвичай цей метод корисний, якщо ви хочете відкласти авторизацію до моменту активації деяких тригерів або якщо на вашому сайті є одна сторінка з динамічно оновлюваним вмістом (односторінковий застосунок).

  • user: об'єкт
  • signature (за бажанням): рядок. Потрібен лише в режимі автентифікації користувача, коли ви хочете захистити дані користувача за допомогою підпису безпеки на бекенді.
  • callback (за бажанням): функція
HelpCrunch('userAuth', {
  email: '<user email / email>',
  user_id: '<user id / string>'
});

updateUserData

Оновлює власні дані поточного користувача. Власні дані — це об’єкт із будь-якими випадковими даними, які ви хочете записати, а потім використовувати у HelpCrunch. Цей метод корисний, коли користувач вносить будь-які зміни у власні атрибути, і ви хочете миттєво побачити це у своєму обліковому записі HelpCrunch. Параметри:

  • userData: об'єкт
  • signature (за бажанням): рядок. Потрібен лише в режимі автентифікації користувача, коли ви хочете захистити дані користувача за допомогою підпису безпеки на бекенді.
  • callback (за бажанням): функція
var userData = {
  money_spent: 2500,
  subscription: 'gold',
  accepted_agreement: true,
};
HelpCrunch('updateUserData', userData,'e8aa8af95cd6a05b80308dcb3dd6901d', function() {});

Приклад:

Ви хочете підрахувати, скільки разів ваш користувач натиснув якусь важливу кнопку. Для цього ви зберігаєте лічильник у localStorage та викликаєте onClick.

document.getElementById('important-button').onclick = function () {
  var counter = window.localStorage.getItem('counter');
  counter++;
  window.localStorage.setItem('counter', counter);
  HelpCrunch('updateUserData', { importantButtonClicks: counter });
}

trackEvent

Ви можете відстежувати будь-які власні події, які виконує робить на вашому сайті, і переглядати його історію подій в обліковому записі HelpCrunch. Докладніше про це — в розділі відстеження власних подій.

Параметри:

  • eventName: рядок
HelpCrunch('trackEvent', eventName);

Приклад:

Ви хочете знати, що користувач натиснув кнопку "Оформити замовлення". Код буде виглядати так:

document.getElementById('checkout-button').onclick = function() {
  HelpCrunch('trackEvent', 'checkoutButtonClick');
}

setLocalization

Викличте setLocalization, якщо хочете запустити спеціальну локалізацію або власні тексти чату. За замовчуванням вам доступно 6 мов, і чат вибере локалізацію відповідно до мови браузера користувача. Якщо цю мову не знайдено, у чаті відображатиметься мова за умовчанням. Докладніше про це — в розділі про локалізацію віджета.

Параметри:

  • phraseListName: рядок
HelpCrunch('setLocalization', phraseListName);

Приклад:

Ви створили список фраз клінгонської мови у своєму обліковому записі адміністратора та назвали його "klingonian". Щоб увімкнути його в чаті HelpCrunch на вашій сторінці, запустіть наступний код перед показом віджета чату:

HelpCrunch('setLocalization', 'klingonian');

sendProactiveChatAutoMessage

HelpCrunch пропонує систему автоматичних проактивних повідомлень у чаті, щоб автоматично звертатися до відвідувачів і лідів. Ви можете налаштувати правила автоматичного надсилання повідомлень у своєму обліковому записі HelpCrunch або просто викликати його з веб-SDK JS API. Докладніше про це — в розділі про надсилання проактивних автоматичних повідомлень чату за допомогою JavaScript API.

Параметри:

  • autoMessageId: номер
HelpCrunch('sendProactiveChatAutoMessage', autoMessageId);

Приклад:

Ви хочете запропонувати клієнту знижку, якщо він відсортує ваші товари за ціною в порядку зростання або просто натисне кнопку "Отримати знижку" (або будь-яку іншу). Для цього вам потрібно створити проактивне автоматичне повідомлення чату у своєму обліковому записі HelpCrunch, увімкнути його та скопіювати його ID на сторінці редагування. Якщо припустити, що ID — 1420, код може бути наступним:

var proposeDiscount = function () {
  HelpCrunch('sendProactiveChatAutoMessage', 1420);
}
document.getElementById('i-want-discount-button').onclick = proposeDiscount;
document.getElementsByClassName('sort-goods').onclick = function (event) {
  if (event.target.attributes.order == 'asc' && event.target.attributes.field == 'price') {
    proposeDiscount();
  }
}

sendUserMessage

Іноді вам потрібно надіслати оператору служби підтримки повідомлення від імені користувача про певну дію користувача. Цей метод підходить для цього.

Параметри:

  • messageText: рядок
HelpCrunch('sendUserMessage', messageText);

Приклад:

Ви хочете, щоб ваш оператор служби підтримки отримував повідомлення з текстом «CALLBACK: +12312312313», коли користувач вводить свій номер телефону в якусь форму та натискає кнопку "Перетелефонуйте мені" на вашому сайті. Цей код виглядатиме так:

document.getElementById('callback-button').onclick = function () {
  var phoneNumber = document.getElementById('callback-input').value;
  if (phoneNumber) {
    HelpCrunch('sendUserMessage', 'CALLBACK: ' + phoneNumber);
  }
}

typeUserMessage

Цей метод дозволяє додати попередньо заповнене повідомлення до області вводу тексту, не надсилаючи його.

Параметри:

  • messageText: рядок
HelpCrunch('typeUserMessage', messageText);

logout

На деяких сайтах користувач може мати кілька облікових записів і може входити/виходити, щоб переключатися між ними. Якщо ви використовуєте режим автентифікації користувача, ви можете зробити те саме для свого віджета HelpCrunch, щоб дані з одного облікового запису користувача не передавалися іншому. Для цього можна використати метод logout з системи:

Параметри:

  • callback (за бажанням): функція
HelpCrunch('logout', function(data) {
  if (data && data.success) {
    // do something
  }
});

muteNotificationSound

На деяких веб-сторінках ви можете не хотіти переривати користувачів звуками сповіщень чату. Наприклад, це можуть бути конференц-зали, класні кімнати тощо. Додавання цього булевого методу блокуватиме звуки чату на таких сторінках.

Параметри:

  • value: булеві
HelpCrunch('muteNotificationSound', true);

setChatButtonOffset

Положення кнопки чату на сторінці можна змінювати динамічно або статично за допомогою цього методу API.

Параметри:

  • horizontal: номер
  • bottom: номер
HelpCrunch('setChatButtonOffset', horizontal, bottom);

setOperatingHours

Загальне налаштування "Робочі години" для всіх віджетів чату доступне в Налаштуваннях. Щоб перевизначити це налаштування для конкретного віджету чату, можна використовувати метод 'setOperatingHours' після коду віджету.

HelpCrunch('setOperatingHours', {
  timezone: 'Europe/London',
  hours: {
    monday: {
      is_enabled: true,
      from: "03:00",
      to: "13:00",
    },
    tuesday: {
      is_enabled: true,
      from: "03:00",
      to: "13:00",
    },
    wednesday: {
      is_enabled: true,
      from: "03:00",
      to: "13:00",
    },
    thursday: {
      is_enabled: true,
      from: "03:00",
      to: "13:00",
    },
    friday: {
      is_enabled: true,
      from: "03:00",
      to: "13:00",
    },
    saturday: {
      is_enabled: false,
      from: "03:00",
      to: "13:00",
    },
    sunday: {
      is_enabled: false,
      from: "03:00",
      to: "13:00",
    },
  }
});

Список часових поясів, які можна використовувати з цим методом:

  'Pacific/Midway', 'Pacific/Honolulu', 'Pacific/Tahiti', 'Pacific/Gambier', 'America/Adak', 'America/Anchorage',
  'America/Metlakatla', 'America/Los_Angeles', 'America/Tijuana', 'America/Chihuahua', 'America/Mazatlan',
  'America/Managua', 'Canada/Saskatchewan', 'America/Mexico_City', 'America/Monterrey', 'America/Lima', 'America/Bogota',
  'America/Caracas', 'America/La_Paz', 'America/Campo_Grande', 'America/New_York', 'Canada/Atlantic', 'America/Santiago',
  'America/Sao_Paulo', 'America/Argentina/Buenos_Aires', 'Canada/Newfoundland', 'America/Godthab', 'America/Noronha',
  'Atlantic/South_Georgia', 'Atlantic/Cape_Verde', 'Atlantic/Azores', 'Africa/Monrovia', 'Africa/Casablanca',
  'Europe/Lisbon', 'Europe/London', 'Africa/Lagos', 'Europe/Amsterdam', 'Europe/Belgrade', 'Europe/Berlin',
  'Europe/Bratislava', 'Europe/Brussels', 'Europe/Budapest', 'Europe/Copenhagen', 'Europe/Ljubljana', 'Europe/Madrid',
  'Europe/Paris', 'Europe/Prague', 'Europe/Rome', 'Europe/Sarajevo', 'Europe/Skopje', 'Europe/Stockholm', 'Europe/Vienna',
  'Europe/Warsaw', 'Europe/Zagreb', 'Africa/Cairo', 'Africa/Harare', 'Africa/Johannesburg', 'Europe/Athens',
  'Europe/Bucharest', 'Europe/Istanbul', 'Asia/Jerusalem', 'Europe/Helsinki', 'Europe/Kyiv', 'Europe/Riga', 'Europe/Sofia',
  'Europe/Tallinn', 'Europe/Vilnius', 'Asia/Baghdad', 'Asia/Kuwait', 'Europe/Minsk', 'Africa/Nairobi', 'Asia/Riyadh',
  'Europe/Volgograd', 'Europe/Moscow', 'Asia/Muscat', 'Asia/Baku', 'Asia/Tbilisi', 'Asia/Yerevan', 'Asia/Dubai',
  'Europe/Samara', 'Indian/Reunion', 'Asia/Karachi', 'Asia/Tashkent', 'Asia/Yekaterinburg', 'Indian/Maldives',
  'Asia/Kolkata', 'Asia/Almaty', 'Asia/Dhaka', 'Asia/Urumqi', 'Asia/Bangkok', 'Asia/Jakarta', 'Asia/Novosibirsk',
  'Asia/Krasnoyarsk', 'Asia/Hong_Kong', 'Asia/Kuala_Lumpur', 'Australia/Perth', 'Asia/Singapore', 'Asia/Taipei',
  'Asia/Irkutsk', 'Asia/Tokyo', 'Asia/Seoul', 'Asia/Yakutsk', 'Australia/Adelaide', 'Australia/Darwin',
  'Australia/Brisbane', 'Pacific/Guam', 'Australia/Hobart', 'Australia/Melbourne', 'Pacific/Port_Moresby',
  'Australia/Sydney', 'Asia/Vladivostok', 'Asia/Magadan', 'Pacific/Fiji', 'Pacific/Kwajalein', 'Asia/Kamchatka',
  'Pacific/Auckland',

Приклад повного коду віджету разом з робочими годинами:

<script type="text/javascript">
  window.helpcrunchSettings = {
    organization: 'helpcrunch',
    appId: 'a47f724b-bh1f-4504-7fa7-0fbf7dg84kb0',
    user: {
      user_id: 'userOneHash',
      name: 'User One',
      email: '[email protected]',
      phone: '+380123456789',
      company: 'my company',
      custom_data: {
        is_active: true,
        money_spent: 2500,
        subscription: 'gold',
        accepted_agreement: true,
      },
    },
  };

</script>

<script type="text/javascript">
  (function(w,d){var hS=w.helpcrunchSettings;if(!hS||!hS.organization){return;}var widgetSrc='https://'+hS.organization+'.widget.helpcrunch.com/';w.HelpCrunch=function(){w.HelpCrunch.q.push(arguments)};w.HelpCrunch.q=[];function r(){if (d.querySelector('script[src="' + widgetSrc + '"')) { return; }var s=d.createElement('script');s.async=1;s.type='text/javascript';s.src=widgetSrc;(d.body||d.head).appendChild(s);}if(d.readyState === 'complete'||hS.loadImmediately){r();} else if(w.attachEvent){w.attachEvent('onload',r)}else{w.addEventListener('load',r,false)}})(window, document)

HelpCrunch('setOperatingHours', {
  timezone: 'Europe/London',
  hours: {
    monday: {
      is_enabled: true,
      from: "03:00",
      to: "13:00",
    },
    tuesday: {
      is_enabled: true,
      from: "03:00",
      to: "13:00",
    },
    wednesday: {
      is_enabled: true,
      from: "03:00",
      to: "13:00",
    },
    thursday: {
      is_enabled: true,
      from: "03:00",
      to: "13:00",
    },
    friday: {
      is_enabled: true,
      from: "03:00",
      to: "13:00",
    },
    saturday: {
      is_enabled: false,
      from: "03:00",
      to: "13:00",
    },
    sunday: {
      is_enabled: false,
      from: "03:00",
      to: "13:00",
    },
  }
});
</script>

openKBArticle

Для відкриття конкретних статей бази знань у віджеті чату, в певній локалізації:

HelpCrunch('openKBArticle', { articleId: 125, lang: 'uk' })

onError

У разі виникнення будь-якої помилки у віджеті чату, цей метод дозволяє вам реагувати відповідним чином:

HelpCrunch('onError', (error) => {

});

setMediaCSS

Медіа CSS корисний, коли ви хочете змінити стилі віджетів, визначивши певні класи, залежно від розміру вікна перегляду браузера.

Стандартні медіа-запити CSS не працюватимуть належним чином, оскільки віджет HelpCrunch знаходиться всередині iframe, тому важливо відстежувати розмір області перегляду браузера, а не iframe.
HelpCrunch('setMediaCSS', {
  maxWidth: {
    800: 'max-width-800-class',
    320: 'max-width-320-class'
  },
  maxHeight: {
    400: 'max-height-400-class'
  }
})

Приклад:

#helpcrunch-container.max-width-800-class .helpcrunch-status-bar .helpcrunch-widget-icon-wrapper {       
  color: tomato;
}

Чи була наша стаття корисною?
close-image
full-image