Вікно на чужій сторінці: що вміє сам скрипт

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

Потрібна вона у трьох випадках: коли на сайті є особистий кабінет і бот має впізнавати людину; коли сайт — SPA, і вікно має знати, що зараз відкрито; коли чат треба відкривати своєю кнопкою.

Рядок, який видає кабінет

<script src="https://app.youselfbot.com/widget.js"
        data-bot-key="pk_..." data-api="https://api.youselfbot.com"></script>

data-bot-key — публічний ключ агента, він і має бути на сторінці. data-api кабінет додає сам, коли API живе на іншому імені.

Беріть рядок із розмови, а не звідси

Скажіть конструкторові «дай код для сайту» — він складе рядок із чинних налаштувань вашої збірки. Переписаний із памʼяті, він мовчки застаріває.

Хто цей відвідувач

Бот може памʼятати постійного клієнта й виконувати дії від його імені — але тільки якщо ваш сайт скаже, хто це.

Просто ідентифікатор

<script src="…/widget.js" data-bot-key="pk_..." data-user-token="user-42"></script>

або, якщо він у куці:

<script … data-user-token-cookie="uid"></script>

Це значення потрапляє в підстановку ваших дій — тобто чужий сервіс отримає запит із ідентифікатором саме цієї людини. Моделі воно не показується ніколи.

Це ще не доказ

Токен зі сторінки може підставити будь-хто: сторінка відкрита. Тому сам собою він не дає прав — лише позначає, чиї це дані в подальших викликах.

Підписаний конверт (коли від цього залежать права)

Коли бот має відповідати як адміністраторові (показувати чужі замовлення, міняти дані), потрібен підпис вашого бекенда:

<script … data-user-auth="v1.eyJ1c2VyIjoi….a3f9…"></script>

Конверт складається так: v1.<base64url(JSON)>.<HMAC-SHA256 hex>, де JSON —

{ "user": "user-42", "role": "admin", "bot": "b_ваш_агент", "exp": 1787400000 }

а підпис береться від рядка v1.<base64url(JSON)> ключем підпису відвідувачів цього агента. Ключ видно в кабінеті (панель агента, «Новий ключ підпису відвідувачів» — він же його й перевипускає).

Складати конверт має бекенд, у коді сторінки його бути не може: інакше ключ опиниться у відкритому HTML і роль «адміністратор» зможе виписати собі будь-хто. Термін життя (exp) ставте коротким — конверт, скопійований із чужого браузера, діє рівно доти. Понад 24 години ставити немає сенсу: довший термін сервер не приймає, і такий конверт не працює зовсім — підпису він не порушує, тож помилки ви не побачите, відвідувач просто лишиться без своєї ролі.

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

window.YouSelfBot — керування зі сторінки

Скрипт лишає рівно одне глобальне імʼя:

Виклик	Що робить
YouSelfBot.open() / .close() / .toggle()	відкрити, закрити, перемкнути вікно — щоб чат відкривала ваша кнопка
YouSelfBot.identify('user-42')	те саме, що data-user-token, але з коду
YouSelfBot.identify({ token, auth })	те саме з підписаним конвертом
YouSelfBot.setContext('Крок 2: оплата')	сказати боту, що людина зараз бачить — для SPA, де адреса не міняється
YouSelfBot.clearContext()	прибрати цю підказку
YouSelfBot.sessionId	ідентифікатор поточної розмови (для звірки в «Розмовах»)
YouSelfBot.reset()	почати розмову з нуля: після виходу з акаунта на вашому сайті

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

Після виходу з акаунта кличте reset()

Інакше наступна людина за тим самим компʼютером продовжить чужу розмову.

Атрибути, які переважають кабінет

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

Атрибут	Значення
data-title	заголовок вікна
data-greeting	перше повідомлення
data-accent	акцентний колір #12a150
data-position	left або bottom-left — лівий нижній кут; right або bottom-right — правий. Без атрибута — як налаштовано в кабінеті; невідоме значення віджет пропускає, пише попередження в консоль браузера й бере налаштування кабінету
data-theme	auto, light, dark
data-fit-site="off"	не переймати палітру сайту
data-page-context="off"	не читати сторінку, на якій стоїть вікно
data-nonce	значення nonce вашого CSP, якщо він строгий

Задане тут не змінити з розмови

Це найчастіша плутанина: власник просить «зроби акцент кавовим», конструктор чесно звітує «готово», а на сайті нічого не міняється — бо колір закріплено атрибутом. Прибирайте атрибут, якщо хочете керувати кольором із кабінету.

WordPress

Готовий плагін ставить вікно на сайт без правки теми. Архів віддає сам API — відкрито, без ключа:

GET /wordpress-plugin.zip

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

Пам'ятайте про попередження вище: заповнені поля плагіна (заголовок, привітання, колір) стають атрибутами й перебивають кабінет; позиція — теж, якщо вибрано «Ліворуч». Лишіть поля порожніми, а позицію «Праворуч», — і все це далі міняється в розмові. І перевірте адресу API, якщо ваша збірка тримає сайт і API на різних іменах.