umbot
    Preparing search index...

    Class SmartAppAdapter

    Адаптер, обеспечивающий полную поддержку Сбер SmartApp (голосовой ассистент Салют). Позволяет разрабатывать навыки для SmartApp на TypeScript с использованием всего функционала платформы: от обработки голосовых запросов до работы с карточками и кнопками.

    Этот адаптер автоматически обрабатывает входящие вебхуки от SmartApp, преобразует их в унифицированный формат фреймворка и формирует ответ, совместимый с требованиями платформы. Подключается одной строкой и не мешает работе других адаптеров (например, для Telegram или VK).

    Поддерживает:

    • голосовые и текстовые запросы;
    • карточки и кнопки; звуки/TTS-эффекты не встраиваются (маркеры звуков вычищаются);

    === Локальное хранилище === Адаптер использует внешнее SmartApp Code API для хранения данных пользователя. По умолчанию URL хранилища: https://smartapp-code.sberdevices.ru/tools/api/data. URL можно переопределить через конфиг:

    appConfig.tokens.smart_app.storage_url = 'https://your-custom-storage-url';
    

    Подключается как любой другой адаптер: bot.use(new SmartAppAdapter()). Несколько адаптеров могут работать одновременно — система сама выберет подходящий на основе заголовков и структуры входящего запроса.

    Токен конструктора адаптеру не требуется: аутентификация навыка происходит через экосистему Сбера, а данные хранилища читаются из appConfig.tokens.smart_app (см. блок про локальное хранилище выше).

    // Простейший навык, который отвечает на приветствие
    import { Bot } from 'umbot';
    import { SmartAppAdapter } from 'umbot/plugins';

    const bot = new Bot()
    .use(new SmartAppAdapter())
    .addCommand('start', ['привет'], (_text, ctx) => {
    ctx.text = 'Привет! Я твой первый навык для SmartApp';
    });

    bot.start('localhost', 3000);
    • Bot
    • BotController
    • BasePlatform

    Hierarchy (View Summary)

    Index
    • Конструктор базового адаптера платформы.

      Parameters

      • OptionalplatformToken: string

        Токен платформы (опционально)

      • OptionaladditionalPlatformOptions: IAdapterOptions

        Дополнительные опции платформы (опционально)

      Returns SmartAppAdapter

    • Protected

      Получает данные пользователя из хранилища

      Parameters

      Returns Promise<unknown>

      Данные пользователя либо пустой объект при ошибке (ошибка логируется)

    • Protected

      Инициализирует TTS (Text-to-Speech) в контроллере. Обрабатывает звуки и стандартные звуковые эффекты

      Parameters

      • controller: BotController

        Контроллер приложения

      Returns void | Promise<void>

    • Сохраняет данные пользователя в хранилище

      Parameters

      • data: unknown

        Данные для сохранения

      • controller: BotController

        Контроллер приложения

      Returns Promise<IRequestSend<unknown>>

      Результат HTTP-запроса к внешнему хранилищу

    • При превышении допустимого времени обработки запроса логирует информацию. Вызывается вручную в конце getContent() голосовых адаптеров (Alisa, Marusia, SmartApp); адаптеры чат-платформ его не вызывают.

      • >= WARNING_TIME_REQUEST (по умолчанию 2000 мс) — warning в лог.
      • >= MAX_TIME_REQUEST (по умолчанию 2900 мс) — текст ошибки пишется в controller.platformOptions.error (не в лог).

      Пороги вынесены в protected поля — при необходимости переопределите в потомке.

      Parameters

      Returns void

    • Отмечает в контроллере, что платформа отклонила отправку: тогда send вернёт false. Вызывается в getContent с результатом запроса отправки; тело ответа на вебхук не меняется.

      Parameters

      • controller: BotController

        Контроллер ответа

      • result: unknown

        Результат запроса к API (null/false — ошибка)

      Returns void

      this.checkSendResult(controller, await myApi.sendMessage(chatId, controller.text));
      return 'ok';
    • Учитывает дополнительные вызовы API платформы в лимите отправки (sendLimit), не ожидая очереди.

      Один send — не всегда один вызов API: например, отправка карточки VK с незакэшированной картинкой — это ещё и загрузка (photos.getMessagesUploadServer, photos.saveMessagesPhoto), а методами платформы делится общий лимит запросов/с. Вызывайте перед вспомогательными API-вызовами своей отправки (из getContent адаптера или обработчика карточек) — очередь рассылки разредится, и платформа не ответит ошибкой «Too many requests».

      Parameters

      • count: number

        Сколько дополнительных вызовов API сейчас будет сделано

      Returns void

      // Адаптер с загрузкой медиа: две подготовки + сама отправка
      // (отправку send() учтёт сам)
      this.consumeSendLimit(2);
      const upload = await myApi.uploadPhoto(controller, path);
    • Создаёт API-фасад платформы для controller.api — унифицированный доступ к исходящим возможностям платформы (sendPhoto, answerCallback и т.д.).

      Базовая реализация возвращает null: фасад считается недоступным. Ядро подключает фасад к контроллеру только у адаптеров, переопределивших этот метод, — поэтому добавить фасад своей платформе можно без правок ядра.

      Для кастомных платформ: если платформа умеет исходящие API-вызовы (отправка медиа, ответ на callback-кнопку), переопределите метод и верните свой фасад IControllerApi. Удобно завернуть готовую фабрику и дополнить её, либо собрать фасад с нуля. Для голосовых платформ (ответ формируется телом webhook) переопределять не нужно.

      Parameters

      • _controller: BotController

        Контроллер текущего запроса (не используется базовой реализацией; доступен переопределяющим методам)

      Returns IControllerApi | null

      Фасад либо null, если для платформы он недоступен

      class MyPlatformAdapter extends BasePlatform {
      createApi(controller: BotController): IControllerApi | null {
      return makeMyApi(controller); // своя фабрика фасада
      }
      }
    • Метод, который вызывается при уничтожении плагина. В данном методе можно добавить отписку, либо выполнить другие действия.

      Parameters

      • _bot: Bot

        Основной класс приложения

      Returns void | Promise<void>

    • Формирует итоговый webhook-ответ SmartApp (ANSWER_TO_USER): текст, TTS/SSML, карточки, кнопки и команду закрытия приложения. Синхронный метод — возвращает готовый объект без промиса.

      Parameters

      • controller: BotController

        Контроллер приложения

      Returns ISberSmartAppWebhookResponse

      Готовый ответ для webhook SmartApp

    • Получает данные из локального хранилища.

      Type Parameters

      • TStorageResult = unknown

      Parameters

      • controller: BotController

        Контроллер приложения

      Returns Promise<TStorageResult>

      Данные пользователя либо пустой объект {}; ошибки логируются через logError

    • Получает время выполнения запроса в миллисекундах

      Parameters

      Returns number

      Время выполнения запроса

    • Формирует пример webhook-запроса SmartApp (MESSAGE_TO_SKILL) для локального тестирования (BotTest).

      Parameters

      • query: string

        Текст команды пользователя

      • userId: string

        Идентификатор пользователя (uuid.userId)

      • count: number

        Номер сообщения (messageId; 0 — новая сессия)

      Returns Record<string, unknown>

      Заготовка запроса в формате webhook SmartApp

    • Срок ответа SmartApp: после него смартап считается не ответившим.

      Returns number

      MAX_TIME_REQUEST, мс

    • Инициализация адаптера. Определять не обязательно. Стоит указывать в случаях, когда нужно выполнить доп логику, например указать токены или писать какую-то статистику по использованию.

      Parameters

      Returns void

    • Проверяет запрос при заданной опции smartapp_application_id: payload.app_info.applicationId должен совпадать с ожидаемым. Отсекает чужой трафик на ваш URL (другой смартап, чужой сценарий). Это НЕ подпись: SmartApp не подписывает вебхуки, весь payload контролирует отправитель, поэтому от целевой подделки (атакующий знает и адрес, и applicationId) опция не защищает — для этого нужна сетевая изоляция.

      Parameters

      • query: string | ISberSmartAppWebhookRequest

        Входящий webhook-запрос (сырое тело строкой или объект)

      • Optional_headers: Record<string, unknown>

        Заголовки HTTP-запроса (не используются)

      • OptionalparsedQuery: unknown

        Тело, разобранное из JSON фреймворком

      Returns boolean

      true, если проверка не включена или applicationId совпал

    • SmartApp всегда имеет внешнее хранилище, поэтому возвращает true.

      Returns boolean

    • Проверяет, что входящий webhook-запрос принадлежит SmartApp. Опознаёт запрос по заголовкам x-sber-smartapp-webhook-token/x-sber-token либо по связке полей messageName + uuid + payload.character + payload.app_info.

      Parameters

      • query: ISberSmartAppWebhookRequest

        Входящий webhook-запрос

      • Optionalheaders: Record<string, unknown>

        Заголовки HTTP-запроса

      Returns boolean

      true, если запрос относится к платформе SmartApp

    • Проверка подписи включена, когда выполнены оба условия базовой HMAC-схемы: задан секрет платформы и имя заголовка подписи. Платформы, переопределившие isCorrectQuery (Telegram, VK, MAX), переопределяют и этот метод — источник секрета у них другой (webhookSecret / secret_key).

      Используется ядром при старте для предупреждения о вебхуке без защиты.

      Returns boolean

    • Умеет ли платформа подписывать вебхук. По умолчанию — да, если задан signatureName (подпись в заголовке) или переопределён isSignatureCheckEnabled (подпись в теле, как у VK). Ядро по этому признаку решает, предупреждать ли при старте о вебхуке без проверки подписи.

      Returns boolean

      true, если у платформы есть механизм подписи вебхука

      class MyAdapter extends BasePlatform {
      // Платформа подписывает запрос полем в теле, заголовка нет
      isSignatureSupported(): boolean {
      return true;
      }
      }
    • SmartApp не поддерживает push-сообщения, поэтому всегда возвращает false.

      Returns boolean

    • Сохраняет данные пользователя во внешнее хранилище SmartApp.

      Parameters

      • data: unknown

        Данные для сохранения

      • controller: BotController

        Контроллер приложения

      Returns Promise<void>

    • Разбирает запрос SmartApp и наполняет контроллер данными: команда, NLU, персонаж, сессия, метаданные и данные экрана устройства.

      Parameters

      Returns boolean

      true, если запрос успешно разобран

    • Дополнительная обработка для звуков. В данном методе стоит реализовать логику, с помощью которой будут наложены дополнительные эффекты для озвучивания текста пользователю

      Parameters

      Returns void | Promise<void>

    • Публичная точка входа для сброса времени начала обработки запроса. Вызывайте перед началом бизнес-логики, чтобы метрики (см. getProcessingTime) считались отсюда.

      Parameters

      Returns void

    • Метод-флаг: указывает, что платформа голосовая (например, Алиса, Маруся).

      Returns boolean

    _knownPlatformOptions: readonly string[] = ...

    Известные опции адаптера. smartapp_application_id — ожидаемый payload.app_info.applicationId вебхука: при заданной опции запросы с другим идентификатором приложения отклоняются (см. isCorrectQuery). Остальные ключи дают предупреждение (см. BasePlatform).

    _platformOptions?: IAdapterOptions

    Опции из второго аргумента конструктора (new TelegramAdapter(token, { telegram_parse_mode })).

    _token?: string

    Токен из конструктора адаптера (new MyAdapter(token)). Во время работы берите токен из appContext.appConfig.tokens: туда он попадает при bot.use() и может быть перезаписан из .env.

    appContext?: AppContext<unknown, string | ISberSmartAppWebhookRequest>

    Контекст приложения

    isVoice: boolean = true

    Голосовая ли платформа (TTS-ответ в теле HTTP). Чат-платформы переопределяют на false.

    limit: number | null = null

    Лимит запросов/сек для входящего rateLimiter; null — не ограничивать. Переопределяется адаптером платформы.

    MAX_TIME_REQUEST: number = 2900

    Максимальное время обработки запроса в миллисекундах: при его превышении в лог записывается ошибка (ответ платформе при этом не модифицируется)

    platformName: string = T_SMART_APP

    Идентификатор платформы Сбер SmartApp.

    sendLimit: number | null = null

    Сколько сообщений в секунду отправляет send (рассылки, bot.broadcast); null — без ограничения. Ответы на входящие запросы не ограничиваются. Переопределяется адаптером по лимиту платформы и опцией адаптера send_rate_limit.

    signatureName?: string

    Имя поля в заголовке запроса, по которому можно проверить корректность полученного запроса от платформы.

    supportedEvents: readonly TEventType[] = ...

    Универсальные события SmartApp (для валидации addEvent).

    WARNING_TIME_REQUEST: number = 2000

    Порог предупреждения в миллисекундах: при его превышении в лог записывается warning