Сніпет для цього тестового середовища
Згенеровано з тегу, яким віджет підключено на цій сторінці, —
можна одразу вставити на тестовий WordPress. Заповнюється у
зібраній версії демо (develop, make widget-demo).
<!-- Локальний dev-режим: віджет підключено
через /src/main.ts, без зібраного widget.js —
сніпета з адресами середовища тут немає. -->
1. Сніпет підключення
Вставте тег перед закриваючим </body> на
кожній сторінці сайту. Адреси нижче — приклад для
продакшну; фактичні значення надає команда SoloWay.
<script
src="https://cdn.soloway.tech/widget/widget.js"
data-api-base-url="https://api.soloway.tech/api/v1"
data-web-asset-base-url="https://aihelper.soloway.tech"
data-no-optimize="1"
defer
></script>
Атрибут defer необовʼязковий, але не блокує рендер
сторінки. А от type="module" додавати
не можна: віджет читає свої data-*
атрибути через document.currentScript, який для
модулів завжди null. Тоді віджет піде на локальні
адреси за замовчуванням.
Атрибут data-no-optimize="1" обовʼязковий: на soloway.tech
працює LiteSpeed Cache з відкладеним завантаженням JS. Він
переписує <script>-теги, і тоді віджет не бачить
власної адреси: він піде на локальний API і не знайде
widget-identity.js та український словник
widget-locale-uk.js. Для надійності додайте також
widget.js у LiteSpeed Cache → Page Optimization → JS
Excludes і «JS Delayed Excludes».
Уже підключили віджет раніше? Нічого міняти не
треба: сніпет і атрибути ті самі, а нові версії віджета (наприклад,
оновлена кнопка) приходять разом із widget.js одразу
після оновлення на сервері — файл віддається без довгого кешу.
Оновити вручну доведеться лише тим, хто скопіював
widget.js до себе на хостинг замість посилання на наш.
Мова віджета. Віджет показується українською або
англійською — так само, як сторінка, на якій він стоїть (див.
розділ 5). Для багатомовного сайту окремий сніпет на кожну мову
не потрібен: один і той самий тег на всіх мовних версіях. Якщо
widget.js скопійовано до себе на хостинг, поруч із ним
має лежати і новий файл widget-locale-uk.js (див.
розділ 8), інакше українські сторінки покажуть віджет англійською.
2. Атрибути
src
обовʼязковий
Публічна адреса зібраного widget.js (CDN або статичний хостинг).
data-api-base-url
обовʼязковий у продакшні
Базова адреса API разом із /api/v1. Без атрибута
віджет звертається до http://localhost:3001/api/v1,
що годиться лише для локальної розробки.
data-web-asset-base-url
рекомендований
Адреса standalone-сторінки асистента, з якої віджет бере
статичні файли (фото менеджера у формі контакту). Без
атрибута — http://localhost:3000, і фото на
реальному сайті не завантажиться.
data-locale
необовʼязковий
Мова віджета: uk або en (також
приймаються uk-UA, en-US). Зазвичай
атрибут не потрібен: без нього віджет бере мову сторінки з
<html lang>, яку WordPress уже виставляє на
кожній мовній версії сайту. Для інших мов сторінки (наприклад,
de, sv) віджет показується англійською.
Атрибут має пріоритет над мовою сторінки; невідоме значення
ігнорується з попередженням у консолі.
3. Куди вставити у WordPress
Віджет має бути на всіх сторінках, тому не вставляйте сніпет у блок «Кастомний HTML» окремого запису: так він зʼявиться лише на одній сторінці.
4. Дозволити домен сайту (CORS)
Браузер відвідувача звертається до API напряму з домену вашого
сайту, тому цей домен має бути у списку дозволених origin'ів на
бекенді: змінна CORS_WIDGET_ORIGIN в
apps/api, кілька доменів через кому. Вказуйте точний
origin зі схемою і без шляху та слеша в кінці, наприклад
https://soloway.tech. Домени www. і без
www. — це різні origin'и.
5. Кнопка, мобільна версія і сусідні елементи сайту
Кнопка асистента — капсула з назвою «SoloWay AI Assistant» і короткою фразою під нею, у нижньому лівому куті: 40px від країв на десктопі, 12px на телефоні (вона не розтягується на всю ширину — справа лишається місце для бульбашки чату). Поки чат відкритий на десктопі, кнопка показує «Згорнути».
На екранах до 767px віджет автоматично перемикається в мобільний вигляд: чат відкривається на весь екран, прокрутка сторінки під ним блокується, а кнопка «Назад» у браузері чи системі закриває чат замість того, щоб піти зі сторінки. Окремих налаштувань не потрібно, але зверніть увагу:
-
У
<head>теми має бути<meta name="viewport" content="width=device-width, initial-scale=1">. Сучасні теми додають його самі. Без нього телефон рендерить сторінку як десктопну, і мобільний вигляд не вмикається. -
Мова віджета — кнопки і всього чату — визначається
один раз під час завантаження сторінки:
- атрибут
data-localeна тегу віджета, якщо він є; - інакше мова сторінки з
<html lang>:uk,uk-UA— українською,en,en-USтощо — англійською; - для інших мов (
de,sv…) і порожньогоlang— англійською.
<html lang>на кожній мовній версії (функціяlanguage_attributes()у темі), тому зазвичай нічого налаштовувати не треба. Мова браузера відвідувача не враховується — віджет завжди мовою сторінки. Тексти відповіді AI пише мовою запиту; якщо відвідувач перейде на іншу мовну версію з уже готовою відповіддю, інтерфейс віджета зміниться на мову нової сторінки, а сама відповідь залишиться як є.
На цьому демо-сайті мовні версії імітує список у шапці (UA / EN / DE / SV / безlang): він змінює<html lang>сторінки так, як це робить WordPress, а текст сторінки лишається українським. Вибір зберігається між сторінками. Перевизначення черезdata-localeможна спробувати параметром?locale=uk(на англійській сторінці віджет стане українським;?locale=off— скинути).data-localeпрацює лише у зібраній версії віджета, не в Vite dev-режимі. - атрибут
-
Банер кукі і чат Tidio, як на soloway.tech
(плагін recookies,
#recookies-banner, і#tidio-chat), віджет обходить сам: кнопка не заходить під банер (на вузькому вікні бере коротшу фразу), вікно налаштувань кукі завжди поверх віджета, закрита бульбашка Tidio стає дзеркально справа на одну лінію з кнопкою (відкриту розмову віджет не чіпає), а на телефоні, поки банер без відповіді, кнопки зʼявляються лише після прокрутки першого екрана. Інші плагіни кукі, чати й кнопки «нагору» віджет не знає — перевірте, що вони не накладаються на кнопку (z-index: 2147483000), і за потреби перемістіть їх. -
Відступ у футері. Щоб останній рядок футера
можна було прокрутити вище кнопки, віджет додає в кінець
footer.main-footer(а якщо такого немає — першого<footer>сторінки) порожній блок.ai-widget-footer-room: 104px на десктопі, 76px на телефоні.
На цьому демо-сайті поведінку поруч із банером кукі і Tidio можна перевірити заглушками, що повторюють їхню геометрію на soloway.tech: банер без відповіді, після «Accept», після «Dismiss», англійська сторінка, українська сторінка. Стан зберігається між сторінками; вимкнути заглушки.
6. Перевірка після підключення
- На будь-якій сторінці внизу зліва зʼявилася кнопка асистента.
-
У консолі розробника (F12 → Console) немає помилок CORS, а у
вкладці Network запити йдуть на адресу з
data-api-base-url, а не наlocalhost. -
У вкладці Network після відкриття чату є запит
widget-identity.jsзі статусом 200 з того самого хоста, що йwidget.js. -
На українській версії сайту віджет українською, а у вкладці
Network є запит
widget-locale-uk.jsзі статусом 200 з того самого хоста, що йwidget.js. На англійській версії віджет англійською, і цього запиту немає. На інших мовних версіях (наприклад, німецькій) — англійською. - Після переходу на іншу сторінку розмова і відкрита панель зберігаються. На цьому демо-сайті можна пройти «Головна» → «Послуги» → «Блог» → «Контакти».
- На телефоні (або в DevTools → режим пристрою) чат відкривається на весь екран, а сторінка під ним не прокручується.
- Кнопка не ховається під cookie-банер чи інший чат, а останній рядок футера прокручується вище неї.
7. Типові проблеми
Кнопка віджета не зʼявляється
Перевірте у вкладці Network, що widget.js
завантажується з кодом 200. Якщо сніпет вставлено через
плагін, переконайтеся, що плагін активний і кеш сайту
(WP Rocket, LiteSpeed Cache, Cloudflare) очищено.
Запити йдуть на localhost замість продакшн-API
Віджет не отримав свої data-* атрибути. Найчастіше
причина в плагіні оптимізації, який обʼєднує, мініфікує або
відкладає JS («Combine JS», «Delay JavaScript execution»).
Додайте widget.js у виключення цих опцій.
Також перевірте, що тег не має type="module".
Помилка CORS у консолі
Домен сайту відсутній у CORS_WIDGET_ORIGIN на
бекенді, або вказаний з іншою схемою чи
www.. Див. розділ 4.
Віджет показується не тією мовою
Перевірте <html lang> сторінки (F12 →
Elements, перший рядок) і атрибут data-locale на
тегу віджета — він має пріоритет над мовою сторінки. Невідоме
значення data-locale віджет ігнорує й пише
попередження в консоль.
Якщо українська сторінка показує віджет англійською, у вкладці
Network знайдіть widget-locale-uk.js: файл має
лежати поруч із widget.js і віддаватися з кодом
200. Коли він недоступний, віджет навмисно показується
англійською, щоб не лишитися без інтерфейсу. Те саме буває,
якщо плагін оптимізації переписав тег віджета — див.
data-no-optimize="1" у розділі 1.
Не завантажується фото менеджера у формі контакту
Не вказано або вказано неправильно
data-web-asset-base-url. Атрибут має вести на
standalone-сторінку асистента, де лежить
/assets/contact/….
Внизу футера зʼявилося порожнє місце
Це блок .ai-widget-footer-room (104px / 76px на
телефоні), який віджет додає, щоб останній рядок футера не
лишався під кнопкою. Він бере фон футера. Див. розділ 5.
На телефоні віджет виглядає як на десктопі
У темі немає meta-тегу viewport. Див. розділ 5.
8. Збірка бандла (для розробників)
У репозиторії проєкту:
pnpm --filter widget build
gzip -c apps/widget/dist/widget.js | wc -c # має бути < 66560 байт
Команда створює три файли:
apps/widget/dist/widget.js,
apps/widget/dist/widget-identity.js (віджет сам
довантажує його під час відкриття чату) і
apps/widget/dist/widget-locale-uk.js (український
словник, довантажується на українських сторінках). Вони мають лежати
в одній теці на одному хості: віджет шукає
обидва додаткові файли поруч із власною адресою. Рекомендований
спосіб — компонент widget (UDS): його образ уже містить усі
три файли. Якщо копіюєте на CDN чи статичний хостинг — копіюйте їх
разом, з однаковими cache-заголовками. Не завантажуйте їх у медіатеку WordPress: там немає
версіювання та контролю кешу, потрібних для оновлень. Імена файлів
не змінюються між збірками, тому віддавайте їх з
Cache-Control: no-cache або додавайте версію в URL
(widget.js?v=…), щоб відвідувачі отримали оновлення.