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 (см. блок про локальное хранилище выше).

Example

// Простейший навык, который отвечает на приветствие
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);

See

Bot
BotController
BasePlatform

Hierarchy (View Summary)

BasePlatformAdapter<string | ISberSmartAppWebhookRequest>
- SmartAppAdapter

Constructors

constructor

new SmartAppAdapter(
platformToken?: string,
additionalPlatformOptions?: IAdapterOptions,
): SmartAppAdapter
Конструктор базового адаптера платформы.
Parameters
- OptionalplatformToken: string
  Токен платформы (опционально)
- OptionaladditionalPlatformOptions: IAdapterOptions
  Дополнительные опции платформы (опционально)
Returns SmartAppAdapter
Inherited from BasePlatformAdapter.constructor
- Defined in plugins/platforms/Base/Base.ts:124

Properties

`Protected` `Optional`_platformOptions

_platformOptions?: IAdapterOptions

`Protected` `Optional`_token

_token?: string

`Optional`appContext

appContext?: AppContext<unknown, string | ISberSmartAppWebhookRequest>

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

isVoice

isVoice: boolean = true

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

limit

limit: number | null = null

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

`Protected`MAX_TIME_REQUEST

MAX_TIME_REQUEST: number = 2900

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

platformName

platformName: string = T_SMART_APP

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

`Optional`signatureName

signatureName?: string

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

supportedEvents

supportedEvents: readonly TEventType[] = ...

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

`Protected`WARNING_TIME_REQUEST

WARNING_TIME_REQUEST: number = 2000

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

Methods

`Protected`_getUserData

_getUserData(controller: BotController): Promise<unknown>
Protected
Получает данные пользователя из хранилища
Parameters
- controller: BotController
Returns Promise<unknown>
Данные пользователя либо пустой объект при ошибке (ошибка логируется)
- Defined in plugins/platforms/SmartApp/Adapter.ts:424

`Protected`_initTTS

_initTTS(controller: BotController): void | Promise<void>
Protected
Инициализирует TTS (Text-to-Speech) в контроллере. Обрабатывает звуки и стандартные звуковые эффекты
Parameters
- controller: BotController
  Контроллер приложения
Returns void | Promise<void>
Inherited from BasePlatformAdapter._initTTS
- Defined in plugins/platforms/Base/Base.ts:466

`Protected`_setUserData

_setUserData(
data: unknown,
controller: BotController,
): Promise<IRequestSend<unknown>>
Сохраняет данные пользователя в хранилище
Parameters
- data: unknown
  Данные для сохранения
- controller: BotController
  Контроллер приложения
Returns Promise<IRequestSend<unknown>>
Результат HTTP-запроса к внешнему хранилищу
- Defined in plugins/platforms/SmartApp/Adapter.ts:446

`Protected`_timeLimitLog

_timeLimitLog(controller: BotController): void
При превышении допустимого времени обработки запроса логирует информацию. Вызывается вручную в конце getContent() голосовых адаптеров (Alisa, Marusia, SmartApp); адаптеры чат-платформ его не вызывают.
- >= WARNING_TIME_REQUEST (по умолчанию 2000 мс) — warning в лог.
- >= MAX_TIME_REQUEST (по умолчанию 2900 мс) — текст ошибки пишется в controller.platformOptions.error (не в лог).
Пороги вынесены в protected поля — при необходимости переопределите в потомке.
Parameters
- controller: BotController
Returns void
Inherited from BasePlatformAdapter._timeLimitLog
- Defined in plugins/platforms/Base/Base.ts:440

createApi

createApi(_controller: BotController): IControllerApi | null
Создаёт API-фасад платформы для controller.api — унифицированный доступ к исходящим возможностям платформы (sendPhoto, answerCallback и т.д.).

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

Для кастомных платформ: если платформа умеет исходящие API-вызовы (отправка медиа, ответ на callback-кнопку), переопределите метод и верните свой фасад IControllerApi. Удобно завернуть готовую фабрику и дополнить её, либо собрать фасад с нуля. Для голосовых платформ (ответ формируется телом webhook) переопределять не нужно.
Parameters
- _controller: BotController
  Контроллер текущего запроса (не используется базовой реализацией; доступен переопределяющим методам)
Returns IControllerApi | null
Фасад либо null, если для платформы он недоступен
Example
```
class MyPlatformAdapter extends BasePlatform {
    createApi(controller: BotController): IControllerApi | null {
        return makeMyApi(controller); // своя фабрика фасада
    }
}
```
Inherited from BasePlatformAdapter.createApi
- Defined in plugins/platforms/Base/Base.ts:202

destroy

destroy(_bot: Bot): void | Promise<void>
Метод, который вызывается при уничтожении плагина. В данном методе можно добавить отписку, либо выполнить другие действия.
Parameters
- _bot: Bot
  Основной класс приложения
