AppIntent: co to je, model intencí Siri a Swift

Co je AppIntent a k čemu slouží?

AppIntent — framework Apple pro deklarativní popis příkazů, které může vaše aplikace provádět na požádání Siri, Shortcuts, Spotlight, Control Center a Action Button. V základu je protokol AppIntent, ve kterém vývojář popisuje název intentu, jeho parametry a metodu perform() — prováděnou logiku. Framework automaticky generuje uživatelské rozhraní pro konfiguraci parametrů v aplikaci Shortcuts a hlasové fráze pro Siri.

Před příchodem AppIntent používali vývojáři Intents framework — systém založený na Intents Definition File, který generoval kód Objective-C a vyžadoval konfiguraci samostatného Intents Extension. Tento proces byl komplikovaný: i jednoduchý intent vyžadoval až 5 konfiguračních souborů. AppIntent tuto složitost odstraňuje — intent je popsán v jednom Swift souboru a systém automaticky generuje vše potřebné pro integraci se Siri a Shortcuts.

Podle WWDC 2024 Session „Dive deeper into App Intents“, Apple vidí AppIntent jako centrální mechanismus pro rozšíření funkčnosti aplikací nad rámec tradičního UI. V době vydání iOS 18 více než 70% aplikací z top 100 App Store již používá AppIntent pro integraci s Shortcuts a Siri a průměrný uživatel iOS 18 spouští 4–6 intentů denně pomocí hlasových příkazů nebo widgetů.

Kde se AppIntent používá

• Siri — hlasové příkazy: „Hey Siri, přidej úkol do MyApp“
• Shortcuts — automatizace v aplikaci Zkratky s konfigurací parametrů
• Spotlight — vyhledávání a provádění příkazů přímo z vyhledávacího pole
• Control Center — tlačítka rychlých akcí na iOS 18+
• Action Button — konfigurace akce pro tlačítko iPhone 15 Pro a novější

AppIntent vs Intents framework: klíčové rozdíly

Intents framework (iOS 10–15) vyžadoval vytvoření .intentdefinition souboru, generování ObjC/Swift tříd přes Xcode, konfiguraci Intents Extension a App Intent Configuration. AppIntent (iOS 16+) zcela nahrazuje toto potrubí čistým Swift kódem bez generování, rozšíření a dalších konfigurací. To činí proces vytváření intentů dostupným pro běžného iOS vývojáře bez nutnosti učení SiriKit.

Klíčovou výhodou AppIntent je deklarativnost. Vývojář popisuje, co intent dělá, ne jak je integrován se systémem. Framework sám zpracovává dialogové scénáře Siri, zobrazení parametrů v Shortcuts a předávání kontextu mezi intenty. Ve starém Intents framework musel být každý aspekt integrace kódován ručně, včetně INUIHostedView pro zobrazení UI intentu.

Porovnání přístupů

Základní protokoly: AppIntent, AppEntity, AppEnum

AppIntent — centrální protokol, který definuje intent. Obsahuje title (název pro Siri), description (popis v Shortcuts), parametry (přes @Parameter) a metodu perform() vracející IntentResult. Výsledkem může být IntentDialog (dialog se Siri), hodnota pro vrácení do Shortcuts nebo chyba. Každý intent může také poskytovat suggestedInvocationPhrase — frázi pro hlasové volání.

AppEntity popisuje entity, se kterými intenty pracují. Například, pokud aplikace spravuje projekty, AppEntity Project obsahuje id, displayRepresentation (jak zobrazit entitu v UI) a defaultQuery (jak vyhledávat entity). AppEnum — výčet pro parametry výběru, který automaticky generuje UI s prvkem picker v Shortcuts. Místo ručního vytváření seznamu parametrů staāčí deklarovat enum, který je v souladu s AppEnum.

Příklad AppEnum a parametru

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")
    }
}

Parametry intentů a jejich validace

Parametry AppIntent jsou deklarovány prostřednictvím property wrapper @Parameter, který se automaticky integruje s UI Shortcuts a hlasovými požadavky Siri. Každý parametr má title (zobrazený v Shortcuts) a může obsahovat popis, výchozí hodnoty, omezení. AppIntent podporuje standardní typy: String, Int, Double, Bool, stejně jako vlastní typy prostřednictvím AppEntity a AppEnum.

Validace parametrů se provádí v metodě perform() před provedením logiky. Pokud jsou parametry nesprávné, intent vrátí chybu prostřednictvím IntentError. Pro složitou validaci lze implementovat metodu validate(), která je volána před perform() a může poskytnout zpětnou vazbu uživateli prostřednictvím IntentDialog ještě před provedením příkazu. To je zvláště užitečné v hlasových scénářích Siri, kde je snazší znovu se zeptat uživatele než provést nesprávný příkaz.

Parametry s validací

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!")
    }
}

Vytvoření intentu ve Swift: příklad

Úplný příklad intentu pro vyhledávání poznámek v aplikaci demonstruje práci s AppEntity a EntityQuery. Intent SearchNotesIntent přijímá vyhledávací řetězec a vrací seznam nalezených poznámek. AppEntity Note popisuje strukturu poznámky a EntityQuery implementuje vyhledávání v úložišti. Výsledek je vrácen prostřednictvím IntentResult s polem entit, které Shortcuts zobrazí uživateli.

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)
    }
}

Integrace s Shortcuts a Siri

Po deklarování AppIntent probíhá integrace s Shortcuts a Siri automaticky. Aplikace Shortcuts skenuje všechny AppIntent z nainstalovaných aplikací a zobrazuje je v seznamu dostupných akcí. Uživatel může přidat intent do svého příkazu, nakonfigurovat jeho parametry a zkombinovat s jinými akcemi. Pro Siri se intenty objevují jako hlasové příkazy bez další konfigurace ze strany vývojáře.

Vývojář může zlepšit integraci přidáním suggestedInvocationPhrase — doporučené fráze pro hlasové volání. Například pro intent přidání úkolu: suggestedInvocationPhrase = "Add new task". Siri analyzuje tuto frázi a nabídne ji uživateli při učení hlasových příkazů. Také lze určit categories — kategorii intentu (create, view, search, edit), která pomáhá Shortcuts seskupovat akce podle významu.

Kategorie intentů pro Shortcuts