Intents Extension: ключевые понятия и интеграция Siri Intents в iOS

Что такое Intents Extension в iOS

Intents Extension — это app extension, которое позволяет Siri, Shortcuts и другим системным сервисам вызывать функциональность приложения через стандартизированный протокол INIntentHandler. Когда пользователь говорит «Привет Siri, отправь сообщение в Мессенджере X», Siri активирует соответствующее расширение, передаёт параметры запроса и получает результат для озвучивания.

В отличие от других типов расширений, Intents Extension работает в фоновом режиме без видимого интерфейса — Siri сама отображает ответ голосом или текстовой карточкой. Расширение может опционально предоставить кастомный UI через INUIHostedViewProviding, который отображается внутри Siri перед выполнением команды для подтверждения.

Расширение не имеет доступа к экрану устройства и не может инициировать действия самостоятельно — только в ответ на запрос от Siri или Shortcuts. Это обеспечивает безопасность: пользователь всегда контролирует, какие действия выполняет приложение через голосовые команды.

SiriKit и домены интентов

SiriKit — это фреймворк Apple для интеграции с Siri, представленный в iOS 10. Он определяет домены — категории действий, которые Siri может обрабатывать: сообщения, телефонные звонки, платежи, списки, напоминания, фото, тренировки, бронирования и другие. Каждый домен имеет фиксированный набор интентов и ответов.

Стандартные домены

INSendMessageIntent — отправка сообщений. INStartWorkoutIntent — начало тренировки. INSearchForPhotosIntent — поиск фотографий. INRequestRideIntent — заказ такси. Каждый домен определяет обязательные и опциональные параметры, которые Siri извлекает из голосового запроса. По данным Apple, для стандартных доменов не требуется файл intentdefinition — достаточно реализовать соответствующий handler.

Для приложений, не попадающих в стандартные домены, с iOS 14 появилась возможность кастомных интентов. Приложение определяет собственные типы команд и их параметры через Intents.intentdefinition, а Siri учится распознавать соответствующие фразы на основе примеров, предоставленных разработчиком.

Конфигурация в Info.plist

Intents Extension регистрируется через ключ IntentsSupported в Info.plist, где перечисляются все классы интентов, которые расширение обрабатывает. Siri использует этот список для выбора подходящего расширения при распознавании голосовой команды. Если несколько расширений поддерживают один интент, Siri предлагает пользователю выбрать.

class MessageIntentHandler: NSObject,
    INSendMessageIntentHandling {

    func handle(
        intent: INSendMessageIntent,
        completion: @escaping
            (INSendMessageIntentResponse) -> Void
    ) {
        let response = INSendMessageIntentResponse(
            code: .success, userActivity: nil)
        completion(response)
    }
}

INIntentHandler: обработка запросов

INIntentHandler — протокол, который определяет методы для обработки каждого этапа работы интента: разрешение параметров, подтверждение и выполнение. Расширение реализует эти методы для каждого типа интента, который оно поддерживает.

Три этапа обработки

resolve — проверка и уточнение параметров интента. Siri вызывает этот метод для каждого параметра. Если параметр не указан или указан некорректно, расширение возвращает запрос на уточнение, и Siri задаёт пользователю дополнительный вопрос. confirm — подтверждение намерения. Расширение проверяет, может ли оно выполнить интент в текущем контексте. handle — фактическое выполнение операции и возврат результата.

Разделение на три этапа критически важно для голосового UX: если параметр не распознан, Siri не выполняет действие, а переспрашивает. Например, если пользователь сказал «Отправь сообщение Алексею», но в контактах три Алексея — расширение возвращает resolve с запросом уточнения, и Siri спрашивает «Какому Алексею?».

INIntentResponse и статусы

INIntentResponse — объект, который расширение возвращает в completion после выполнения интента. Response содержит код результата (success, failure, requiresAuthentication, inProgress) и опциональные данные для озвучивания Siri. Код определяет, как Siri отреагирует: success — голосовое подтверждение, failure — сообщение об ошибке, inProgress — индикация длительной операции.

