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, що відповідає 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