Ассистент в Android и iOS SDK

Этот гайд проводит от настройки кампаний до работающей кнопки ассистента в приложении. После подключения покупатель открывает полноэкранный чат, задаёт вопрос, видит подборку товаров в дизайне вашего приложения и переходит из неё в карточку товара.

Вам нужно сделать три части интерфейса: кнопку входа, товарную карусель и обработчик переходов. Экран чата, отправку сообщений, хранение текущего диалога и отправку событий ассистента берёт на себя Gravity SDK.

Шаг 1. Подготовьте SDK и раздел магазина

До написания кода ассистента проверьте следующие условия. Настройки кабинета может подготовить ваша команда маркетинга или менеджер Gravity Field; разработчику нужны их значения и опубликованные кампании.

Что должно быть готово Что получить или проверить Инструкция
Базовый SDK SDK установлен и инициализирован один раз; известны API-ключ и section магазина. Android SDK, iOS SDK, API-ключи
Идентификация Передаются просмотры экранов и события входа пользователя; SDK получает user.uid и сессию. Идентификация пользователей и раздел идентификации в руководстве вашей платформы
Shopping Assistant Подключён тот же раздел, чей ID указан в section SDK; сервис допускает обращения мобильного приложения. Что требуется для Shopping Assistant
Товарный каталог Фид синхронизирован, SKU и данные карточек корректны. Требования к товарному фиду
Ответы ассистента Тестовый вопрос в кабинете возвращает ожидаемые ответы и товары. Превью ассистента

Для чата используйте обычную идентификацию Gravity SDK. Правила обмена section, uid и threadId описаны ниже.

Авторизация запросов ассистента

Этот раздел описывает планируемый API авторизации. Текущая реализация SDK отправляет запрос генерации без заголовка Authorization.

До первого prepareAssistant вызовите setAssistantAuth и выберите один из двух способов:

Способ Когда использовать Кто получает токен
Гостевой доступ Покупатель пользуется ассистентом без входа в аккаунт магазина. SDK регистрирует гостевую сессию и сохраняет её токен.
Токен клиента Приложение получает доступ к ассистенту через backend магазина. Приложение предоставляет поставщик токена; SDK вызывает его перед запросами.

Настройка действует для всего ассистента, а не для отдельной кампании. Токен передаётся как Authorization: Bearer <accessToken> в генерации, истории и оценках ответа. Его не нужно добавлять в JSON кампании или передавать из товарного блока.

Гостевой доступ

GravitySDK.instance.setAssistantAuth(AssistantAuth.Guest)
GravitySDK.instance.setAssistantAuth(.guest)

При подготовке SDK дожидается user.uid и получает токен через POST /shopping/guest-sessions с tenant_id = section и resourceId = user.uid. Действующая сохранённая сессия используется повторно. Параллельные запросы ожидают одну регистрацию.

SDK хранит accessToken и sessionId отдельно для каждой пары «раздел + user.uid» в защищённом хранилище приложения: Android Keystore с шифрованием данных или iOS Keychain. После перезапуска используется сохранённая сессия; автоматического восстановления открытого диалога при этом нет. При недоступном хранилище сессия остаётся только в памяти процесса.

История и память ассистента принадлежат гостевой сессии. При 401 INVALID_GUEST_TOKEN SDK сбрасывает её токен и локальный диалог. Следующий запрос регистрирует новую сессию с тем же user.uid. Если ошибка возникла при генерации, SDK один раз отправляет только текущее сообщение в новый threadId и сообщает покупателю об истечении сессии. Прежняя переписка не переносится. Ошибки регистрации не переключают запросы на доступ без токена; при 429 или 503 SDK предлагает повторить позже.

Формат регистрации, срок действия и ошибки сервиса: Гостевые токены.

Токен клиента

Передайте поставщик AssistantAuthProvider. Его метод getAccessToken(forceRefresh) асинхронно возвращает непустую строку токена без префикса Bearer. Backend клиента возвращает токен, принимаемый Shopping API для текущих section и user.uid; обычный токен входа в магазин можно использовать только при такой настройке доступа. SDK не меняет resourceId на ID аккаунта из токена.

val authProvider = object : AssistantAuthProvider {
    override suspend fun getAccessToken(forceRefresh: Boolean): String {
        return shopAuth.getAssistantToken(forceRefresh = forceRefresh)
    }
}

GravitySDK.instance.setAssistantAuth(AssistantAuth.Client(authProvider))
struct ShopAssistantAuthProvider: AssistantAuthProvider {
    let shopAuth: ShopAuth

    func getAccessToken(forceRefresh: Bool) async throws -> String {
        try await shopAuth.getAssistantToken(forceRefresh: forceRefresh)
    }
}

