Інструкція

Як підключити AI-віджет на сайт WordPress

Віджет — це один JS-файл, який сам монтується в ізольований Shadow DOM, тому не конфліктує зі стилями та скриптами теми. Підключення — це один тег <script> без додаткового коду ініціалізації.

1 тег <script>≤ 65 KB gzipShadow DOMДесктоп і мобільна версія

Сніпет для цього тестового середовища

Згенеровано з тегу, яким віджет підключено на цій сторінці, — можна одразу вставити на тестовий WordPress. Заповнюється у зібраній версії демо (develop, make widget-demo).

HTML
<!-- Локальний dev-режим: віджет підключено
     через /src/main.ts, без зібраного widget.js —
     сніпета з адресами середовища тут немає. -->

1. Сніпет підключення

Вставте тег перед закриваючим </body> на кожній сторінці сайту. Адреси нижче — приклад для продакшну; фактичні значення надає команда SoloWay.

HTML
<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» окремого запису: так він зʼявиться лише на одній сторінці.

Плагін WPCode / «Insert Headers and Footers» найпростіше

Code Snippets → Header & Footer → вставте сніпет у поле Footer → збережіть. Код теми не змінюється й не зникне після оновлення теми.

Дочірня тема, functions.php

Для розробників, які тримають тему в git. Додайте хук у functions.php дочірньої теми, щоб оновлення батьківської теми не стерло зміни:

PHP
add_action('wp_footer', function () { ?>
  <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>
<?php });

Поле «Додатковий код» у налаштуваннях теми

Деякі теми (Astra, GeneratePress, Kadence) мають власне поле для коду у footer. Воно працює так само, як і плагін вище.

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">. Сучасні теми додають його самі. Без нього телефон рендерить сторінку як десктопну, і мобільний вигляд не вмикається.
  • Мова віджета — кнопки і всього чату — визначається один раз під час завантаження сторінки:
    1. атрибут data-locale на тегу віджета, якщо він є;
    2. інакше мова сторінки з <html lang>: uk, uk-UA — українською, en, en-US тощо — англійською;
    3. для інших мов (de, sv…) і порожнього lang — англійською.
    WordPress сам виставляє <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. Збірка бандла (для розробників)

У репозиторії проєкту:

Shell
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=…), щоб відвідувачі отримали оновлення.