Встановлення чат-віджета в односторінковому застосунку (SPA)

На традиційному багатосторінковому сайті браузер щоразу перезавантажує документ, коли відвідувач відкриває іншу сторінку. В односторінковому застосунку все працює інакше: основний документ завантажується один раз, а маршрут і вміст сторінки змінюються за допомогою JavaScript.

Тому код встановлення HelpCrunch також має виконуватися лише один раз. Не потрібно повторно ініціалізувати віджет або надсилати ті самі дані користувача після кожного переходу між маршрутами. Натомість прив’яжіть методи HelpCrunch JS API до стану автентифікації та подій роутера у вашому застосунку.

---

Зміст:

• Перед початком роботи

• Встановіть віджет один раз у кореневому шаблоні застосунку

• Оберіть, коли ідентифікувати користувача

  • Варіант A: ініціалізуйте віджет разом із даними користувача

  • Варіант B: ініціалізуйте віджет для відвідувача, а потім автентифікуйте користувача

  • Варіант C: дочекайтеся даних користувача, перш ніж ініціалізувати віджет

  • Вимоги до автентифікації користувача

• Що робити після переходу між маршрутами без перезавантаження сторінки

• Оновлюйте дані користувача лише тоді, коли вони змінюються

  • Оновлення стандартних атрибутів користувача

  • Оновлення власних атрибутів користувача

• Завершуйте сесію користувача у віджеті

• Керуйте віджетом на різних маршрутах SPA

• За потреби дочекайтеся готовності HelpCrunch

• Поширені помилки під час встановлення віджета в SPA

• Чеклист для тестування

---

Перед початком роботи

Скопіюйте код віджета у своєму акаунті HelpCrunch у розділі Налаштування → Канали → Веб-віджети → Назва_вашого_віджета → Встановлення.

Вам знадобляться:

• Назва вашої організації в HelpCrunch

• appId віджета зі скопійованого коду встановлення

• Доступ до кореневого HTML-шаблону або макета (root layout) вашого SPA

• Доступ до подій автентифікації та роутера застосунку, якщо потрібно ідентифікувати користувачів або змінювати поведінку віджета залежно від маршруту

---

1. Встановіть віджет один раз у кореневому шаблоні застосунку

Додайте повний код віджета, скопійований із HelpCrunch, перед закриваючим тегом </body> у головному HTML-файлі вашого SPA. Залежно від фреймворку це може бути index.html, кореневий макет (root layout) або інший компонент, який залишається змонтованим протягом усієї сесії в браузері.

Налаштування віджета матимуть приблизно такий вигляд:

<script>
  window.helpcrunchSettings = {
    organization: '<your-organization>',
    appId: '<your-appId>'
  };
</script>

<!-- Вставте нижче решту коду віджета, скопійованого з HelpCrunch. -->

Якщо ваш фреймворк використовує серверний рендеринг (SSR), переконайтеся, що код віджета виконується лише у браузері, де доступні window і document.

---

2. Оберіть, коли ідентифікувати користувача

Оберіть варіант залежно від того, коли ваш застосунок отримує дані користувача.

Варіант A: ініціалізуйте віджет разом із даними користувача

Використовуйте цей варіант, якщо дані автентифікованого користувача доступні ще до ініціалізації віджета.

<script>
  window.helpcrunchSettings = {
    organization: '<your-organization>',
    appId: '<your-appId>',
    user: {
      user_id: '<unique-user-id>',
      name: 'Jane Doe',
      email: '[email protected]',
      phone: '+12025550123',
      company: 'Example Inc.',
      custom_data: {
        subscription: 'pro',
        is_active: true
      }
    },
    signature: '<signature-from-your-backend>'
  };
</script>

<!-- Нижче вставте решту коду віджета, скопійованого з HelpCrunch. -->

Варіант B: ініціалізуйте віджет для відвідувача, а потім автентифікуйте користувача

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

Встановіть віджет звичайним способом, передавши organization і appId. Після успішного входу, коли застосунок отримає дані користувача, викличте userAuth:

function identifyHelpCrunchUser(user, signature) {
  HelpCrunch(
    'userAuth',
    {
      user_id: String(user.id),
      name: user.name,
      email: user.email,
      phone: user.phone,
      company: user.company
    },
    signature
  );
}

Варіант C: дочекайтеся даних користувача, перш ніж ініціалізувати віджет

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