GravitySDK.instance.setAssistantAuth(
    .client(ShopAssistantAuthProvider(shopAuth: shopAuth))
)

shopAuth и ShopAuth в примерах — ваш адаптер обращения к backend магазина. В Swift адаптер должен быть Sendable, например actor. При forceRefresh = false он может вернуть действующий кешированный токен. При true должен запросить новый токен, минуя кеш. Хранением и обновлением клиентского токена управляет приложение; SDK использует результат поставщика для отправки запроса.

Во время подготовки SDK получает токен с forceRefresh = false в пределах общего timeout. Это не отправляет сообщение ассистенту. Перед последующими запросами SDK снова обращается к поставщику. После HTTP 401 SDK один раз вызывает его с forceRefresh = true и повторяет исходный запрос с теми же телом, threadId и ID сообщения. Обновление токена для того же пользователя сохраняет диалог. Повторный 401, пустой токен или отказ поставщика в доступе возвращают unauthorized; сетевые ошибки и timeout обрабатываются по общим правилам. Переключения на гостевой доступ при ошибке нет.

Вход, выход и смена способа доступа

При входе, выходе или смене аккаунта сначала обновите идентификацию базового SDK, затем вызовите setAssistantAuth с актуальным способом доступа и повторите подготовку. Каждый вызов setAssistantAuth закрывает чат, сбрасывает подготовку и локальный диалог, отменяет текущие запросы и инвалидирует ссылки на товары. Поздние токены и ответы прежнего пользователя не применяются. Обновлять токен внутри одного аккаунта следует через поставщик, без повторного setAssistantAuth.

«Новый чат» меняет только threadId и сохраняет действующий способ доступа и токен. Смена способа доступа начинает отдельный разговор; гостевая история не объединяется с историей аккаунта. Локальный сброс не отзывает токен на сервере: при выходе клиентский токен отзывает backend магазина, гостевой — метод отзыва сессии.

Шаг 2. Настройте две API-кампании

Кампания возвращает настройки интерфейса, которые SDK получает по selector — строковому имени кампании. В этой интеграции используются два разных selector:

Кампания Selector в примерах Что управляется из кабинета Кто читает JSON
Кнопка входа assistant-entry Показывать ли кнопку на экране и как её подписать. Приложение через getContentBySelector.
Ассистент shopping-assistant Включён ли чат, его заголовок, приветствие и стартовые подсказки. SDK внутри prepareAssistant.

Имена в таблице — пример. Задайте свои имена в кабинете и передайте те же строки в приложение, без изменения регистра или пробелов.

Создайте кампании в кабинете

Для каждой строки таблицы:

  1. Откройте Campaigns → API Campaigns и создайте кампанию типа Custom JSON.
  2. Укажите её API-селектор.
  3. Добавьте Experience — сценарий с условиями показа. Для первого теста выберите условия, которым соответствует ваш тестовый пользователь и экран.
  4. Создайте вариацию и вставьте подходящий JSON из примеров ниже в редактор её содержимого.
  5. Активируйте и сценарий, и кампанию, затем нажмите Опубликовать.

Пошаговые экраны кабинета: Создание API-кампании. Если терминология незнакома: кампания → сценарий → вариация. Условия выбора настраиваются в таргетинге и расписании; редактируемые тексты — через переменные вариаций.

JSON кнопки входа

Для assistant-entry:

{ "enabled": true, "title": "Спросите помощника" }
  • enabled: true разрешает приложению подготовить ассистента на этом экране.
  • title — подпись кнопки приложения. Её положение, иконку и внешний вид задаёте вы.
  • При enabled: false, отсутствии данных, некорректном JSON или ошибке запроса кнопка остаётся скрытой.

JSON ассистента

Для shopping-assistant:

{
  "enabled": true,
  "title": "Помощник магазина",
  "subtitle": "Помогу выбрать подходящий товар.",
  "suggests": ["Помогите выбрать подарок"]
}
Поле Назначение Если не задано
enabled Включает ассистента; тип Boolean. Обязательное поле.
title Заголовок внутри чата; заданная строка должна быть непустой. "Помощник"
subtitle Приветствие на стартовом экране. Пустая строка.
suggests Массив непустых строк. Нажатие отправляет выбранную строку как сообщение пользователя. Пустой массив.

При enabled: false остальные поля не используются, результат подготовки — unavailable(disabled). Неизвестные поля игнорируются. Несколько разных конфигураций для одного selector — invalid_configuration.

В редактор вставляется JSON-объект из примера, без внешней обёртки custom. В ответе SDK этот JSON находится строкой в CampaignContent.custom.json. Стартовые подсказки приходят из этой кампании; подсказки после ответа — из response.ui.suggests. Подготовка не отправляет скрытое сообщение ассистенту.

Шаг 3. Подключите товарный блок и переходы

