Docs

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

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

Подробные контракты /shopping/generate, /shopping/feedback и /shopping/history вынесены в Shopping Assistant API reference. Контракт публичных ссылок описан в разделе Шаринг диалогов.

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

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: PUT /shopping/feedback<br/>messageId + reaction
    else JSON-контракт запрещает показ
        Client->>Client: Не показывать ассистента
    end

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

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

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

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

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. Создайте диалог

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

  1. Создайте стабильный threadId для новой чат-сессии.
  2. Отобразите welcome-экран из настроек вариации или настроек UI по умолчанию.
  3. Отправьте событие chat_dialog_open через API V2 POST /event.
  4. При отправке сообщения передайте assistant_message_sent.
  5. Вызовите POST /shopping/generate, передав:
    • тот же threadId;
    • resourceId, равный user.uid;
    • только новое сообщение пользователя;
    • tenant_id и актуальный контекст.

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

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

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

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

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

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

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

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

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

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

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

  • events[] верхнего уровня относятся ко всему блоку товаров;
  • events[] внутри товара относятся к конкретной карточке.

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

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

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

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

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

Чтобы собирать реакции покупателей, покажите элементы оценки рядом с ответами ассистента и вызывайте PUT /shopping/feedback. Используйте те же tenant_id, resourceId и threadId, а в messageId передавайте assistantMessageId ответа. Контракт и обработка ошибок описаны в Shopping Assistant API.

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

Чтобы повторно открывать существующий диалог, вызывайте 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. Полный сценарий, контракт и ограничения описаны в разделе Шаринг диалогов.

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

  • Товарный фид успешно синхронизируется и содержит необходимые для подбора товары и атрибуты.
  • /visit отправляется для всех просмотров страниц или экранов.
  • E-commerce события передаются через /event с теми же идентификаторами пользователя.
  • /visit возвращает или обновляет uid и ses, значения сохраняются корректно.
  • /choose вызывается по selector с isBuildEngagementUrl и isImplicitImpression.
  • API-кампания возвращает ожидаемые вариации и контрольную группу.
  • При отсутствии welcome-настроек используются значения UI по умолчанию.
  • Контрольная группа обрабатывается по согласованному JSON-контракту.
  • Campaign IMP фиксируется через isImplicitImpression, а WRIMP отправляется по всем URL один раз при видимости.
  • Один диалог использует неизменные threadId и resourceId.
  • В /shopping/generate отправляется только новое сообщение.
  • В debug-режиме клиент корректно отображает текст, товары и быстрые ответы из фиксированной заглушки.
  • Текст, изображения, товары, кнопки и быстрые ответы отображаются корректно.
  • assistantMessageId сохраняется вместе с каждым новым ответом ассистента.
  • Custom events диалога отправляются через API V2 POST /event.
  • Tracking URL блока товаров и отдельных карточек вызываются в нужный момент.
  • Повтор запроса после ошибки не создает новый диалог и не дублирует сообщение.

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

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

Связанные материалы

Shopping Assistant API
/shopping_assistant/api_reference/

Шаринг диалогов
/shopping_assistant/dialog_sharing/

Трекинг событий
/shopping_assistant/tracking/

© Copyright 2026. All rights reserved.