Встановлення віджета на сайт: один тег script

Для розробників, у коді: один тег script із вкладки «Встановлення» в панелі, що означає кожен атрибут і як перевірити, що працює.

Фрагмент коду панель дає на вкладці Встановлення віджета. Він прив’язаний до вашого сайту (ключ) і до одного віджета (код) і виглядає так:

<script
  src="https://<хост віджета>/widget.js"
  data-key="wk_…"
  data-code="default"
  data-agent-base="https://<хост агента>"
  async
></script>

Вставте його перед </body> на кожній сторінці, де має бути помічник, — або в поле «власний код» вашого конструктора сайтів. На цьому встановлення закінчується.

Атрибути

Атрибут	Що це
`src`	Бандл віджета з нашого CDN. Один файл, завантажується раз, кешується браузером.
`data-key`	Ключ віджета сайту. Він публічний за задумом і обмежений на сервері списком origin, вказаних для ключа, — копіюйте куди завгодно, працює лише на ваших доменах. Один ключ на всі віджети сайту.
`data-code`	Який віджет сайту завантажити. Перший віджет — `default`. Без цього атрибута бандл завантажує віджет `default` і пише попередження в консоль; на сайті з кількома віджетами скопіюйте фрагмент заново, щоб закріпити потрібний.
`data-agent-base`	Рантайм, з яким говорить віджет: `GET /widget/config` для вигляду, `WS /ws` для розмови, `/tts` і `/ws/stt` для голосу.
`async`	Завантажується, не блокуючи сторінку.

Без data-key або data-agent-base віджет пише попередження і нічого не робить.

Що завантажується

Один бандл, один хост-елемент. Віджет додає <div id="sa-widget"> у body і малює все всередині відкритого shadow root, тож CSS вашої сторінки не зачепить його випадково, а його CSS — вашу сторінку. На хост-елементі ви задаєте токени теми зі свого CSS (Тема); він лежить над усім (z-index: 2147483000).

<html lang> — вхідний параметр: він визначає мову власного тексту віджета (кнопки, підписи, привітання), підказує мову відповіді на перше повідомлення і перемикає інтерфейс у напрямок справа наліво для арабської, івриту та інших RTL-мов (Мови і RTL).

Один віджет на сторінку

Підтримується лише один віджет на сторінку: не вставляйте на одну сторінку два фрагменти. Щоб на різних сторінках був різний вигляд, створіть у панелі другий віджет і вставте його фрагмент на тих сторінках — ключ той самий, data-code інший.

Перевизначення конфігурації з сервера

Усе, що власник налаштував у панелі, приходить із GET /widget/config. Сторінка може перевизначити будь-що з цього до завантаження скрипта:

<script>
  window.ShukaiConfig = { color: "#059669", voiceCharacter: "fox" };
</script>
<script src="…/widget.js" data-key="…" data-code="…" data-agent-base="…" async></script>

Злиття неглибоке — ключі й три речі, які дивують, у Конфігурації.

Перевірте, що працює

Завантажте сторінку. Кнопка запуску з’являється в кутку, який обрав власник.
Відкрийте в браузері вкладку мережі: GET /widget/config відповідає 200 з налаштуваннями власника.
Спитайте щось, на що сайт відповідає. Під відповіддю є посилання на джерело.

У двох випадках нижче віджет нічого не пише в консоль, тож дивіться на цей запит. Якщо кут порожній, а він відповів active: false, — у сайту закінчилися кредити або немає тарифу: нічого не змонтувалося, і сторінка ні в чому не винна. Shukai.ready усе одно виконується, а кожен метод нічого не робить, доки тариф не стане активним.

Якщо він відповів 403, origin сторінки немає у списку дозволених для ключа: кнопка запуску однаково з’являється з вбудованим виглядом, але кожне питання відхиляється. Додайте origin на екрані API-ключів у панелі.

Якщо він відповів 404, у сайту немає ввімкненого віджета з data-code із фрагмента: його вимкнено на вкладці Встановлення, видалено, або код записано з помилкою. Нічого не з’являється, і цього разу консоль каже про це одним рядком.

Звідки беруться відповіді помічника

Не з цієї сторінки. Помічник відповідає з джерел, які власник додав у панелі — сторінок сайту, завантажених документів, вписаних нотаток — і з будь-якого власного інструмента, який власник підключив. Якщо ви поставили віджет на сторінку, яку власник не проіндексував, він усе одно працює; просто не знає, що на цій сторінці написано, доки її не додадуть як джерело.