Спочатку додайте до налаштувань лише назву організації та залиште основний код завантаження з коду встановлення HelpCrunch:

window.helpcrunchSettings = {
  organization: '<your-organization>'
};

На цьому етапі не передавайте appId. Коли застосунок отримає дані користувача, ініціалізуйте та відобразіть віджет вручну:

async function startHelpCrunch(user, signature) {
  HelpCrunch('init', '<your-organization>', {
    appId: '<your-app-id>',
    user: {
      user_id: String(user.id),
      name: user.name,
      email: user.email,
      phone: user.phone,
      company: user.company,
      custom_data: {
        subscription: user.subscription,
        is_active: user.isActive
      }
    },
    signature
  });

  HelpCrunch('showChatWidget');
}

Вимоги до автентифікації користувача

Під час увімкнення режиму автентифікації користувача врахуйте такі вимоги:

• user_id має бути рядком (string) і бути унікальним для кожного користувача

• Не призначайте однаковий user_id різним акаунтам

• Генеруйте хеші або підписи для автентифікації на бекенді – ніколи не передавайте секретний ключ або сіль хешування (hash salt) у фронтенд-коді

• Передавайте user_id, щоб автентифікувати користувача та зберігати єдину історію його чатів між сесіями й пристроями;

• Якщо передати лише ім’я або email без user_id, користувача не буде автентифіковано – ці значення лише автоматично заповнять форму перед початком чату

• Форма чату перед початком розмовы не відображається для користувача, автентифікованого за допомогою режиму автентифікації користувача

---

3. Що робити після переходу між маршрутами без перезавантаження сторінки

Коли роутер змінює URL, віджет HelpCrunch залишається ініціалізованим. Поточна розмова та ідентифікований користувач також нікуди не зникають.

Тому не викликайте init, userAuth або updateUser після кожного переходу, якщо користувач і його дані не змінилися.

Використовуйте хук роутера лише для дій, які справді залежать від нового маршруту. Наприклад, щоб:

• Показати або приховати віджет

• Змінити мову віджета

• Зафіксувати перехід користувача до певного розділу застосунку

• Оновити власний атрибут, наприклад поточний розділ продукту

• Відкрити чат або запустити певне повідомлення після дії, пов’язаної з маршрутом

---

4. Оновлюйте дані користувача лише тоді, коли вони змінюються

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

Оновлення стандартних атрибутів користувача

Використовуйте updateUser, коли користувач змінює ім’я, email, номер телефону або компанію. Можна передати лише ті поля, які змінилися.

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

Оновлення власних атрибутів користувача

Використовуйте updateUserData, щоб оновлювати дані, пов’язані з вашим продуктом або бізнесом:

HelpCrunch('updateUserData', {
  subscription: 'enterprise',
  projects_count: 12,
  trial_ends_at: '2026-09-01T10:00:00+00:00'
});

Спочатку створіть відповідні атрибути у розділі Налаштування → Контакти → Власні атрибути. Власні дані можуть містити значення типів integer, float, string, URL, boolean і DateTime. Динамічно оновлювати власні дані можна лише для користувачів із user_id.

Використовуйте власні атрибути, щоб зберігати останній відомий стан. Якщо потрібна хронологія переходів або дій користувача, викликайте trackEvent, а не перезаписуйте той самий власний атрибут після кожної дії.

---

5. Завершуйте сесію користувача у віджеті

Якщо просто очистити локальний стан користувача у вашому застосунку, його сесія в HelpCrunch не завершиться автоматично. Коли користувач виходить зі свого акаунта у SPA, викличте метод logout:

HelpCrunch('logout', function (data) {
  if (data?.success) {
    // The HelpCrunch session has been cleared.
  }
});

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

Щоб перейти безпосередньо з одного акаунта до іншого:

1. Викличте logout для поточного користувача HelpCrunch.

2. Дочекайтеся виклику callback-функції з підтвердженням успішного завершення сесії.

3. Викличте userAuth, передавши унікальний user_id нового користувача та підпис безпеки, якщо його ввімкнено.

---

6. Керуйте віджетом на різних маршрутах SPA

Викликайте методи HelpCrunch JS API з обробників подій роутера або компонента:

HelpCrunch('showChatWidget'); // Show the widget button
HelpCrunch('hideChatWidget'); // Hide the widget button
HelpCrunch('openChat');       // Open the chat panel
HelpCrunch('closeChat');      // Close the chat panel

