AppIntent: что это, модель интентов Siri и Swift

Что такое AppIntent и зачем он нужен?

AppIntent — фреймворк Apple для декларативного описания команд, которые ваше приложение может выполнять по запросу Siri, Shortcuts, Spotlight, Control Center и Action Button. В основе лежит протокол AppIntent, в котором разработчик описывает название интента, его параметры и метод perform() — исполняемую логику. Фреймворк автоматически генерирует пользовательский интерфейс для настройки параметров в приложении Shortcuts и голосовые фразы для Siri.

До появления AppIntent разработчики использовали Intents framework — систему, основанную на Intents Definition File, который генерировал Objective-C код, и требовал настройки отдельного Intents Extension. Этот процесс был громоздким: даже простой интент требовал до 5 файлов конфигурации. AppIntent устраняет эту сложность — интент описывается в одном Swift-файле, а система автоматически генерирует всё необходимое для интеграции с Siri и Shortcuts.

По данным WWDC 2024 Session "Dive deeper into App Intents", Apple видит AppIntent как центральный механизм расширения функциональности приложений за пределы традиционного UI. К моменту выхода iOS 18 более 70% приложений из топ-100 App Store уже используют AppIntent для интеграции с Shortcuts и Siri, а средний пользователь iOS 18 запускает 4–6 интентов в день через голосовые команды или виджеты.

Где используются AppIntent

• Siri — голосовые команды: "Hey Siri, добавь задачу в MyApp"
• Shortcuts — автоматизация в приложении Команды с настройкой параметров
• Spotlight — поиск и выполнение команд прямо из строки поиска
• Control Center — кнопки быстрого действия на iOS 18+
• Action Button — настройка действия на кнопку iPhone 15 Pro и новее

AppIntent vs Intents framework: ключевые отличия

Intents framework (iOS 10–15) требовал создания .intentdefinition файла, генерации ObjC/Swift-классов через Xcode, настройки Intents Extension и App Intent Configuration. AppIntent (iOS 16+) полностью заменяет этот пайплайн чистым Swift-кодом без генерации, расширений и дополнительных конфигураций. Это делает процесс создания интентов доступным для рядового iOS-разработчика без изучения SiriKit.

Ключевое преимущество AppIntent — декларативность. Разработчик описывает что делает интент, а не как он интегрируется с системой. Фреймворк сам обрабатывает диалоговые сценарии Siri, отображение параметров в Shortcuts и передачу контекста между интентами. В старом Intents framework каждый аспект интеграции приходилось кодировать вручную, включая INUIHostedView для отображения UI интента.

Сравнение подходов

Основные протоколы: AppIntent, AppEntity, AppEnum

AppIntent — центральный протокол, который определяет интент. Он содержит title (название для Siri), description (описание в Shortcuts), параметры (через @Parameter) и метод perform(), возвращающий IntentResult. Результатом может быть IntentDialog (диалог с Siri), значение для возврата в Shortcuts или ошибка. Каждый интент может также предоставлять suggestedInvocationPhrase — фразу для голосового вызова.

AppEntity описывает сущности, с которыми работают интенты. Например, если приложение управляет проектами, AppEntity Project содержит id, displayRepresentation (как отображать сущность в UI) и defaultQuery (как искать сущности). AppEnum — перечисление для параметров выбора, которое автоматически генерирует UI с picker-элементом в Shortcuts. Вместо ручного создания списка параметров достаточно объявить enum, conforming к AppEnum.

Пример AppEnum и параметра

enum TaskPriority: String, AppEnum {
    case low, medium, high
    
    static var typeDisplayRepresentation: TypeDisplayRepresentation =
        "Priority"
    
    var displayRepresentation: DisplayRepresentation {
        switch self {
        case .low: "Low"
        case .medium: "Medium"
        case .high: "High"
        }
    }
}

struct CreateTaskIntent: AppIntent {
    static var title: LocalizedStringResource = "Create Task"
    
    @Parameter(title: "Task Name")
    var taskName: String
    
    @Parameter(title: "Priority")
    var priority: TaskPriority
    
    func perform() async throws -> some IntentResult {
        try await TaskManager.shared
            .createTask(name: taskName, priority: priority)
        return .result(dialog: "Task created")
    }
}

Параметры интентов и их валидация

Параметры AppIntent объявляются через property wrapper @Parameter, который автоматически интегрируется с UI Shortcuts и голосовыми запросами Siri. Каждый параметр имеет title (отображается в Shortcuts) и может содержать описание, значения по умолчанию, ограничения. AppIntent поддерживает стандартные типы: String, Int, Double, Bool, а также кастомные типы через AppEntity и AppEnum.

Валидация параметров выполняется в методе perform() перед выполнением логики. Если параметры некорректны, интент возвращает ошибку через IntentError. Для сложной валидации можно реализовать метод validate(), который вызывается до perform() и может предоставить обратную связь пользователю через IntentDialog еще до выполнения команды. Это особенно полезно для голосовых сценариев Siri, где переспросить пользователя проще, чем выполнить неверную команду.

Параметры с валидацией

struct SendMessageIntent: AppIntent {
    static var title: LocalizedStringResource = "Send Message"
    
    @Parameter(title: "Recipient")
    var recipient: String
    
    @Parameter(title: "Message")
    var message: String
    
    func validate() throws {
        guard message.count >= 1 else {
            throw IntentError.invalidMessage
        }
    }
    
    func perform() async throws -> some IntentResult {
        try await Messenger.shared
            .send(recipient: recipient, text: message)
        return .result(dialog: "Sent!")
    }
}

Создание интента на Swift: пример

Полный пример интента для поиска заметок в приложении демонстрирует работу с AppEntity и EntityQuery. Интент SearchNotesIntent принимает строку поиска и возвращает список найденных заметок. AppEntity Note описывает структуру заметки, а EntityQuery реализует поиск по хранилищу. Результат возвращается через IntentResult с массивом сущностей, который Shortcuts отображает пользователю.

struct Note: AppEntity {
    let id: UUID
    let title: String
    let content: String
    
    static var typeDisplayRepresentation: TypeDisplayRepresentation =
        "Note"
    
    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "(title)")
    }
}

struct SearchNotesIntent: AppIntent {
    static var title: LocalizedStringResource = "Search Notes"
    
    @Parameter(title: "Query")
    var query: String
    
    func perform() async throws -> some IntentResult {
        let results = await NoteStore.shared
            .search(query)
            .map { $0.toEntity() }
        return .result(value: results)
    }
}

Интеграция с Shortcuts и Siri

После объявления AppIntent интеграция с Shortcuts и Siri происходит автоматически. Приложение Shortcuts сканирует все AppIntent-ы из установленных приложений и отображает их в списке доступных действий. Пользователь может добавить интент в свою команду, настроить его параметры и скомбинировать с другими действиями. Для Siri интенты появляются как голосовые команды без дополнительной настройки со стороны разработчика.

Разработчик может улучшить интеграцию, добавив suggestedInvocationPhrase — рекомендуемую фразу для голосового вызова. Например, для интента добавления задачи: suggestedInvocationPhrase = "Add new task". Siri анализирует эту фразу и предлагает её пользователю при обучении голосовым командам. Также можно указать categories — категорию интента (create, view, search, edit), которая помогает Shortcuts группировать действия по смыслу.

Категории интентов для Shortcuts