Усунення несправностей і контрольний список

Інструменти

• Інструменти розробника → Мережа: loader.js, core.<hash>.js, з’єднання WebSocket (вкладка «Повідомлення» або «Кадри» показує init, init_ok, error) або запити резервного каналу HTTP (h/auf, …/sse, …/tx).
• Увімкнути діагностику: data-rc-debug="true" у тегу завантажувача або localStorage.setItem('rc_debug','1') у консолі, потім перезавантажити.
• Консоль: ReactiveChat('getSession'), ReactiveChat('getEndpoint'), ReactiveChat('isOpen'), ReactiveChat.version.

Кнопки чату не видно

• Ключ сайту відсутній або недійсний. Тоді завантажувач мовчки зупиняється. Перевірте data-rc-site-key (8–64 символи з A–Z a–z 0–9 _ -) на виконаному тегу: менеджери тегів і допоміжні засоби фреймворків іноді відкидають атрибути.
• type="module" у тегу скрипту: тоді завантажувач не знаходить свій тег. Вбудовуйте його як класичний скрипт.
• data-rc-hide-launcher="true" або в обліковому записі задано «Лише через власні посилання (без значка чату)».
• У фрагменті немає кольору бренду: без дійсного кольору data-rc-brand кнопка з’являється лише після встановлення з’єднання. Скопіюйте фрагмент з облікового запису знову.
• Проєкт призупинено або ключ сайту невідомий: сервер відповідає unknown_site_key (закриття 4002); у цій вкладці віджет не повторює спробу десять хвилин.
• Ядро не завантажується: консоль показує [reactive.chat] core.js …. Часто адресу блокує script-src або блокувальник реклами — див. Власний домен.

Кнопка є, але повідомлення не надходять

• Власне розміщення loader.js без data-rc-ws-url: віджет шукає сервер чату на вашому домені. На вкладці мережі видно марні спроби підключення до wss://ws.<your-domain>/rc_wss/. Рішення: data-rc-ws-url="wss://ws.reactive.chat/rc_wss/".
• origin_denied, закриття 1008: домену сторінки немає в Дозволених джерелах. Введіть домен сайту, а не піддомен чату.
• CSP блокує: у консолі є повідомлення CSP про wss://… або https://…/rc_wss/h/auf. Додайте обидва варіанти до connect-src.
• Корпоративна мережа без WebSocket: після двох невдалих спроб віджет переходить на резервний канал HTTP. Якщо він теж не працює, перевірте проксі, що переривають запити раніше ніж за 30 секунд або буферизують відповіді (Транспорт).
• Блокування захистом від зловживань (закриття 1008 blocked): типово за власним проксі без дійсного ключа проксі, бо тоді всі відвідувачі мають одну адресу.
• Повідомлення задовге: віджет не надсилає тексти понад ліміт тарифу (1000 або 4000 символів).

Користувач, який увійшов, вважається анонімним

Кадр error містить auth_failed із detail.reason:

• no_hash — у identify немає userHash.
• no_secret — у проєкті не налаштовано секрет.
• bad_exp — exp у мілісекундах замість секунд або не ціле число.
• expired — сторінка довго відкрита або неправильний годинник сервера; обчислюйте хеш заново під час завантаження сторінки.
• exp_too_far — більш як на 24 години вперед.
• bad_hash — секрет, порядок (userId + "." + exp) або набір символів не збігаються; секрет — це ключ як рядок, а не декодовані байти. Електронну адресу потрібно підписати саме так, як ви її передаєте.

Докладно: Ідентифікація відвідувачів.

Дані клієнтів не надходять

• Асистент просить користувача ввійти, хоча той уже ввійшов: exp відсутній або прострочений — без exp даних клієнтів немає.
• Перевірити з’єднання в обліковому записі називає причину (http_401, zeitueberschreitung, umleitung, adresse_privat …). Підписаний рядок — X-RC-Zeit + "." + raw body; перевіряйте отримані байти, а не повторно закодований JSON.
• У відповіді асистента бракує поля: воно не ввімкнене в обліковому записі або входить до переліку полів, які ніколи не приймаються.

Докладно: Кінцева точка даних клієнтів.

Вебхуки не надходять

• Чи ввімкнено інтеграцію й вибрано подію (немає вибору = усі)? Після ввімкнення зачекайте до 15 секунд.
• Кінцева точка відповідає довше ніж 10 секунд або повертає перенаправлення.
• Кінцева точка одного разу відповіла 410 — це деактивує інтеграцію. Увімкніть її знову.
• Підпис не збігається: обчислюйте за сирим тілом і X-RC-Timestamp + "." + body, зважайте на префікс sha256=.
• У data бракує вмісту: поля кожної події наведено в розділі Вебхуки; невибрана подія взагалі не надходить.

Серверний API

• 401 auth_failed: ключ відкликано, введено неправильно або його автор більше не адміністратор.
• 403 insufficient_scope: прав недостатньо; required_scope указує потрібні.
• 429: перевищено 120 запитів за хвилину; дотримуйтеся Retry-After.
• 415/413: немає Content-Type: application/json або тіло перевищує 64 КіБ.

Текст конфіденційності не з’являється

• Завантажувач відсутній на сторінці або заблокований платформою згоди: вбудуйте datenschutz.js безпосередньо.
• Сайт не додано як домен у проєкті або проєкт призупинено.
• data-rc-privacy-state="error" на елементі вказує на невдалий запит.

Контрольний список перед запуском

1. Усі домени сайту додано до Дозволених джерел.
2. Незмінений фрагмент з облікового запису є на всіх сторінках, де має бути чат, зокрема на сторінці конфіденційності.
3. CSP: script-src для місця доставки, connect-src із wss:// та https://, img-src для зображень.
4. Згода: перевірено data-rc-consent або платформу згоди (TCF v2 / consented.eu), протестовано зі згодою та без неї.
5. Політику конфіденційності доповнено (<div data-rc-privacy> або текстовий блок).
6. Ідентифікація: userHash із exp обчислено на сервері, секрет лише в серверному середовищі, init_ok.identity.verified дорівнює true.
7. Області з конфіденційним текстом позначено data-rc-private.
8. Із власним доменом: усі п’ять кроків перевірки «OK», ключ проксі лише в конфігурації проксі, /rc_wss/h/ не потрапляє в журнал доступу.
9. Вебхуки: перевірено підпис і час, дублікати визначаються через X-RC-Delivery, швидка відповідь 2xx.
10. Резервний канал HTTP один раз перевірено з data-rc-transport="http".
11. Перевірено мобільний вигляд (нижче 480 пікселів чат відкривається на весь екран) та керування клавіатурою.