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

Что такое Embedded App

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Есть схожие черты с сценариями для 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

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней