AppIntent: ce este, modelul intenţiilor Siri şi Swift

Ce este AppIntent şi de ce este necesar?

AppIntent — framework-ul Apple pentru descrierea declarativă a comenzilor pe care aplicaţia dvs. le poate executa la cererea Siri, Shortcuts, Spotlight, Control Center şi Action Button. La bază stă protocolul AppIntent, în care dezvoltatorul descrie numele intenţiei, parametrii săi şi metoda perform() — logica executată. Framework-ul generează automat interfaţa de utilizator pentru configurarea parametrilor în aplicaţia Shortcuts şi frazele vocale pentru Siri.

Înainte de apariţia AppIntent, dezvoltatorii foloseau Intents framework — un sistem bazat pe fişierul Intents Definition File, care genera cod Objective-C şi necesita configurarea unui Intents Extension separat. Acest proces era greoi: chiar şi o intenţie simplă necesita până la 5 fişiere de configurare. AppIntent elimină această complexitate — intenţia este descrisă într-un singur fişier Swift, iar sistemul generează automat tot ce este necesar pentru integrarea cu Siri şi Shortcuts.

Conform WWDC 2024 Session „Dive deeper into App Intents“, Apple vede AppIntent ca mecanism central pentru extinderea funcţionalităţii aplicaţiilor dincolo de UI-ul tradiţional. Până la lansarea iOS 18, peste 70% din aplicaţiile din top 100 App Store folosesc deja AppIntent pentru integrarea cu Shortcuts şi Siri, iar utilizatorul mediu de iOS 18 lansează 4–6 intenţii pe zi prin comenzi vocale sau widget-uri.

Unde se folosesc AppIntent

• Siri — comenzi vocale: „Hey Siri, adaugă o sarcină în MyApp“
• Shortcuts — automatizare în aplicaţia Comenzi cu configurarea parametrilor
• Spotlight — căutarea şi executarea comenzilor direct din bara de căutare
• Control Center — butoane de acţiune rapidă pe iOS 18+
• Action Button — configurarea acţiunii pentru butonul iPhone 15 Pro şi mai noi

AppIntent vs Intents framework: diferenţe cheie

Intents framework (iOS 10–15) necesita crearea fişierului .intentdefinition, generarea claselor ObjC/Swift prin Xcode, configurarea Intents Extension şi App Intent Configuration. AppIntent (iOS 16+) înlocuieşte complet această conductă cu cod Swift pur, fără generare, extensii şi configuraţii suplimentare. Acest lucru face procesul de creare a intenţiilor accesibil pentru dezvoltatorul obişnuit de iOS, fără a învăţa SiriKit.

Avantajul cheie al AppIntent este caracterul declarativ. Dezvoltatorul descrie ce face intenţia, nu cum se integrează cu sistemul. Framework-ul gestionează singur scenariile de dialog Siri, afişarea parametrilor în Shortcuts şi transmiterea contextului între intenţii. În vechiul Intents framework, fiecare aspect al integrării trebuia codat manual, inclusiv INUIHostedView pentru afişarea UI-ului intenţiei.

Compararea abordărilor

Protocoale principale: AppIntent, AppEntity, AppEnum

AppIntent — protocolul central care defineşte intenţia. Conţine title (numele pentru Siri), description (descrierea în Shortcuts), parametrii (prin @Parameter) şi metoda perform() care returnează IntentResult. Rezultatul poate fi IntentDialog (dialog cu Siri), o valoare de returnat în Shortcuts sau o eroare. Fiecare intenţie poate oferi, de asemenea, suggestedInvocationPhrase — o frază pentru apelul vocal.

AppEntity descrie entităţile cu care lucrează intenţiile. De exemplu, dacă aplicaţia gestionează proiecte, AppEntity Project conţine id, displayRepresentation (cum se afişează entitatea în UI) şi defaultQuery (cum se caută entităţile). AppEnum — enumerare pentru parametrii de selecţie, care generează automat UI cu un element picker în Shortcuts. În loc să creaţi manual o listă de parametri, este suficient să declaraţi un enum care se conformează la AppEnum.

Exemplu de AppEnum şi 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")
    }
}

Parametrii intenţiilor şi validarea lor

Parametrii AppIntent sunt declaraţi prin property wrapper @Parameter, care se integrează automat cu UI-ul Shortcuts şi cererile vocale Siri. Fiecare parametru are un title (afişat în Shortcuts) şi poate conţine descriere, valori implicite, restricţii. AppIntent suportă tipurile standard: String, Int, Double, Bool, precum şi tipuri personalizate prin AppEntity şi AppEnum.

Validarea parametrilor se efectuează în metoda perform() înainte de executarea logicii. Dacă parametrii sunt incorecţi, intenţia returnează o eroare prin IntentError. Pentru validare complexă, se poate implementa metoda validate(), care este apelată înainte de perform() şi poate oferi feedback utilizatorului prin IntentDialog chiar înainte de executarea comenzii. Acest lucru este util în special în scenariile vocale Siri, unde este mai uşor să întrebaţi din nou utilizatorul decât să executaţi o comandă incorectă.

Parametri cu validare

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

Crearea unei intenţii în Swift: exemplu

Un exemplu complet de intenţie pentru căutarea notiţelor într-o aplicaţie demonstrează lucrul cu AppEntity şi EntityQuery. Intenţia SearchNotesIntent primeşte un şir de căutare şi returnează o listă de notiţe găsite. AppEntity Note descrie structura notiţei, iar EntityQuery implementează căutarea în depozit. Rezultatul este returnat prin IntentResult cu un array de entităţi, pe care Shortcuts îl afişează utilizatorului.

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

Integrarea cu Shortcuts şi Siri

După declararea AppIntent, integrarea cu Shortcuts şi Siri are loc automat. Aplicaţia Shortcuts scanează toate AppIntent-urile din aplicaţiile instalate şi le afişează în lista de acţiuni disponibile. Utilizatorul poate adăuga intenţia în comanda sa, poate configura parametrii şi o poate combina cu alte acţiuni. Pentru Siri, intenţiile apar ca comenzi vocale fără configurare suplimentară din partea dezvoltatorului.

Dezvoltatorul poate îmbunătăţi integrarea adăugând suggestedInvocationPhrase — o frază recomandată pentru apelul vocal. De exemplu, pentru intenţia de adăugare a unei sarcini: suggestedInvocationPhrase = "Add new task". Siri analizează această frază şi o propune utilizatorului la învăţarea comenzilor vocale. De asemenea, se poate specifica categories — categoria intenţiei (create, view, search, edit), care ajută Shortcuts să grupeze acţiunile după sens.

Categoriile de intenţii pentru Shortcuts