Интеграция Shopping Assistant по API

Настройте Shopping Assistant в собственном интерфейсе через API. Ваше приложение самостоятельно вызывает Gravity Field API V2 и Shopping Assistant API, управляет состоянием диалога и отображает интерфейс ассистента.

Подробные контракты вынесены в API-справочник. Следуйте шагам ниже, чтобы получить первый ответ и отобразить товары. Параметры методов, примеры ответов и ошибки находятся на отдельных страницах.

Как работает интеграция

Схема показывает интеграцию с resourceId = user.uid. Если ваша интеграция использует user.custom, передавайте его значение как resourceId. При подключении гостевых токенов идентификатор остаётся тем же — в запросы добавляется токен.

sequenceDiagram
    actor User as Покупатель
    participant Client as Клиентский канал
    participant GFAPI as Gravity Field API V2
    participant Assistant as Shopping Assistant API

    Client->>GFAPI: POST /visit<br/>user + ctx + device
    GFAPI-->>Client: user.uid + user.ses
    Client->>Client: Сохранить uid и ses
    Client->>GFAPI: POST /event<br/>e-commerce события

    Client->>GFAPI: POST /choose<br/>selector + user + ctx<br/>isBuildEngagementUrl + isImplicitImpression
    GFAPI-->>Client: Вариация + tracking URL<br/>welcome-настройки опционально

    alt JSON-контракт разрешает показ
        Client->>Client: Показать точку входа и welcome-экран
        Client->>GFAPI: GET campaign WRIMP URL
        User->>Client: Открывает ассистента и отправляет сообщение
        Client->>GFAPI: POST /event<br/>события диалога
        Client->>Assistant: POST /shopping/generate<br/>threadId + resourceId=user.uid + новое сообщение
        Assistant-->>Client: contents + ui.suggests + tracking events
        Client->>Client: Отобразить ответ
        Client->>GFAPI: POST /event + GET tracking URL
        User->>Client: Оценивает ответ
        Client->>Assistant: GET feedback URL или PUT /shopping/feedback<br/>messageId + reaction
    else JSON-контракт запрещает показ
        Client->>Client: Не показывать ассистента
    end

Шаги интеграции

1. Синхронизируйте товарный фид

Shopping Assistant подбирает товары из каталога Gravity Field. До подключения API настройте синхронизацию фида и проверьте, что в нем есть актуальные товары, остатки и атрибуты, необходимые для подбора.

Формат, обязательные поля и настройка синхронизации описаны в разделе Требования к товарному фиду.

Если поиск и ранжирование должен выполнять собственный сервис клиента, подключите его через BYOA: контракт API и условия подключения описаны в разделе Свой поиск через BYOA.

Если ассистент должен отвечать о наличии товара в конкретном магазине, а магазинов много и остатки быстро меняются, подготовьте отдельный API наличия товаров в магазинах. Фид и lng не заменяют проверку актуального остатка по SKU и точке продаж.

2. Настройте API V2 и передачу просмотров

Получите sec и bearer API key, затем настройте HTTP-клиент по инструкции Начало интеграции API V2.

Передавайте POST /visit при каждом просмотре страницы или экрана, а не только там, где должен отображаться ассистент. В запросе используйте актуальные user, ctx и device.

Для нового пользователя передайте пустой user.
Для известного пользователя передайте сохраненные uid и ses.
Если используется собственный ID клиента, передайте user.custom вместе с user.ses.

Сохраняйте user.uid между сессиями, а user.ses - в рамках текущей сессии. Если API вернул обновленные значения, замените ими сохраненные. В запросах Shopping Assistant используйте user.uid как resourceId. Если интеграция использует user.custom, передавайте в resourceId его значение.

Структура пользователя, авторизация и правила хранения идентификаторов описаны в разделе Начало интеграции API V2.

3. Передавайте e-commerce события

Передавайте основные e-commerce события через POST /event:

add-to-cart-v1 - добавление товара в корзину;
purchase-v1 - покупка;
login-v1 и signup-v1 - авторизация и регистрация для склейки профилей пользователя.

При необходимости передавайте и другие события, предусмотренные вашей интеграцией. Вместе с каждым событием используйте актуальные user, ctx и device.

Просмотры страниц и e-commerce события нужны для профиля пользователя, контекстного таргетинга, аналитики и оценки результатов кампании.

