AppIntent: cos'è, il modello di intent Siri e Swift

Cos'è AppIntent e a cosa serve?

AppIntent è un framework Apple per descrivere in modo dichiarativo comandi che la tua app può eseguire su richiesta di Siri, Shortcuts, Spotlight, Control Center e Action Button. Si basa sul protocollo AppIntent, in cui lo sviluppatore descrive il nome dell'intent, i suoi parametri e il metodo perform() — la logica eseguibile. Il framework genera automaticamente un'interfaccia utente per configurare i parametri nell'app Shortcuts e frasi vocali per Siri.

Prima di AppIntent, gli sviluppatori usavano Intents framework — un sistema basato sul file Intents Definition File che generava codice Objective-C e richiedeva la configurazione di un'estensione Intents Extension separata. Questo processo era macchinoso: anche un intent semplice richiedeva fino a 5 file di configurazione. AppIntent elimina questa complessità — un intent è descritto in un singolo file Swift e il sistema genera automaticamente tutto il necessario per l'integrazione con Siri e Shortcuts.

Secondo la sessione WWDC 2024 "Dive deeper into App Intents", Apple vede AppIntent come il meccanismo centrale per estendere le funzionalità delle app oltre l'interfaccia utente tradizionale. Al momento del rilascio di iOS 18, oltre il 70% delle app nella top 100 dell'App Store utilizza già AppIntent per l'integrazione con Shortcuts e Siri, e l'utente medio di iOS 18 avvia 4–6 intent al giorno tramite comandi vocali o widget.

Dove viene usato AppIntent

• Siri — comandi vocali: "Hey Siri, aggiungi un'attività a MyApp"
• Shortcuts — automazione nell'app Comandi con configurazione dei parametri
• Spotlight — ricerca ed esecuzione di comandi direttamente dalla barra di ricerca
• Control Center — pulsanti di azione rapida su iOS 18+
• Action Button — assegnazione di un'azione al pulsante di iPhone 15 Pro e successivi

AppIntent vs Intents framework: differenze principali

Intents framework (iOS 10–15) richiedeva la creazione di un file .intentdefinition, la generazione di classi ObjC/Swift tramite Xcode, la configurazione di Intents Extension e App Intent Configuration. AppIntent (iOS 16+) sostituisce completamente questa pipeline con codice Swift puro senza generazione, estensioni o configurazioni aggiuntive. Ciò rende il processo di creazione degli intent accessibile allo sviluppatore iOS medio senza studiare SiriKit.

Il vantaggio principale di AppIntent è la dichiaratività. Lo sviluppatore descrive cosa fa l'intent, non come si integra con il sistema. Il framework stesso gestisce gli scenari di dialogo di Siri, la visualizzazione dei parametri in Shortcuts e il passaggio di contesto tra intent. Nel vecchio Intents framework, ogni aspetto dell'integrazione doveva essere codificato manualmente, incluso INUIHostedView per visualizzare l'interfaccia utente dell'intent.

Confronto degli approcci

Protocolli principali: AppIntent, AppEntity, AppEnum

AppIntent è il protocollo centrale che definisce un intent. Contiene un title (nome per Siri), description (descrizione in Shortcuts), parametri (tramite @Parameter) e il metodo perform() che restituisce IntentResult. Il risultato può essere IntentDialog (dialogo con Siri), un valore da restituire a Shortcuts o un errore. Ogni intent può anche fornire suggestedInvocationPhrase — una frase per l'invocazione vocale.

AppEntity descrive le entità con cui lavorano gli intent. Ad esempio, se un'app gestisce progetti, AppEntity Project contiene id, displayRepresentation (come visualizzare l'entità nell'interfaccia utente) e defaultQuery (come cercare entità). AppEnum è un'enumerazione per parametri di selezione che genera automaticamente un'interfaccia utente con un elemento picker in Shortcuts. Invece di creare manualmente un elenco di parametri, basta dichiarare un enum conforme ad AppEnum.

Esempio di AppEnum e parametro

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

Parametri degli intent e loro validazione

I parametri di AppIntent vengono dichiarati tramite il property wrapper @Parameter, che si integra automaticamente con l'interfaccia utente di Shortcuts e le richieste vocali di Siri. Ogni parametro ha un title (visualizzato in Shortcuts) e può includere una descrizione, valori predefiniti e vincoli. AppIntent supporta i tipi standard: String, Int, Double, Bool, oltre a tipi personalizzati tramite AppEntity e AppEnum.

La validazione dei parametri viene eseguita nel metodo perform() prima di eseguire la logica. Se i parametri non sono validi, l'intent restituisce un errore tramite IntentError. Per validazioni complesse, è possibile implementare il metodo validate(), chiamato prima di perform(), che può fornire feedback all'utente tramite IntentDialog ancora prima di eseguire il comando. Ciò è particolarmente utile per scenari vocali di Siri, dove è più semplice chiedere nuovamente all'utente piuttosto che eseguire un comando errato.

Parametri con validazione

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

Creazione di un intent in Swift: esempio

Un esempio completo di intent per cercare note in un'app dimostra il lavoro con AppEntity e EntityQuery. SearchNotesIntent accetta una stringa di ricerca e restituisce un elenco di note trovate. AppEntity Note descrive la struttura della nota e EntityQuery implementa la ricerca nell'archivio. Il risultato viene restituito tramite IntentResult con un array di entità, che Shortcuts mostra all'utente.

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

Integrazione con Shortcuts e Siri

Dopo aver dichiarato un AppIntent, l'integrazione con Shortcuts e Siri avviene automaticamente. L'app Shortcuts scansiona tutti gli AppIntents dalle app installate e li mostra nell'elenco delle azioni disponibili. L'utente può aggiungere un intent al suo collegamento, configurarne i parametri e combinarlo con altre azioni. Per Siri, gli intent appaiono come comandi vocali senza configurazione aggiuntiva da parte dello sviluppatore.

Lo sviluppatore può migliorare l'integrazione aggiungendo suggestedInvocationPhrase — una frase consigliata per l'invocazione vocale. Ad esempio, per un intent di aggiunta attività: suggestedInvocationPhrase = "Add new task". Siri analizza questa frase e la suggerisce all'utente durante l'apprendimento dei comandi vocali. È anche possibile specificare categories — la categoria dell'intent (create, view, search, edit), che aiuta Shortcuts a raggruppare le azioni per significato.

Categorie di intent per Shortcuts