До первой подготовки зарегистрируйте два объекта приложения:

Что реализовать Минимальная обязанность Контракт
AssistantProductBlockBuilder Нарисовать заголовок и горизонтальную карусель на переданную ширину; сообщать SDK о видимости и нажатии товара. Товарный блок
AssistantActionHandler Проверить поддержку действия и открыть карточку товара, поддержку или URL средствами приложения. Действия и навигация
GravitySDK.instance.setAssistantProductBlockBuilder(productBlockBuilder)
GravitySDK.instance.setAssistantActionHandler(actionHandler)
GravitySDK.instance.setAssistantProductBlockBuilder(productBlockBuilder)
GravitySDK.instance.setAssistantActionHandler(actionHandler)

Здесь productBlockBuilder и actionHandler — ваши реализации интерфейсов, приведённых ниже. В builder можно использовать существующий компонент карточки магазина. Он получает товары от SDK: отдельный запрос каталога для заполнения карусели не требуется.

При нажатии карточка сообщает tap SDK. Затем SDK учитывает клик, закрывает чат и вызывает ваш handler. В handler выполните переход по SKU или URL. Не делайте второй переход прямо из карточки. Для поддержки обработайте OpenSupportChat, для ссылки — FollowUrl; неподдержанное действие возвращает false из canHandle.

Шаг 4. Покажите кнопку после подготовки

На каждом экране, где нужен ассистент:

  1. Сразу скройте кнопку предыдущего экрана и передайте trackView(pageContext).
  2. Вызовите getContentBySelector("assistant-entry", pageContext).
  3. Прочитайте JSON точки входа. Если она включена, вызовите prepareAssistant("shopping-assistant", pageContext).
  4. Только после ready для текущего экрана покажите кнопку с entry.title.
  5. При нажатии вызовите openAssistant с видимой Activity или UIViewController.

PageContext должен описывать экран, с которого открывается чат: например, PRODUCT и SKU для карточки товара или CATEGORY и данные категории для каталога. Поля и примеры: PageContext Android, PageContext iOS, правила контекста API V2. Не меняйте регистр SKU, категорий и региона относительно фида.

prepareAssistant не заменяет trackView и не отправляет его повторно. Получение данных кампании само по себе не показывает кнопку: отрисовка точки входа остаётся в приложении.

Как прочитать настройку точки входа

Ответ getContentBySelector содержит выбранный контент по пути:

ContentResponse.data[]
  → campaign.payload[]
    → variation.contents[]
      → content.custom.json  // строка с JSON, которую нужно разобрать

Для точки входа используйте один выбранный контент своей кампании. Не объединяйте вариации разных кампаний. parseEntry в примере ниже — функция приложения: она разбирает эту строку и возвращает enabled и title; отсутствие или ошибка разбора означает, что кнопка не показывается. JSON второго selector приложение не разбирает — это делает prepareAssistant.

Полный порядок с защитой от смены экрана

Это псевдокод управления экраном. generation, задача экрана и видимость кнопки принадлежат приложению. В Kotlin используйте lifecycleScope/Job, в Swift — Task на MainActor. Поколение меняется до запроса точки входа, а не только перед подготовкой.

entrySelector = "assistant-entry"
assistantSelector = "shopping-assistant"

onScreenShown(pageContext):
    generation += 1
    cancel(previousScreenTask)
    myGeneration = generation
    hideEntryButton()
    sdk.trackView(pageContext)

    previousScreenTask = launch:
        entryResponse = await sdk.getContentBySelector(entrySelector, pageContext)
        if taskCancelled or myGeneration != generation: return
        entry = parseEntry(entryResponse) // custom.json; ошибка/нет данных -> disabled
        if not entry.enabled: return

        result = await sdk.prepareAssistant(assistantSelector, pageContext, timeoutMillis = 10_000)
        if taskCancelled or myGeneration != generation: return
        if result == ready: showEntryButton(entry.title)

onScreenHiddenOrIdentityChanged:
    generation += 1
    cancel(previousScreenTask)
    hideEntryButton()

onEntryTap:
    result = sdk.openAssistant(currentPresenter)
    if result == not_ready or result == invalid_presenter:
        hideEntryButton()

Любая ошибка обоих запросов оставляет кнопку скрытой. В Kotlin prepareAssistant возвращает Cancelled при отмене coroutine, а getContentBySelector пробрасывает CancellationException. Перед показом кнопки проверьте состояние задачи и актуальность экрана. В Swift для проверки отмены используйте Task.isCancelled. На Android передайте в openAssistant контекст видимой Activity. На iOS передайте готовый к презентации UIViewController или вызовите openAssistant(), чтобы SDK выбрал его сам.

Шаг 5. Проверьте первый запуск

