Как работать с Embedded App

Обновлено 20 марта 2024

Что такое Embedded App

Embedded App — это встроенный (нативный) смартап. Не относится к APK-аппам. Пример встроенного смартапа: музыкальный плеер в мобильном приложении «Салют». Для работы Embedded App на стороне Assistant SDK реализован отдельный API.

Как создать навык в IDE для работы с поверхностью

Чтобы создать навык, необходимо создать проект и задать настройки.

Создание проекта

Создать проект можно по стандартному сценарию, который описан в документации к Studio.

Навыки работают на несколько поверхностей: preMatch (функция, которая вызывается перед классификатором интентов) разводит сценарий в разные темы (ветки). Поэтому в разных темах могут работать разные интенты: таким образом можно контролировать поведение смартапа.

Работа навыка с поверхностью

Чтобы навык работал с вашей поверхностью, нужно запросить смену или добавление настроек в app_dir:

• если будет работать на одной поверхности с типом EMBEDDED_APP — присвойте appType значение EMBEDDED_APP для текущей версии смартапа и укажите свою поверхность;

• если будет работать на нескольких поверхностях — заведите внутри project_id несколько смартапов с разными appType, развернутые на разных поверхностях, например:

  • DIALOG_APP «Построение маршрута» на поверхности SBERBOX;
  • EMBEDDED_APP «Построение маршрута» на вашей поверхности.

Внутри аппов можно указать разные интенты, вебхуки и другие настройки.

Как передать в поверхность ответ от навыка

Если настройки указаны правильно, то поверхность получит в ответе строку. Пример кода обработчика:

@Override
public void handle(@NotNull EmbeddedSmartAppDataCommand command,
                   @NotNull EmbeddedSmartAppMessageID messageId) {
    // do something
}

data class EmbeddedSmartAppDataCommand(
    val raw: String
)

Как взаимодействовать с поверхностью

Есть схожие черты с сценариями для Canvas App. На запрос пользователя отрабатывает один из следующих сценариев:

• голосовой ответ;
• ответ в виде команды smart_app_data с произвольным JSON-объектом — формат этого объекта согласуется между бэкендом (фронтендом) на устройстве и сценарием.

Что можно делать в Assistant SDK: отсылать serverAction. Например, для озвучки какого-то события.

API для Embedded App

Ниже перечислены интерфейсы и классы, которые позволяют работать со встроенными смартапами.

Интерфейсы

Ниже перечислены интерфейсы для работы со встроенными смартапами.

EmbeddedSmartAppRegistry

Регистрация встроенного смартапа. Методы:

• register() — регистрирует встроенный смартап в качестве обработчиков сообщений VPS, возвращает EmbeddedSmartAppMessaging;
• release() — снимает смартап с регистрации.

EmbeddedSmartApp

Интерфейс взаимодействия AssistantSDK со встроенным смартапом. Может быть или отдельной сущностью, или расширением Activity/Fragment. Для работы необходимо, чтобы был переопределен и включен флаг ru.sberbank.sdakit.smartapps.domain.config.SmartAppsFeatureFlag.isEmbeddedAppsEnabled.

EmbeddedSmartAppMessaging

Обмен сообщениями. Методы:

• sendData() — возвращает EmbeddedSmartAppMessageID;
• getState() — возвращает статус встроенного смартапа;
• onAssistantStateChanged(state: AssistantState) — метод для отправки данных о состоянии ассистента (state — изменившееся состояние);
• cancelTts() — метод для остановки TTS;
• handle() — обрабатывает команды из VPS.

Классы

Ниже перечислены классы для работы со встроенными смартапами.

EmbeddedSmartAppServerAction

Объект данных ServerAction для отправки в VPS. Свойства:

• payload — Словарь с параметрами, тело запроса в смартап-сценарий. Должен быть корректным JSON.
• actionType — Свойство, чтобы встроенный смартап мог реагировать по-разному.

EmbeddedSmartAppDataCommand

Обертка над данными для передачи во встроенный смартап. Содержит свойство raw — данные для передачи во встроенный смартап.

EmbeddedSmartAppFeature

Описывает возможности платформы, которые требуются для правильной работы EmbeddedSmartApp.