AppIntent: wat is het, model van Siri-intents en Swift

Wat is AppIntent en waarvoor dient het?

AppIntent — Apple framework voor het declaratief beschrijven van opdrachten die uw app kan uitvoeren op verzoek van Siri, Shortcuts, Spotlight, Control Center en Action Button. Aan de basis ligt het protocol AppIntent, waarin de ontwikkelaar de naam van de intent, de parameters en de methode perform() — de uit te voeren logica beschrijft. Het framework genereert automatisch de gebruikersinterface voor het configureren van parameters in de Shortcuts-app en spraakzinnen voor Siri.

Vóór de komst van AppIntent gebruikten ontwikkelaars Intents framework — een systeem gebaseerd op Intents Definition File, dat Objective-C code genereerde en configuratie van een aparte Intents Extension vereiste. Dit proces was omslachtig: zelfs een eenvoudige intent vereiste tot 5 configuratiebestanden. AppIntent elimineert deze complexiteit — de intent wordt beschreven in één Swift-bestand, en het systeem genereert automatisch alles wat nodig is voor integratie met Siri en Shortcuts.

Volgens WWDC 2024 Session „Dive deeper into App Intents“, ziet Apple AppIntent als het centrale mechanisme voor het uitbreiden van app-functionaliteit buiten de traditionele UI. Tegen de tijd van iOS 18 gebruikt meer dan 70% van de apps in de top 100 van de App Store al AppIntent voor integratie met Shortcuts en Siri, en de gemiddelde iOS 18-gebruiker start 4–6 intents per dag via spraakopdrachten of widgets.

Waar worden AppIntent gebruikt

• Siri — spraakopdrachten: „Hey Siri, voeg taak toe aan MyApp“
• Shortcuts — automatisering in de app Snelkoppelingen met parameterconfiguratie
• Spotlight — zoeken en uitvoeren van opdrachten rechtstreeks vanuit de zoekbalk
• Control Center — knoppen voor snelle actie op iOS 18+
• Action Button — configuratie van actie voor de knop van iPhone 15 Pro en nieuwer

AppIntent vs Intents framework: belangrijkste verschillen

Intents framework (iOS 10–15) vereiste het maken van een .intentdefinition-bestand, het genereren van ObjC/Swift-klassen via Xcode, configuratie van Intents Extension en App Intent Configuration. AppIntent (iOS 16+) vervangt deze pijplijn volledig met zuivere Swift-code zonder generatie, extensies en extra configuraties. Dit maakt het proces van het maken van intents toegankelijk voor de gemiddelde iOS-ontwikkelaar zonder SiriKit te hoeven leren.

Het belangrijkste voordeel van AppIntent is de declarativiteit. De ontwikkelaar beschrijft wat de intent doet, niet hoe het met het systeem integreert. Het framework handelt zelf Siri-dialogscenario’s, weergave van parameters in Shortcuts en overdracht van context tussen intents af. In het oude Intents framework moest elk aspect van integratie handmatig worden gecodeerd, inclusief INUIHostedView voor het weergeven van de intent-UI.

Vergelijking van benaderingen

Belangrijkste protocollen: AppIntent, AppEntity, AppEnum

AppIntent — het centrale protocol dat de intent definieert. Het bevat title (naam voor Siri), description (beschrijving in Shortcuts), parameters (via @Parameter) en de methode perform() die IntentResult retourneert. Het resultaat kan IntentDialog (dialoog met Siri), een terug te geven waarde in Shortcuts of een fout zijn. Elke intent kan ook suggestedInvocationPhrase — een zin voor spraakoproep bieden.

AppEntity beschrijft entiteiten waarmee intents werken. Bijvoorbeeld, als de app projecten beheert, bevat AppEntity Project id, displayRepresentation (hoe de entiteit in de UI wordt weergegeven) en defaultQuery (hoe entiteiten te zoeken). AppEnum — opsomming voor selectieparameters die automatisch UI genereert met een picker-element in Shortcuts. In plaats van handmatig een parameterlijst te maken, volstaat het om een enum te declareren die conform AppEnum is.

Voorbeeld van AppEnum en parameter

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

Parameters van intents en hun validatie

Parameters van AppIntent worden gedeclareerd via de property wrapper @Parameter, die automatisch integreert met de Shortcuts-UI en spraakverzoeken van Siri. Elke parameter heeft een title (weergegeven in Shortcuts) en kan een beschrijving, standaardwaarden, beperkingen bevatten. AppIntent ondersteunt standaardtypes: String, Int, Double, Bool, evenals aangepaste types via AppEntity en AppEnum.

Validatie van parameters wordt uitgevoerd in de methode perform() voordat de logica wordt uitgevoerd. Als parameters onjuist zijn, retourneert de intent een fout via IntentError. Voor complexe validatie kan de methode validate() worden geïmplementeerd, die wordt aangeroepen vóór perform() en feedback aan de gebruiker kan geven via IntentDialog nog voordat de opdracht wordt uitgevoerd. Dit is vooral nuttig in Siri-spraakscenario’s, waar het gemakkelijker is om de gebruiker opnieuw te vragen dan een onjuiste opdracht uit te voeren.

Parameters met validatie

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

Een intent maken in Swift: voorbeeld

Een volledig voorbeeld van een intent voor het zoeken van notities in een app demonstreert het werken met AppEntity en EntityQuery. De intent SearchNotesIntent ontvangt een zoekstring en retourneert een lijst met gevonden notities. AppEntity Note beschrijft de structuur van een notitie, en EntityQuery implementeert het zoeken in de opslag. Het resultaat wordt geretourneerd via IntentResult met een array van entiteiten, die Shortcuts aan de gebruiker toont.

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

Integratie met Shortcuts en Siri

Na declaratie van AppIntent vindt integratie met Shortcuts en Siri automatisch plaats. De Shortcuts-app scant alle AppIntent uit geïnstalleerde apps en toont ze in de lijst met beschikbare acties. De gebruiker kan de intent aan zijn opdracht toevoegen, de parameters configureren en combineren met andere acties. Voor Siri verschijnen intents als spraakopdrachten zonder extra configuratie van de ontwikkelaar.

De ontwikkelaar kan de integratie verbeteren door suggestedInvocationPhrase toe te voegen — een aanbevolen zin voor spraakoproep. Bijvoorbeeld voor een intent om een taak toe te voegen: suggestedInvocationPhrase = "Add new task". Siri analyseert deze zin en stelt deze voor aan de gebruiker bij het leren van spraakopdrachten. Ook kan categories — de categorie van de intent (create, view, search, edit) worden opgegeven, wat Shortcuts helpt acties te groeperen op betekenis.

Categorieën van intents voor Shortcuts