Проверка Ожидаемый результат
Открыли тестовый экран, обе кампании опубликованы и включены. После успешной подготовки появилась кнопка с подписью из кампании.
Нажали кнопку. Открылся полноэкранный чат с заголовком, приветствием и подсказками.
Отправили вопрос о товаре. SDK показал ответ и передал подборку вашему builder.
Нажали на товар. Чат закрылся, handler открыл карточку в приложении один раз.
Закрыли и снова открыли чат. Переписка сохранилась в памяти приложения.
Выключили точку входа и опубликовали изменение. При следующем запросе точки входа кнопка не появилась.

Если кнопка или чат не появились

Симптом Что проверить
getContentBySelector не вернул контент Значения section и selector, публикацию кампании и Experience, таргетинг для текущего PageContext.
Контент есть, кнопки нет Разбор custom.json, enabled: true, результат prepareAssistant; не успел ли пользователь уйти с экрана.
unavailable Нет подходящей настройки ассистента либо она выключена. Проверьте вторую кампанию, а не только кнопку.
invalid_configuration Непустой ли selector, положителен ли timeoutMillis, корректен ли JSON конфигурации и нет ли нескольких разных конфигураций. На iOS проверьте инициализацию SDK.
network при подготовке Проверьте соединение и запрос выбора кампании /choose в диагностических логах SDK.
Чат открылся, но на сообщение пришла ошибка Проверьте запрос /shopping/generate в диагностических логах SDK и доступ секции к Shopping API из мобильной сети. В чате можно повторить отправку.
not_ready при открытии Кнопку показали раньше ready или подготовка уже устарела после смены экрана/пользователя.
Товары есть, перехода нет canHandle(OpenProduct) возвращает true, карточка передаёт tap с product.ref, обработчик действительно выполняет навигацию.

Для проверки запросов платформы используйте API-логи. Все результаты и ошибки разобраны в справочнике ниже.

Дополнительные сценарии перед выпуском

  • При отключённой или отсутствующей кампании кнопки нет; при медленной подготовке не появляется неработающая кнопка.
  • Быстрые переходы между страницами не показывают кнопку или подсказки предыдущей страницы.
  • Ошибка повторной подготовки не удаляет активный диалог; «Новый чат» не показывает старый стартовый экран.
  • Поворот, большие шрифты и пустые подборки не создают нулевую или бесконечную высоту блока.
  • Карточки за пределами горизонтального viewport не дают impression; перерисовки не создают дубли.
  • SKU без URL открывается; товар без обоих остаётся видимым без нажатия.
  • Товар и кнопка поддержки закрывают чат до перехода; быстрый двойной tap не открывает два экрана.
  • Чужая блокировка UI-кампаний сохраняется после закрытия ассистента.
  • После смены пользователя не видны старые сообщения, товары и поздние ответы.

Проверки для планируемого API авторизации:

  • В гостевом режиме повторные запросы используют одну сессию; после INVALID_GUEST_TOKEN новое сообщение уходит в новый диалог без старой переписки.
  • В клиентском режиме после 401 поставщик получает один вызов с forceRefresh = true; повторный отказ не запускает цикл запросов или гостевую регистрацию.

Методы SDK

Сигнатуры для регистрации компонентов, подготовки и управления экраном ассистента.

Методы вызываются у GravitySDK.instance. Асинхронная подготовка — suspend-метод; действия с UI выполняются в главном потоке.

suspend fun prepareAssistant(
    assistantSelector: String,
    pageContext: PageContext,
    timeoutMillis: Long = 10_000,
): AssistantPrepareResult

fun openAssistant(activityContext: Context): AssistantOpenResult
fun closeAssistant()
fun setAssistantProductBlockBuilder(builder: AssistantProductBlockBuilder)
fun setAssistantActionHandler(handler: AssistantActionHandler)
fun performAssistantProductAction(
    product: AssistantProductRef,
    action: AssistantProductAction,
): AssistantInteractionResult

Методы доступны у GravitySDK.instance. Подготовка использует Swift concurrency; UI API и обработчики работают на MainActor.

@MainActor
func prepareAssistant(
    assistantSelector: String,
    pageContext: PageContext,
    timeoutMillis: Int64 = 10_000
) async -> AssistantPrepareResult

@MainActor func openAssistant(viewController: UIViewController? = nil) -> AssistantOpenResult
@MainActor func closeAssistant()
@MainActor func setAssistantProductBlockBuilder(_ builder: AssistantProductBlockBuilder)
@MainActor func setAssistantActionHandler(_ handler: AssistantActionHandler)
@MainActor func performAssistantProductAction(
    product: AssistantProductRef,
    action: AssistantProductAction
) -> AssistantInteractionResult

Типы авторизации

В планируемом API способ доступа задаётся явно. До вызова setAssistantAuth подготовка возвращает invalid_configuration.

