Демо-приложение

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 падает на «адрес уже занят», не имея на что показать.