4. Запросите API-кампанию по selector

Создайте и опубликуйте API-кампанию с согласованным selector: Создание API-кампании.

После /visit отдельно вызовите POST /choose:

передайте согласованный selector в data[].selector;
используйте актуальные user.uid, user.ses и ctx;
передайте options.isBuildEngagementUrl: true;
передайте options.isImplicitImpression: true, чтобы зафиксировать IMP вместе с выбором вариации.

Gravity Field применяет таргетинг и распределение трафика внутри API-кампании и возвращает выбранную вариацию.

Заранее согласуйте контракт контрольной группы. Она может возвращать пустой JSON или специальный флаг внутри JSON. Клиентский канал должен определять необходимость показа ассистента по согласованному контракту вариации.

Welcome-настройки в вариации необязательны. При необходимости через переменные кампании можно передавать title, subtitle и suggests[], а для разных ctx настраивать отдельные сценарии. Если значения не пришли, используйте настройки UI по умолчанию.

Передавайте в /choose актуальный контекст, чтобы Gravity Field мог применить нужный сценарий и таргетинг.

5. Отобразите кампанию и отправьте engagement

IMP фиксируется самим запросом /choose при включенном options.isImplicitImpression. Не вызывайте для него отдельный tracking URL.

Когда точка входа стала видимой, вызовите все tracking URL события WRIMP из ответа /choose.

Не собирайте engagement URL вручную и не ограничивайтесь первым URL в массиве. Общие правила описаны в разделе Взаимодействия с кампаниями.

6. Создайте диалог

Когда пользователь открывает ассистента:

Создайте стабильный threadId для новой чат-сессии.
Отобразите welcome-экран из настроек вариации или настроек UI по умолчанию.
Отправьте событие chat_dialog_open через API V2 POST /event.
При отправке сообщения передайте assistant_message_sent.
Вызовите POST /shopping/generate, передав:
- тот же threadId;
- resourceId, равный user.uid или используемому в интеграции user.custom; для гостевого запроса также добавьте заголовок Authorization;
- только новое сообщение пользователя;
- tenant_id и актуальный контекст; если выбран магазин, передайте его ID в runtimeContext.ctx.attributes.storeId.

На следующих ходах сохраняйте те же threadId и resourceId. Историю сообщений повторно передавать не нужно.

Контракт запроса, текстовые и графические сообщения описаны в API-справочнике.

Во время разработки проверьте транспорт и рендеринг на фиксированной заглушке: передайте trafficType: "debug". Такой запрос не обращается к LLM, не расходует токены и не сохраняется в истории. Формат запроса, полный ответ и ограничения режима описаны в разделе Режим отладки.

7. Отобразите ответ

Клиентский канал отвечает за рендеринг блоков из ответа:

message - сообщение ассистента;
products - товарные карточки;
button - действие клиента;
response.ui.suggests - быстрые ответы.

Событие assistant_response_received отправляйте только после успешного добавления ответа в UI. Если ответ содержит непустой блок товаров, дополнительно отправьте assistant_product_selection_received.

Сохраните assistantMessageId из ответа /shopping/generate вместе с сообщением: он нужен для отправки пользовательской оценки.

Если интерфейс должен меняться под задачу покупателя, используйте context.scenario.id и context.mode из готового ответа. Например, для подбора ноутбука можно показать элементы выбора диагонали и бюджета. ID сценариев доступны в Настройки ассистента → Сценарии. Контракт, режимы и обработка null описаны в разделе Контекст сценария и интерфейс.

Правила событий диалога: Трекинг событий Shopping Assistant. Полный контракт ответа: API-справочник.

8. Передайте tracking товаров

Shopping Assistant возвращает готовые tracking URL:

events[] верхнего уровня могут содержать tracking URL блока и ссылки оценки ответа;
events[] внутри товара относятся к конкретной карточке.

При видимости блока или карточки и при клике вызовите все URL соответствующего события. Ошибка tracking-запроса не должна блокировать UI или действие пользователя.

Ссылки like и dislike обрабатывайте отдельно, только при нажатии оценки. Не вызывайте все события из ответа автоматически.

Подробная структура событий и пример обработчика приведены в разделе Трекинг событий Shopping Assistant.

Дополнительные возможности

