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 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, који се аутоматски интегрише са Shortcuts UI-јем и 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