fun setAssistantAuth(auth: AssistantAuth)

sealed interface AssistantAuth {
    data object Guest : AssistantAuth
    data class Client(val provider: AssistantAuthProvider) : AssistantAuth
}

interface AssistantAuthProvider {
    suspend fun getAccessToken(forceRefresh: Boolean): String
}
@MainActor func setAssistantAuth(_ auth: AssistantAuth)

enum AssistantAuth {
    case guest
    case client(any AssistantAuthProvider)
}

protocol AssistantAuthProvider: Sendable {
    func getAccessToken(forceRefresh: Bool) async throws -> String
}

Поставщик не должен блокировать главный поток. При параллельных запросах SDK объединяет получение или принудительное обновление токена для текущей идентичности. Отмена подготовки или смена доступа отменяет ожидание; результат отменённого вызова не используется.

Товарный блок приложения

Builder получает целую подборку. SDK управляет вертикальной прокруткой чата; приложение рисует заголовок, карточки и горизонтальную прокрутку.

interface AssistantProductBlockBuilder {
    @Composable
    fun Build(block: AssistantProductBlock, layout: AssistantProductLayout)
}

data class AssistantProductLayout(
    val availableWidth: Dp,
    val isInteractionEnabled: Boolean,
)
@MainActor
protocol AssistantProductBlockBuilder {
    func build(block: AssistantProductBlock, layout: AssistantProductLayout) -> AnyView
}

struct AssistantProductLayout {
    let availableWidth: CGFloat
    let isInteractionEnabled: Bool
}

availableWidth — полезная ширина внутри чата после safe area и внутренних отступов, в dp на Android и points на iOS. Блок занимает ровно эту ширину и возвращает конечную измеряемую высоту по содержимому. Не используйте бесконечную высоту, fillMaxHeight, вертикальный ScrollView или GeometryReader как единственный источник высоты.

На Android корневому контейнеру задают Modifier.width(layout.availableWidth); Compose измеряет высоту содержимого. На iOS применяют .frame(width: layout.availableWidth) и .fixedSize(horizontal: false, vertical: true); SwiftUI сообщает высоту контейнеру SDK. При повороте, изменении размера окна, масштаба текста или загрузке изображения layout пересчитывается. Используйте соотношение сторон/placeholder для изображения, чтобы высота была определена ещё до загрузки. Для UIKit/Android View обёртка должна участвовать в нативном измерении высоты.

Модель данных

AssistantProductBlock Тип Значение
blockId String Уникальный ключ блока; не используйте только shelf_id как глобальный ключ.
title String? Заголовок подборки.
products [AssistantProduct] / List<AssistantProduct> Товары в порядке ответа. Пустой список допустим.
AssistantProduct Тип Значение
itemId String Уникальное появление товара в ответе. Одинаковый SKU в двух местах — разные itemId.
ref AssistantProductRef Непрозрачная ссылка SDK для событий. Не создавать самостоятельно и не сохранять между открытиями чата.
name String Название.
sku, url, imageUrl String? SKU, URL товара и изображения. url не является URL аналитики.
price Double? Цена без форматирования. Валюту определяет приложение.
brand, features String? Дополнительные сведения.
categoryId String? Значение category_id из Shopping API; не название и не путь категории.
isStm Bool? / Boolean? Признак СТМ.
canOpen Bool / Boolean Есть SKU или допустимый URL, зарегистрирован handler и его canHandle(OpenProduct(product)) возвращает true.

Поля товара, кроме itemId, ref, name и canOpen, могут отсутствовать. Не удаляйте товар из-за отсутствующей картинки, цены или категории. Показывайте placeholder и форматируйте цену по правилам магазина. Пустой блок показывает пустое состояние. События аналитики хранятся внутри SDK и не требуются builder.

Видимость и нажатия

Приложение вызывает публичный метод SDK; это не callback, который SDK вызывает в приложении:

GravitySDK.instance.performAssistantProductAction(
    product = product.ref,
    action = AssistantProductAction.VisibleImpression,
)
GravitySDK.instance.performAssistantProductAction(
    product = product.ref,
    action = AssistantProductAction.Tap,
)
GravitySDK.instance.performAssistantProductAction(product: product.ref, action: .visibleImpression)
GravitySDK.instance.performAssistantProductAction(product: product.ref, action: .tap)

