# Web-виджет Shopping Assistant

Справочник относится к готовому виджету `1.41`. Для первого запуска используйте [Web-гайд](./web.md); возможности сервера описаны в [API-справочнике](reference/overview.md).

## Параметры конструктора

Передайте объект в `new ShoppingAssistant(options)`.

| Параметр | Тип | По умолчанию | Назначение |
| --- | --- | --- | --- |
| `apiUrl` | `string` | `https://shopping-assistant-api.gravityfield.ai/shopping/generate` | Адрес генерации. |
| `feedbackUrl` | `string` | Выводится из `apiUrl`: `/generate` → `/feedback`. | Адрес PUT-оценки ответа. |
| `resourceId` | `string` | `"api request"` | В интеграции обязательно передайте `GF.userData.uid`. |
| `startScreenTitle` | `string` | `Помогу подобрать товар` | Заголовок стартового экрана. |
| `startScreenDescription` | `string` | Пустая строка. | Описание стартового экрана. |
| `startScreenLogoUrl` | `string` | Логотип Gravity Field из CDN. | Изображение стартового экрана. |
| `placeholder` | `string` | `Задать вопрос...` | Подсказка поля сообщения. |
| `quickQuestions` | `Array<{title: string, sub?: string}>` | Два примера о смартфонах. | Стартовые вопросы. Замените их под ваш магазин или передайте `[]`. |
| `autoInsertTrigger` | `boolean` | `true` | Создать встроенную кнопку открытия. |
| `focusInputOnOpen` | `boolean` | `true` | Перевести фокус в поле при открытии. |
| `enableCopyResponse` | `boolean` | `false` | Показать копирование текста рядом с оценкой ответа. |
| `textareaMaxLines` | `number` | `3` | Высота поля сообщения до появления прокрутки. |
| `loadingTexts` | `string[]` | Три текста о поиске товаров. | Сменяющиеся тексты ожидания; пустой массив возвращает значения по умолчанию. |
| `icons` | `Object` | Встроенные SVG. | Иконки `likeButton`, `dislikeButton`, `copyButton`. Передавайте только доверенную разметку. |
| `apiKey` | `string` | Не задан. | Дополнительный Bearer-заголовок, если он предусмотрен вашим подключением. Для стандартного Web-примера не требуется; серверный API-ключ в браузер не передавайте. |

`tenant_id` и контекст виджет берёт из текущих `GF.section` и `GF.pageContext` при отправке. Передача этих значений как произвольных параметров конструктора не заменяет настройку Web-интеграции.

## Методы

| Метод | Что делает |
| --- | --- |
| `attachTo(elementOrSelector)` | Вставляет контейнер в элемент или по CSS-селектору. Элемент должен существовать. |
| `open()` | Открывает чат; если разговора ещё нет, создаёт `threadId`. |
| `close()` | Закрывает чат, сохраняя текущую переписку. |
| `toggle()` | Переключает открытое и закрытое состояние. |
| `startNewChat()` | Отменяет текущую отправку, очищает переписку и создаёт новый `threadId`. |
| `destroy()` | Удаляет контейнер из DOM. Не является полной очисткой внутренних подписок. |

Объект `assistant.config` содержит параметры экземпляра. Если меняется пользователь, сначала вызовите `startNewChat()`, затем обновите `assistant.config.resourceId`. Обработчики кнопок, оверлея и товарных событий, добавленные вашей командой, снимайте в собственном коде.

## Товарное событие

Виджет создаёт контейнер для блока товаров и отправляет DOM-событие `shopping-assistant-recs` на `document`. Самостоятельного рендеринга полноценных товарных карточек в нём нет.

| Поле `event.detail` | Значение |
| --- | --- |
| `element` | Элемент товарного контейнера. |
| `uniqueId` | ID контейнера; используйте его как селектор вставки. |
| `skus` | SKU в порядке ответа ассистента. |
| `title` | Необязательный заголовок товарного блока. |
| `data` | Исходный блок `products`. |

Вставку и показ карточек реализуйте по [Web-гайду](./web.md#3-подключите-виджет-и-товары). Не используйте событие получения подборки как подтверждение видимости товаров.

## Что поддерживает версия 1.41

Виджет отправляет текстовые сообщения, отображает текстовые ответы и быстрые подсказки, создаёт товарные контейнеры и отправляет оценки через PUT. Переписка хранится в экземпляре на вкладке; автоматического восстановления после перезагрузки через history API нет.

Версия `1.41` не передаёт `messages[].id`. Повторная отправка после потери ответа может создать второе сообщение. Если нужны управляемые повторы без дублей, используйте собственный API-клиент со стабильным [ID сообщения](reference/generate.md#ошибки-и-повтор-запроса).

Запрос содержит `trafficType: "test"`, если адрес страницы включает `sl_preview`; иначе — `"real"`. Отдельного параметра `trafficType` в конструкторе нет. Обычная предпросмотрная вкладка должна действительно содержать этот признак, чтобы запросы не попали в боевой трафик.

Изображения, публичный шаринг и GET feedback требуют отдельной реализации интерфейса. В версии `1.41` кнопка `open_support_chat` закрывает ассистента и вызывает `window.$flomni.chat.openThread()`, если этот API доступен. Для другого сервиса поддержки нужен отдельный обработчик интерфейса; параметра конструктора для замены этого действия нет.

После изменения версии проверьте параметры, события, PUT-оценки и товарный шаблон на [тестовом сценарии](../troubleshooting.md). Не обновляйте только JS или только CSS.

В версии `1.41` кнопка оценки меняет состояние до завершения запроса. При ошибке отправки виджет пишет сообщение в консоль; автоматического отката кнопки нет. Проверяйте HTTP-ответ, а не только вид кнопки. Для собственного интерфейса применяйте состояние после успеха или возвращайте прежнюю оценку при ошибке.