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

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

Что такое Embedded App

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

В релизе 22.6.1002 добавили новый фреймворк AssistantAPI и перенесли в него EmbeddedAppAPI. Везде, где использовался API для Embedded App, нужно подключить AssistantAPI вместо AssistantSDK.

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

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

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

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

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

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

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

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

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

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

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

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

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

func handle(
    command: SmartAppCommand,
    messageID: EmbeddedSmartAppMessageID
)

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

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

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

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

API для Embedded App

EmbeddedSmartApp

Протокол взаимодействия Assistant SDK со встроенными смартапами.

Содержит следующее:

• описательная часть смартапа, которая содержит информацию об идентификации смартапа (systemName):

var description: EmbeddedSmartAppDescription { get }

• актуальное состояние встроенного смартапа, подтягивается в сообщениях VPS:

var state: EmbeddedAppRawState { get }

• метод обработки смартап-команд от навыка:

func handle(
    command: SmartAppCommand,
    messageID: EmbeddedSmartAppMessageID
)

EmbeddedSmartAppDescription

Протокол, описывающий встроенный смартап. Необходим для регистрации смартапа, дальнейшей отправки команд и роутинга на стороне хост-приложения.

Содержит системное имя навыка на бэкенде; должен существовать для всех смартапов типа Embedded App:

var systemName: SystemName

EmbeddedSmartAppController

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

Контроллер может работать только с зарегистрированными смартапами — что-то отправить от несуществующего смартапа не получится.

Содержит следующее:

• методы регистрации и освобождения встроенного смартапа:

func register(smartApp: EmbeddedSmartApp) throws
func release(smartApp: EmbeddedSmartApp) throws

• методы захвата текущего смартапа при общении через VPS:

func makeCurrent(smartApp: EmbeddedSmartApp) throws
func releaseCurrent(smartApp: EmbeddedSmartApp) throws

• метод отправки ServerAction в VPS (отправлять много запросов не рекомендуется — максимум 1-2 запроса в секунду от пользователя):

@discardableResult
  func sendData(
smartApp: EmbeddedSmartApp,
serverAction: EmbeddedSmartAppServerAction
  ) throws -> EmbeddedSmartAppMessageID

EmbeddedSmartAppServerAction

Объект перечисления данных для отправки ServerAction в VPS. Бывает двух типов: фоновые и активные. Главное отличие, что фоновый не может повлиять на состояние UI ассистента.

case foreground
case background

EmbeddedSmartAppMessageID

Номер сообщения. Можно использовать для синхронизации между запросом и ответом.

EmbeddedSmartAppControllerError

Ошибки, возникающие при работе с API встроенных смартапов.

Содержит следующее:

• ошибка регистрации встроенного смартапа:

case alreadyRegisteredApplication

• ошибка обращения к незарегистрированному смартапу:

case controllerNotCreated

• ошибка обращения к удаленному контроллеру:

case controllerNotCreated

• ошибка выполнения ServerAction:

case failedToPerformServerAction

• ошибка наличия несериализуемых данных в словаре:

case payloadNotSerializable

• ошибка при отключенной возможности перевести смартап в активное состояние из API. Возникает, когда при создании хост-приложение явным образом указывает AssistantStackScreenController. В этом случае currentApp может быть определен внутри SDK самостоятельно:

case currentAppFeatureDisabled

• ошибка, возникающая при попытке перевести смартап, который не является текущим (активным), в фоновое состояние:

case isNotCurrentApp