AssistantProductAction имеет только visibleImpression и tap. AssistantInteractionResult: accepted, duplicate, stale_reference, not_actionable. На Kotlin это VisibleImpression, Tap, Accepted, Duplicate, StaleReference, NotActionable; в Swift — одноимённые case в lowerCamelCase.

  • Отправляйте visibleImpression, когда не менее 50% площади карточки видно непрерывно одну секунду одновременно внутри карусели, видимой области чата и окна приложения. Фоновое приложение и закрытый чат не считаются видимостью. При потере видимости таймер сбрасывают.
  • Отправляйте tap один раз на физическое нажатие, только при layout.isInteractionEnabled && product.canOpen.
  • Builder обязан применить это условие к кликам и accessibility actions. SDK не может изменить обработчики произвольной host view. SDK дополнительно отклоняет недопустимое действие на своей границе.
  • Повторное создание view не создаёт новые показы: SDK принимает один visibleImpression для одного появления товара за одно открытие чата. При новом открытии выдаются новые ref.
  • Старые ссылки после закрытия, нового чата или смены идентичности возвращают stale_reference без tracking и навигации. Повторный tap в уже начатом переходе возвращает duplicate.

Действия и навигация

Единый AssistantActionHandler обслуживает и товары, и действия ответа: например, open_support_chat. Зарегистрируйте его до подготовки, чтобы приложение могло обработать переходы.

interface AssistantActionHandler {
    fun canHandle(action: AssistantAction): Boolean
    fun handle(action: AssistantAction)
}

sealed interface AssistantAction {
    data class OpenProduct(val product: AssistantProduct) : AssistantAction
    data class OpenSupportChat(val payload: Map<String, Any?>) : AssistantAction
    data class FollowUrl(val url: String) : AssistantAction
    data class Custom(val type: String, val payload: Map<String, Any?>) : AssistantAction
}
@MainActor
protocol AssistantActionHandler {
    func canHandle(_ action: AssistantAction) -> Bool
    func handle(_ action: AssistantAction)
}

enum AssistantAction {
    case openProduct(AssistantProduct)
    case openSupportChat(payload: [String: JSONValue])
    case followUrl(URL)
    case custom(type: String, payload: [String: JSONValue])
}

payload содержит исходный объект серверной кнопки (type, value, action и прочие полученные поля) без переименования ключей; отдельного серверного поля payload не требуется. На Android значения представлены как Any?, на iOS — как JSONValue. Серверное action: "follow_url" с корректным HTTP(S) URL преобразуется в FollowUrl/.followUrl; open_support_chat — в OpenSupportChat/.openSupportChat. canHandle синхронен, не выполняет сеть и не запускает навигацию. Для неизвестного типа возвращайте false; SDK оставляет такое действие недоступным и фиксирует диагностику, не ломая весь ответ.

Для товара SDK проверяет действие, ставит click tracking на отправку, закрывает чат и после завершения закрытия вызывает handle. Для open_support_chat, follow_url и поддержанных custom-действий порядок закрытия и вызова такой же. Сам переход — ответственность приложения. При обработке tap не выполняйте второй переход напрямую из builder и не отправляйте отдельный sendProductEngagement.

В handle откройте карточку по SKU либо URL, чат поддержки либо другой экран приложения. Обработчик выполняется один раз для принятого нажатия. Асинхронная аналитика не задерживает навигацию. Если приложение не может завершить переход после передачи управления, оно показывает собственную ошибку навигации.

Подготовка, контекст и диалог

Подготовка и диалог — независимые состояния. Подготовка бывает idle, preparing, ready, unavailable или failed. Диалог бывает empty, active или sending. Подготовка никогда не отправляет скрытое сообщение от имени пользователя.

Каждая новая подготовка сразу делает предыдущий стартовый экран недействительным. Даже при равных аргументах действует последний вызов. Поздний ответ, отмена или timeout старого запроса не меняют результат нового.

Событие Поведение
Первое открытие после ready Приветствие и подсказки актуальной подготовки.
Успешная повторная подготовка того же ассистента Обновляет данные для следующего нового чата. Уже начатый диалог сохраняется.
Подготовка не завершена или закончилась ошибкой Старый стартовый экран не используется. Уже открытый активный диалог сохраняется; новый чат недоступен.
Новый экран приложения trackView инвалидирует стартовую подготовку при изменении контекста. Приложение скрывает кнопку и повторяет выбор точки входа и подготовку.
Закрытие чата Закрывает только UI; сообщения и черновик сохраняются в памяти.
Повторное открытие Показывает активный диалог; если диалога нет, требует актуальный ready.
«Новый чат» при ready Атомарно прекращает ожидание старого ответа в UI, создаёт новый ID диалога, очищает сообщения и показывает актуальный стартовый экран.
«Новый чат» во время подготовки или после её ошибки Кнопка недоступна. SDK показывает статус подготовки/ошибку с повтором; старый диалог не удаляется.
Смена пользователя, сессии или раздела SDK Закрывает чат, очищает диалог и подготовку, отменяет запросы и инвалидирует ссылки на товары.
Вызов setAssistantAuth Сбрасывает подготовку и диалог; для открытия требуется новая подготовка. Токен другой идентичности не используется.
Обновление клиентского токена через поставщик Сохраняет диалог того же пользователя; при 401 допускается один повтор с новым токеном.
Истечение гостевого токена Новая гостевая сессия и новый диалог по правилам гостевого доступа.
Другой assistantSelector или tenant Предыдущий диалог не переносится в другого ассистента. Для него нужна новая успешная подготовка.
Перезапуск приложения Новый диалог. Автоматического восстановления предыдущего чата нет.