Returns void | Promise<void>
Inherited from BasePlatformAdapter.destroy
- Defined in plugins/Base.ts:21

getContent

getContent(controller: BotController): ISberSmartAppWebhookResponse
Формирует итоговый webhook-ответ SmartApp (ANSWER_TO_USER): текст, TTS/SSML, карточки, кнопки и команду закрытия приложения. Синхронный метод — возвращает готовый объект без промиса.
Parameters
- controller: BotController
  Контроллер приложения
Returns ISberSmartAppWebhookResponse
Готовый ответ для webhook SmartApp
Overrides BasePlatformAdapter.getContent
- Defined in plugins/platforms/SmartApp/Adapter.ts:366

getLocalStorage

getLocalStorage<TStorageResult = unknown>(
controller: BotController,
): Promise<TStorageResult>
Получает данные из локального хранилища.
Type Parameters
- TStorageResult = unknown
Parameters
- controller: BotController
  Контроллер приложения
Returns Promise<TStorageResult>
Данные пользователя либо пустой объект {}; ошибки логируются через logError
Overrides BasePlatformAdapter.getLocalStorage
- Defined in plugins/platforms/SmartApp/Adapter.ts:480

getProcessingTime

getProcessingTime(controller: BotController): number
Получает время выполнения запроса в миллисекундах
Parameters
- controller: BotController
Returns number
Время выполнения запроса
Inherited from BasePlatformAdapter.getProcessingTime
- Defined in plugins/platforms/Base/Base.ts:426

getQueryExample

getQueryExample(
    query: string,
    userId: string,
    count: number,
): Record<string, unknown>
Формирует пример webhook-запроса SmartApp (MESSAGE_TO_SKILL) для локального тестирования (BotTest).
Parameters
- query: string
  Текст команды пользователя
- userId: string
  Идентификатор пользователя (uuid.userId)
- count: number
  Номер сообщения (messageId; 0 — новая сессия)
Returns Record<string, unknown>
Заготовка запроса в формате webhook SmartApp
Overrides BasePlatformAdapter.getQueryExample
- Defined in plugins/platforms/SmartApp/Adapter.ts:508

getRatingContext

getRatingContext(controller: BotController): ISberSmartAppWebhookResponse
Формирует ответ с оценкой навыка
Parameters
- controller: BotController
  Контроллер приложения
Returns ISberSmartAppWebhookResponse
Объект ответа для вебхука
Overrides BasePlatformAdapter.getRatingContext
- Defined in plugins/platforms/SmartApp/Adapter.ts:391

init

init(
    appContext: AppContext<
        IDatabaseInfo,
        string
        | ISberSmartAppWebhookRequest,
    >,
): void
Инициализация адаптера. Определять не обязательно. Стоит указывать в случаях, когда нужно выполнить доп логику, например указать токены или писать какую-то статистику по использованию.
Parameters
- appContext: AppContext<IDatabaseInfo, string | ISberSmartAppWebhookRequest>
  Контекст приложения
Returns void
Inherited from BasePlatformAdapter.init
- Defined in plugins/platforms/Base/Base.ts:169

isCorrectQuery

isCorrectQuery(
query: string | ISberSmartAppWebhookRequest,
headers?: Record<string, unknown>,
): boolean
Проверяет полученный запрос от платформы на корректность. Из коробки проверка идет по sha256-hmac и включается только если одновременно заданы:
- appConfig.tokens[<platformName>].token — секретный ключ
- this.signatureName — имя http-заголовка с подписью
Если хотя бы один из этих параметров не задан, метод вернёт true без проверки — это opt-in механизм.

⚠️ Важно: не все платформы используют HMAC-SHA256 от тела. Переопределите этот метод в адаптере платформы, если её формат подписи отличается:
- Telegram — переопределён (использует plain x-telegram-bot-api-secret-token).
- Viber — умолчание корректно (Viber шлёт x-viber-content-signature как HMAC-SHA256(auth_token, body)).
- VK — переопределён: сверяет поле secret из тела запроса с secret_key из конфигурации (plain-сравнение через timingSafeEqual, без HMAC).
- Max — переопределён: сверяет заголовок x-max-bot-api-secret со значением webhook-secret (options.secret / tokens.max_app.webhookSecret).
- Для платформ без подписи (Alisa, Marusia, SmartApp) проверка пропускается из-за отсутствия signatureName.
Parameters
- query: string | ISberSmartAppWebhookRequest
  Объект запроса от платформы
- Optionalheaders: Record<string, unknown>
  HTTP-заголовки запроса
Returns boolean
true — запрос валиден / проверка не включена, false — подпись не сошлась или отсутствует.
Inherited from BasePlatformAdapter.isCorrectQuery
- Defined in plugins/platforms/Base/Base.ts:286