func resolve(
    for intent: INSendMessageIntent,
    with completion: @escaping
        (INStringResolutionResult) -> Void
) {
    if let text = intent.content, !text.isEmpty {
        completion(.success(with: text))
    } else {
        completion(.needsValue())
    }
}

Создание кастомных интентов

С iOS 14 разработчики получили возможность определять собственные интенты вне стандартных доменов SiriKit. Кастомные интенты описываются в файле Intents.intentdefinition — это визуальный редактор внутри Xcode, где создаются новые типы команд с параметрами и ответами.

Структура кастомного интента

Каждый кастомный интент состоит из INIntent (определение запроса) и INIntentResponse (определение ответа). INIntent содержит параметры с типом данных — String, Integer, CurrencyAmount, найденные объекты и другие. INIntentResponse содержит свойства для возврата результата и массив кодов ответа. Xcode автоматически генерирует Swift-классы на основе этого определения.

Apple рекомендует включать в кастомный интент не более 5 параметров — избыточное количество ухудшает распознавание голоса и усложняет пользовательский опыт. Для каждого параметра желательно предоставить примеры фраз в Assistant Dialog, чтобы Siri научилась их корректно распознавать.

Примеры фраз для Siri

В Intents.intentdefinition для каждого интента можно указать примеры предложений — фразы, которые пользователь скажет Siri для активации интента. Примеры: «Закажи кофе в МоемПриложении», «Попроси МоёПриложение найти рецепт пиццы». Siri использует эти фразы для обучения распознаванию и предлагает их пользователю при настройке Shortcuts.

// Intents.intentdefinition (visual editor)
Intent: OrderCoffeeIntent
Parameters:
  - beverage (String)
  - size (String)
  - quantity (Integer)
Response:
  - orderNumber (String)
  - price (CurrencyAmount)
Phrases:
  - "Order coffee in MyApp"
  - "Get a latte from MyApp"

Голосовое взаимодействие и INUIHostedViewProviding

INUIHostedViewProviding — протокол, который позволяет Intents Extension показывать кастомный интерфейс внутри Siri перед выполнением команды. Например, при заказе такси расширение может отобразить карту с маршрутом и стоимостью, а пользователь подтверждает действие касанием.

Конфигурация интерфейса

Протокол определяет метод configure(with:for:completion:), где расширение получает интент и возвращает UIViewController, который будет встроен в Siri. Размер контроллера ограничен — максимальная высота 200 точек. Рекомендуется использовать компактные карточки с ключевой информацией: сумма, время, адрес.

Кастомный интерфейс опционален — если расширение не реализует INUIHostedViewProviding, Siri отображает стандартную карточку с типом интента и приложением. Для большинства интентов стандартный UI достаточен, и Apple рекомендует добавлять кастомный интерфейс только когда он действительно улучшает понимание — например, для отображения маршрута или подтверждения платежа.

Безопасность и подтверждение

Для интентов, связанных с финансами или личными данными, требуется аутентификация. INIntentResponse поддерживает код requiresAuthentication, который заставляет Siri запросить Face ID или Touch ID перед выполнением. После аутентификации расширение получает подтверждение через отдельный вызов handle, где проверяется статус аутентификации.

Apple особо подчёркивает: Intents Extension не должен запрашивать собственный пароль или биометрию — используется системная аутентификация. Хранение токенов доступа в Keychain с общим доступом между приложением и расширением — стандартная практика для long-lived сессий.

class IntentViewController: UIViewController {

    func configure(
        with intent: INIntent,
        completion: @escaping
            (UIViewController?) -> Void
    ) {
        let cardView = ConfirmationCardView()
        let hostingController =
            UIHostingController(rootView: cardView)
        completion(hostingController)
    }
}