Для кнопки приложения достаточно результата подготовки; отдельный hasAssistantActiveDialog не нужен. При каждой новой странице кнопку показывают после ready, даже если в памяти есть диалог. Уже открытый чат при этом не закрывается из-за обычной ошибки подготовки.

Контекст активного диалога фиксируется при его старте. Переход на другую страницу не переписывает контекст незавершённого запроса. Новый контекст применяется к следующему новому чату. Значения SKU, категорий и региона передаются без изменения регистра, согласно PageContext Android и PageContext iOS.

SDK не допускает параллельной отправки двух сообщений в одном диалоге и блокирует повторное нажатие отправки. Во время запроса виден индикатор. Таймаут запроса ответа — 120 секунд, независимо от timeoutMillis подготовки. При ошибке текст остаётся в переписке. По нажатию кнопки повтора SDK отправляет тот же текст с прежним threadId. Запрос не содержит messages[].id, поэтому при потере ответа после сохранения сообщения на сервере повтор может создать второе сообщение.

В планируемой обработке повтора SDK проверит историю диалога после обрыва связи и повторно использует ID сообщения и исходный запрос. Для генерации предусмотрен message_conflict при HTTP 409 MESSAGE_ID_CONFLICT, для истории — history_unavailable при HTTP 404 SHOPPING_HISTORY_NOT_FOUND. Для отправки оценки предусмотрен assistantMessageId из генерации или id сообщения ассистента из истории.

Закрытие UI не отменяет уже отправленное сообщение: успешный ответ продолжает обрабатываться в текущем диалоге. «Новый чат», смена идентичности и смена ассистента инвалидируют старые ответы; они не попадают в новый диалог. Уже отправленный запрос может завершиться и сохраниться в старом серверном диалоге.

Результаты и ошибки

Имена результатов ниже записаны в общем формате. В Kotlin используются Ready, Unavailable(reason), Failure(error), Cancelled, Superseded; в Swift — .ready, .unavailable(reason), .failure(error), .cancelled, .superseded. Результаты подготовки и их вложенные типы сравнимы по значению (Equatable в Swift).

Результат подготовки Значение
ready Для последнего контекста загружена конфигурация стартового экрана и определён user.uid.
unavailable(no_matching_configuration) Выбор кампании успешно завершён, подходящего контента нет. Это может быть отсутствие кампании, условия таргетинга или непустой selector, который ни с чем не совпал. SDK не угадывает конкретную причину.
unavailable(disabled) Выбранная конфигурация ассистента явно отключена.
failure(error) Не удалось получить или проверить конфигурацию; подробности в AssistantError.
cancelled Подготовка отменена экраном приложения или сменой идентичности. Android возвращает Cancelled из prepareAssistant при перехвате CancellationException.
superseded Подготовку заменил более поздний вызов; её ответ не меняет состояние.

AssistantError содержит code, диагностическое message и необязательный httpStatus. В текущих результатах prepareAssistant SDK оставляет httpStatus пустым. Диагностический текст предназначен для логов приложения.

code при подготовке Условие Действие приложения
invalid_configuration Пустой selector, неположительный timeoutMillis, невалидный JSON, отсутствует поле enabled или выбрано несколько разных конфигураций. На iOS этот код также возвращается до инициализации SDK. Исправить интеграцию или кампанию.
network SDK не получил пригодный для подготовки ответ на /choose. Сюда попадают сетевые сбои и ошибки запроса или разбора ответа. Проверить соединение и диагностические логи запроса /choose.
timeout Выбор кампании по /choose не завершился за timeoutMillis. Оставить кнопку скрытой и повторить подготовку явно.
invalid_response Получена включённая конфигурация, но SDK не смог определить user.uid. Проверить идентификацию пользователя и ответ /choose.

Если /choose успешно вернул ответ без конфигурации для указанного selector, подготовка возвращает unavailable(no_matching_configuration). Доступ к Shopping API проверяется при отправке сообщения.

При сбое генерации SDK показывает сообщение «Не удалось получить ответ, попробуйте ещё раз» с кнопкой повтора. Для диагностики SDK сопоставляет HTTP 401 и 403 с unauthorized, HTTP 429 с rate_limited, HTTP 5xx с server, остальные HTTP 4xx с invalid_response. Эти коды используются в логах генерации. Результат prepareAssistant относится только к подготовке.

AssistantOpenResult принимает значения opened, already_open, not_ready и invalid_presenter. Повторное открытие не создаёт второй экран. На Android invalid_presenter означает, что SDK не нашёл подходящую Activity или её корневое представление. На iOS SDK проверяет инициализацию, наличие активного UIViewController и отсутствие уже открытого им модального экрана.

Аналитика

События жизненного цикла SDK отправляет через обычный канал custom events Gravity Field. Приложение не дублирует их:

Событие Когда SDK отправляет
chat_dialog_open После завершения каждого открытия UI.
assistant_message_sent Один раз при принятии нового пользовательского сообщения; сетевой повтор с тем же ID не является новым сообщением.
assistant_response_received При первом отображении полученного ответа, включая отображение после повторного открытия.
assistant_product_selection_received Вместе с первым отображением ответа, если в нём есть хотя бы один непустой товарный блок.
chat_error При показе ошибки отправки, истории или подготовки в открытом чате. Отменённые и вытесненные запросы не считаются ошибками.
chat_dialog_close После закрытия UI, включая переход через handler.
chat_dialog_end При явном «Новом чате» или сбросе идентичности/ассистента. Простое закрытие не завершает диалог.

События содержат идентификаторы диалога, сообщения и кампании, где применимо, без текста переписки. SDK сохраняет привязку события к исходному пользователю; событие старого диалога не отправляется от имени нового аккаунта. Завершение процесса не гарантирует доставку chat_dialog_close или chat_dialog_end.

SDK использует события click и visible_impression из product.events ответа Shopping API. Для каждого принятого действия он отправляет все допустимые URL соответствующего типа; одинаковые URL внутри одного действия отправляются один раз. Отсутствие событий не блокирует отображение товара и навигацию, но аналитика этого действия через данный механизм отсутствует.

Приложение не вызывает tracking URL, не создаёт их из SKU и не отправляет одновременно обычный sendProductEngagement. События товаров ассистента и engagement обычных кампаний — разные механизмы. События уровня ответа не подменяют показы конкретных карточек. SDK обрабатывает поддержанные события ответа отдельно при соответствующем событии жизненного цикла ответа.

Очередь уже принятых кликов не отменяется закрытием чата; событие сохраняет исходные товар и идентичность. SDK не обещает доставку после завершения процесса приложения или exactly-once доставку по сети.

Кнопки open_support_chat и follow_url сами по себе не содержат товарных tracking URL. Вызов action handler не означает отправку product click и не подменяет аналитику приложения для этих действий.

Другие UI-кампании

На время презентации и показа ассистента SDK блокирует автоматические modal/in-app показы и переходы шагов таких кампаний. Блокировка устанавливается до открытия и снимается после полного закрытия, включая системный Back и swipe-dismiss.

Ассистент снимает только собственную блокировку. Если приложение уже вызвало lockPresentation, закрытие чата не отменяет блокировку приложения. Ошибка открытия и уничтожение экрана также освобождают только блокировку ассистента.

Получение кампаний и отправка событий продолжаются. Подавленные кампании автоматически после закрытия чата не воспроизводятся; следующие показы определяются последующими обычными событиями приложения. Inline-контент на экранах приложения не становится модальным и не блокируется этим правилом.

Подключение к Shopping API

SDK использует https://shopping-assistant-api.gravityfield.ai. runtimeContext.tenant_id равен section, указанному при инициализации Gravity SDK. Этот раздел должен быть подключён к Shopping Assistant; selector выбирает сценарий внутри раздела и не переключает tenant. resourceId и runtimeContext.uid — канонический user.uid Gravity Field, полученный базовым SDK. Собственный ID из setUser не подставляется вместо него напрямую.

Для подготовки SDK запрашивает конфигурацию в пределах timeoutMillis и определяет user.uid из ответа или данных базового SDK. Если uid недоступен, подготовка возвращает invalid_response. threadId — отдельный UUID чата, а не user.ses.

Выбор кампании идёт через Gravity API V2 с ключом базового SDK. Текущая реализация отправляет POST /shopping/generate с Content-Type: application/json без заголовка Authorization. На стороне сервиса раздел должен допускать обращения из мобильной сети. В планируемом API авторизации запросы генерации, истории и PUT-оценок будут передавать Authorization: Bearer <accessToken>.

Подробный транспортный контракт: интеграция Shopping Assistant по API. Приложение не вызывает эти запросы параллельно с SDK.

Связанные разделы

API кампании
/personalization/campaigns/api_campaigns/
Таргетинг
/personalization/campaigns/targeting_schedule/
Проверка ответов
/shopping_assistant/personal_account/preview/
Трекинг событий
/shopping_assistant/integrations/tracking/
Обзор API
/shopping_assistant/api/overview/