Демо-застосунок

demo/ у корені репозиторію. Сторінка, яка не описує три способи вбудовування, а показує всі три в роботі. AGNT2-241.

Вбудовування працювало й до цієї теки, але щоб його показати, щоразу доводилося збирати сторінку руками. Це вона і є, зібрана один раз і залишена в репозиторії.

Як запустити

cp demo/.env.example demo/.env     # і заповнити три рядки
make dev                           # api + app + admin + демо на :3002

або окремо, без решти трьох застосунків:

node demo/server.mjs               # :3002, або DEMO_PORT=3999 node demo/server.mjs

Встановлювати нічого. У демо немає залежностей, немає збірки і немає lock-файлу — node demo/server.mjs піднімається з чистого клону. Це рішення: четвертий пакетний маніфест поруч з api, app і admin означав би четверте встановлення в make dev і ще одне місце, де встановлене дерево розходиться з оголошеним.

Усередині Superset-воркспейсу

make dev займає спільні порти 3000/3001/3333 і вбиває тих, хто їх тримає, тому там його запускати не можна. Демо піднімає ./.superset/run.sh — на порту API_PORT + 3 з власного блоку воркспейсу.

Налаштування, і жодного рядка в коді

Усе живе в demo/.env. Жоден файл усередині demo/ не треба правити заради чогось із цього, а в репозиторії немає жодного справжнього ідентифікатора, квитка чи ключа — лише demo/.env.example з іменами та формою значень.

змінна	що це
AGENTFY_AGENT_ID	до якого агента звертається віджет
AGENTFY_HUB_URL	адреса хаба, куди стукає браузер відвідувача — це не порт api
AGENTFY_EMBED_KEY	ключ команди. Заданий — демо випускає квитки саме, див. нижче
AGENTFY_API_URL	api, до якого сервер демо йде з цим ключем
AGENTFY_EMBED_TOKEN	квиток, вставлений руками. Використовується лише за порожнього ключа
AGENTFY_TOKEN_URL	куди по квиток ходить віджет усередині цієї документації — /token демо
AGENTFY_SDK_URL	звідки береться бандл віджета; порожньо — стокова адреса
AGENTFY_DOCS_URL	де піднята ця документація, для посилань назад у розділ
DEMO_PORT	порт демо; за замовчуванням 3002

Ключ не залишає процес демо. Його немає в жодній відповіді, яку бачить браузер, і його не читає збірка документації — див. нижче.

Що показує сторінка

спосіб	на сторінці
тег <script>, плаваюча бульбашка	наживо — бульбашка в правому нижньому куті
пакет у вашій збірці	наживо — вікно всередині сторінки, тим самим init({ mode: 'inline', mount }); описано, а не виконано, лише рядок npm i, бо в демо навмисно немає збірки
власний інтерфейс поверх клієнта	наживо — чат, намальований цілком версткою самої сторінки поверх BridleClient

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

П'ятнадцять хвилин, і дві відповіді на них

Квиток вбудовування живе 15 хвилин за замовчуванням і добу максимум — див. чому він не може жити довше. Отже, демо з квитком, вписаним у файл, гарантовано одного дня перестане відповідати, і людина, дивлячись на мовчазний віджет, вирішить, що зламалося вбудовування.

Тому в демо два режими, і воно каже на сторінці, у якому з них зараз.

key — спливати нічому

Коли задано AGENTFY_EMBED_KEY, сервер демо працює бекендом сайту: він просить в api квиток на конкретного покупця в момент, коли сторінка підключається. Квитка у файлі немає взагалі, тому в ньому нічому протухнути. Так робить справжній сайт, і це той режим, яким варто користуватися.

Заразом видно головне, заради чого ключ і потрібен: три блоки приходять трьома названими людьми, а не трьома незнайомцями, і з'являються у списку лідів команди з іменами та поштою.

token — випадок, який цього уникнути не може

Без ключа і зі вставленим AGENTFY_EMBED_TOKEN демо поводиться як статичний сайт: читає власний квиток до того, як віддати його віджету, показує залишок, а коли строк вийшов — каже саме це: коли він скінчився, чому строк такий короткий, де випустити новий і що сервер перезапускати не треба, бо .env перечитується на кожен запит конфігурації. Якщо строк виходить, поки сторінка відкрита, зворотний відлік доводить до того самого пояснення без перезавантаження, а віджети знімаються, а не висять, вдаючи.

Віджет у самих цих сторінках

Розділ, який ви читаєте, несе ту саму плаваючу бульбашку — на /embed/* в усіх трьох мовах, — і вона знімається, коли ви йдете з розділу.

Налаштовується вона з того самого demo/.env і є саме тим випадком, про який розділ сперечається: зібрана документація — це статичний сайт без власного бекенда. Тому вона бере AGENTFY_TOKEN_URL — /token демо, — якщо він є, і вставлений AGENTFY_EMBED_TOKEN, якщо ні.

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

Порт

3002, доданий у трьох місцях: make dev його піднімає, make kill-ports звільняє перед стартом, make down — після. Наявні три — 3000, 3001, 3333 — не зачеплені.

Порт, доданий у dev і забутий у kill-ports, ламається так, що це варто назвати: демо переживає одне Ctrl-C, тримає порт, і наступний make dev падає на «адресу вже зайнято», не маючи на що показати.