isLocalStorage

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

Returns boolean
Overrides BasePlatformAdapter.isLocalStorage
- Defined in plugins/platforms/SmartApp/Adapter.ts:489

isPlatformOnQuery

isPlatformOnQuery(
query: ISberSmartAppWebhookRequest,
headers?: Record<string, unknown>,
): 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
Overrides BasePlatformAdapter.isPlatformOnQuery
- Defined in plugins/platforms/SmartApp/Adapter.ts:83

isSignatureCheckEnabled

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

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

Returns boolean
Inherited from BasePlatformAdapter.isSignatureCheckEnabled
- Defined in plugins/platforms/Base/Base.ts:317

send

send(): boolean
SmartApp не поддерживает push-сообщения, поэтому всегда возвращает false.

Returns boolean
Overrides BasePlatformAdapter.send
- Defined in plugins/platforms/SmartApp/Adapter.ts:496

setLocalStorage

setLocalStorage(data: unknown, controller: BotController): Promise<void>
Сохраняет данные пользователя во внешнее хранилище SmartApp.
Parameters
- data: unknown
  Данные для сохранения
- controller: BotController
  Контроллер приложения
Returns Promise<void>
Overrides BasePlatformAdapter.setLocalStorage
- Defined in plugins/platforms/SmartApp/Adapter.ts:465

setQueryData

setQueryData(
query: ISberSmartAppWebhookRequest,
controller: BotController,
): boolean
Разбирает запрос SmartApp и наполняет контроллер данными: команда, NLU, персонаж, сессия, метаданные и данные экрана устройства.
Parameters
- query: ISberSmartAppWebhookRequest
  Входящий webhook-запрос SmartApp
- controller: BotController
  Контроллер приложения
Returns boolean
true, если запрос успешно разобран
Overrides BasePlatformAdapter.setQueryData
- Defined in plugins/platforms/SmartApp/Adapter.ts:204

soundProcessing

soundProcessing(_controller: BotController): void | Promise<void>
Дополнительная обработка для звуков. В данном методе стоит реализовать логику, с помощью которой будут наложены дополнительные эффекты для озвучивания текста пользователю
Parameters
- _controller: BotController
  Контроллер бота
Returns void | Promise<void>
Inherited from BasePlatformAdapter.soundProcessing
- Defined in plugins/platforms/Base/Base.ts:456

updateTimeStart

updateTimeStart(controller: BotController): void
Публичная точка входа для сброса времени начала обработки запроса. Вызывайте перед началом бизнес-логики, чтобы метрики (см. getProcessingTime) считались отсюда.
Parameters
- controller: BotController
Returns void
Inherited from BasePlatformAdapter.updateTimeStart
- Defined in plugins/platforms/Base/Base.ts:418

`Static`isVoice

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

Returns boolean
Inherited from BasePlatformAdapter.isVoice
- Defined in plugins/platforms/Base/Base.ts:520

Class SmartAppAdapter

Example

See

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns SmartAppAdapter

Properties

Protected Optional_platformOptions

Protected Optional_token

OptionalappContext

isVoice

limit

ProtectedMAX_TIME_REQUEST

platformName

OptionalsignatureName

supportedEvents

ProtectedWARNING_TIME_REQUEST

Methods

Protected_getUserData

Parameters

Returns Promise<unknown>

Protected_initTTS

Parameters

Returns void | Promise<void>

Protected_setUserData

Parameters

Returns Promise<IRequestSend<unknown>>

Protected_timeLimitLog

Parameters

Returns void

createApi

Parameters

Returns IControllerApi | null

Example

destroy

Parameters

Returns void | Promise<void>

getContent

Parameters

Returns ISberSmartAppWebhookResponse

getLocalStorage

Type Parameters

Parameters

Returns Promise<TStorageResult>

getProcessingTime

Parameters

Returns number

getQueryExample

Parameters

Returns Record<string, unknown>

getRatingContext

Parameters

Returns ISberSmartAppWebhookResponse

init

Parameters

Returns void

isCorrectQuery

Parameters

Returns boolean

isLocalStorage

Returns boolean

isPlatformOnQuery

Parameters

Returns boolean

isSignatureCheckEnabled

Returns boolean

send

Returns boolean

setLocalStorage

Parameters

Returns Promise<void>

setQueryData

Parameters

Returns boolean

`Protected` `Optional`_platformOptions

`Protected` `Optional`_token

`Optional`appContext

`Protected`MAX_TIME_REQUEST

`Optional`signatureName

`Protected`WARNING_TIME_REQUEST

`Protected`_getUserData

`Protected`_initTTS

`Protected`_setUserData

`Protected`_timeLimitLog

`Static`isVoice