AppIntent: какво е, модел на Siri интенциите и Swift

Какво е AppIntent и за какво служи?

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

Преди появата на AppIntent, разработчиците използваха Intents framework — система, базирана на Intent 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 срещу 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, който отговаря на 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