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

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

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

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

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.

Структура пользователя, авторизация и правила хранения идентификаторов описаны в разделе Начало интеграции 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;
- только новое сообщение пользователя;
- 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 вместе с сообщением: он нужен для отправки пользовательской оценки.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Проверка базовой интеграции

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

Оценка отправляется выбранным методом GET или PUT, а ошибки не оставляют в UI неподтверждённое состояние.
При восстановлении истории учитываются feedback.reaction и id сообщения ассистента.
Для шаринга используются те же resourceId и threadId, что и в исходном диалоге.
Публичная страница отображает только поля из snapshot-а и корректно обрабатывает недоступную или отозванную ссылку.
share_token не попадает в аналитику, error tracking и прикладные логи.