Следующие возможности не требуются для первого запуска. Подключайте их в зависимости от сценария клиентского интерфейса.

Подключение гостевых токенов

Зарегистрируйте resourceId через POST /shopping/guest-sessions, используя user.uid или значение user.custom из вашей интеграции Gravity Field. Сохраните полученные токен и sessionId вместе с идентификатором и передавайте токен в Authorization: Bearer gst_.... Используйте сохранённую сессию при повторных загрузках страницы; параллельные запросы должны ожидать одну регистрацию.

Каждая успешная регистрация, в том числе с прежним resourceId, создаёт отдельную сессию с пустой историей и памятью ассистента. При переходе с режима без токена очистите локальные диалоги прежнего режима; их история в новую сессию не переносится. При потере токена или 401 INVALID_GUEST_TOKEN очистите данные прежней сессии, зарегистрируйтесь с тем же UID и начните новый разговор. Действующие токены других сессий сохраняются. Получение, срок действия, отзыв и порядок восстановления описаны на странице гостевых токенов.

Персональные стартовые подсказки

Чтобы на welcome-экране показывать кнопки с учётом текущей страницы и доступных сведений о покупателе, подключите POST /shopping/starter-prompts. Метод требует гостевой токен и включённый набор подсказок для секции.

Передайте актуальный ctx и сохранённый гостевой токен. Для подбора не нужно создавать диалог или отправлять сообщение.
Покажите prompts[].text в порядке ответа. Если набор отключён, список пуст или запрос завершился ошибкой, используйте статические подсказки из вариации кампании или настроек UI; ошибки токена обрабатывайте по правилам гостевой сессии.
После нажатия отправьте выбранный текст обычным сообщением в /shopping/generate с той же сессией и актуальным контекстом страницы.

Контракт запроса, ответы и обработка ошибок: Стартовые подсказки. Быстрые ответы после сообщения ассистента по-прежнему берите из response.ui.suggests.

Оценка ответа

Покажите элементы оценки рядом с ответами. В прежнем режиме для нового ответа можно вызвать готовый GET URL типа like или dislike из events[]; для снятия реакции или оценки восстановленного сообщения используйте PUT. В гостевой интеграции используйте PUT с заголовком Authorization. Сохраняйте идентификатор именно того ответа, который оценивается. Контракты и ошибки: Оценка ответа.

Восстановление истории

Чтобы повторно открывать существующий диалог, вызывайте POST /shopping/history с теми же tenant_id, resourceId и threadId. Отображайте полученную историю в UI, но не отправляйте ее повторно в /shopping/generate. Контракт и пагинация описаны в Shopping Assistant API.

Для восстановления интерфейса используйте context последнего ответа ассистента, включая null. Не подставляйте сценарий из более раннего сообщения. Подробности: Контекст и восстановление интерфейса.

Для интерфейса со списком диалогов используйте гостевой токен:

Получите список через GET /shopping/dialogs и дайте выбрать разговор.
Загрузите последние сообщения выбранного threadId через POST /shopping/history с paginationMode: "backward". Более ранние страницы добавляйте сверху по курсору before.
Продолжайте разговор через /shopping/generate с тем же threadId, идентификатором пользователя и токеном. Для «Нового чата» меняется только threadId.
Для действия «Убрать из истории» вызовите DELETE /shopping/dialogs/{threadId} и после 204 уберите диалог из UI. Публичные ссылки на него также перестанут открываться.

При переходе между страницами сохраняйте токен, resourceId, sessionId и активный threadId; контекст страницы в новом запросе генерации обновляйте. Привязывайте threadId и локальную переписку к sessionId: новая сессия с тем же UID не получает доступ к старым диалогам. Контракты списка и скрытия: Диалоги. Эти элементы интерфейса реализует ваш клиентский канал.

Шаринг диалога

Чтобы покупатель мог поделиться историей разговора и товарной подборкой, добавьте действие «Поделиться» и создавайте публичную копию диалога (snapshot) через POST /dialogs/share. Публичный endpoint возвращает JSON; страницу для получателя и ее внешний вид реализует клиентский канал.

Используйте resourceId исходного диалога как user_id, а threadId — как dialog_id. Не передавайте tenant_id. Полный сценарий, контракт и ограничения описаны в разделе Шаринг диалогов.