Метод hideChatWidget приховує кнопку віджета. Якщо на закритому маршруті потрібно також приховати вже відкрите вікно чату, викличте closeChat перед hideChatWidget.

Для кнопок, доступних лише на певних маршрутах, викликайте методи безпосередньо з обробника натискання у вашому фреймворку:

function contactSupport() {
  HelpCrunch('typeUserMessage', 'I need help with my subscription');
  HelpCrunch('openChat');
}

У SPA надійніше використовувати методи API, ніж додавати до URL
?HelpCrunchOpenChat=1 або ?HelpCrunchInputText=.... Ці параметри обробляються переважно під час завантаження сторінки, а перехід між маршрутами на стороні клієнта не запускає цю логіку повторно.

Якщо ви використовуєте правила видимості віджета на основі URL, правила для автоповідомлень або попапів, налаштовані в HelpCrunch, перевірте їх і під час прямого завантаження сторінки, і під час переходів між маршрутами без перезавантаження. Якщо поведінка віджета має змінюватися одразу після кожного переходу, викликайте відповідний метод JS API з хука роутера.

---

7. За потреби дочекайтеся готовності HelpCrunch

Код встановлення HelpCrunch створює чергу команд, тому виклики API, зроблені до ініціалізації, можуть виконатися після завершення init. Якщо певну дію потрібно виконати лише після завантаження основного скрипту, використовуйте onScriptLoaded:

HelpCrunch('onScriptLoaded', () => {
  // HelpCrunch-dependent logic
});

Якщо ви створюєте власну кнопку відкриття чату й маєте дочекатися повної готовності ініціалізованого віджета, використовуйте onReady:

HelpCrunch('onReady', () => {
  // Display or enable your custom chat button
});

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

---

Поширені помилки під час встановлення віджета в SPA

• Додавання повного коду віджета до кожного компонента, що завантажується роутером

• Виклик init після кожного переходу

• Повторні виклики userAuth, хоча поточний користувач не змінився

• Передавання user_id як числа, а не рядка

• Використання однакового user_id для різних користувачів

• Генерування підпису безпеки або зберігання солі хешування (hash salt) у фронтенд-коді

• Оновлення власних даних до створення відповідних атрибутів у HelpCrunch

• Виклик updateUserData для анонімного відвідувача без user_id

• Очищення сесії застосунку без виклику HelpCrunch('logout')

• Автентифікація другого акаунта до завершення сесії першого користувача HelpCrunch

• Очікування, що window.onload спрацює після переходу між маршрутами на стороні клієнта

• Повторна реєстрація тих самих обробників роутера або натискань після кожного рендерингу

---

Чеклист для тестування

Після встановлення віджета перевірте такі сценарії:

1. Відкрийте публічний маршрут із повним завантаженням сторінки та переконайтеся, що віджет з’явився.

2. Перейдіть між маршрутами без перезавантаження сторінки та переконайтеся, що віджет залишається ініціалізованим.

3. Відкрийте пряме посилання на вкладену сторінку й перевірте, чи правильно працюють видимість і локалізація для цього маршруту.

4. Увійдіть в акаунт без перезавантаження сторінки та переконайтеся, що в розділі Контакти відображається правильний користувач.

5. Змініть email користувача або власний атрибут і перевірте, чи оновився профіль.

6. Змініть мову застосунку та переконайтеся, що локалізація віджета також змінилася.

7. Перейдіть на маршрути, де віджет має бути прихований, і перевірте, чи зникає кнопка та, за потреби, відкрите вікно чату.

8. Скористайтеся кнопками браузера «Назад» і «Вперед» та переконайтеся, що хук роутера спрацьовує один раз для кожного переходу.

9. Вийдіть з одного акаунта, увійдіть в інший і перевірте, чи не змішуються розмови та дані двох користувачів.

10. Переконайтеся, що протягом однієї клієнтської сесії скрипт віджета HelpCrunch завантажується лише один раз.

---

Читайте також:

• Як встановити HelpCrunch на сайт (для відвідувачів)

• Як встановити HelpCrunch у застосунку (для авторизованих користувачів)

• Як увімкнути режим автентифікації користувача через JS API

• Способи ініціалізації віджета чату

• Методи JS API

• Як керувати відображенням віджета чату на сайті

• Власні дані користувача