AppIntent: czym jest, model intentów Siri i Swift

Czym jest AppIntent i do czego służy?

AppIntent — framework Apple do deklaratywnego opisywania poleceń, które Twoja aplikacja może wykonywać na żądanie Siri, Shortcuts, Spotlight, Control Center i Action Button. U podstaw leży protokół AppIntent, w którym deweloper opisuje nazwę intentu, jego parametry i metodę perform() — wykonywaną logikę. Framework automatycznie generuje interfejs użytkownika do konfiguracji parametrów w aplikacji Shortcuts oraz frazy głosowe dla Siri.

Przed pojawieniem się AppIntent deweloperzy używali Intents framework — systemu opartego na pliku Intents Definition File, który generował kod Objective-C i wymagał konfiguracji osobnego Intents Extension. Proces ten był uciążliwy: nawet prosty intent wymagał do 5 plików konfiguracyjnych. AppIntent eliminuje tę złożoność — intent jest opisywany w jednym pliku Swift, a system automatycznie generuje wszystko, co niezbędne do integracji z Siri i Shortcuts.

Według WWDC 2024 Session „Dive deeper into App Intents“, Apple postrzega AppIntent jako centralny mechanizm rozszerzania funkcjonalności aplikacji poza tradycyjny UI. Do czasu wydania iOS 18 ponad 70% aplikacji z top 100 App Store już używa AppIntent do integracji z Shortcuts i Siri, a przeciętny użytkownik iOS 18 uruchamia 4–6 intentów dziennie za pomocą poleceń głosowych lub widgetów.

Gdzie są używane AppIntent

• Siri — polecenia głosowe: „Hey Siri, dodaj zadanie w MyApp“
• Shortcuts — automatyzacja w aplikacji Skróty z konfiguracją parametrów
• Spotlight — wyszukiwanie i wykonywanie poleceń bezpośrednio z paska wyszukiwania
• Control Center — przyciski szybkiego działania na iOS 18+
• Action Button — konfiguracja działania na przycisk iPhone 15 Pro i nowsze

AppIntent vs Intents framework: kluczowe różnice

Intents framework (iOS 10–15) wymagał utworzenia pliku .intentdefinition, generowania klas ObjC/Swift przez Xcode, konfiguracji Intents Extension i App Intent Configuration. AppIntent (iOS 16+) całkowicie zastępuje ten potok czystym kodem Swift bez generowania, rozszerzeń i dodatkowych konfiguracji. To sprawia, że proces tworzenia intentów jest dostępny dla przeciętnego dewelopera iOS bez znajomości SiriKit.

Kluczową zaletą AppIntent jest deklaratywność. Deweloper opisuje co robi intent, a nie jak jest integrowany z systemem. Framework sam obsługuje scenariusze dialogowe Siri, wyświetlanie parametrów w Shortcuts i przekazywanie kontekstu między intentami. W starym Intents framework każdy aspekt integracji trzeba było kodować ręcznie, włączając INUIHostedView do wyświetlania UI intentu.

Porównanie podejść

Podstawowe protokoły: AppIntent, AppEntity, AppEnum

AppIntent — centralny protokół, który definiuje intent. Zawiera title (nazwę dla Siri), description (opis w Shortcuts), parametry (przez @Parameter) i metodę perform() zwracającą IntentResult. Wynikiem może być IntentDialog (dialog z Siri), wartość do zwrócenia w Shortcuts lub błąd. Każdy intent może również dostarczać suggestedInvocationPhrase — frazę do wywołania głosowego.

AppEntity opisuje encje, z którymi pracują intenty. Na przykład, jeśli aplikacja zarządza projektami, AppEntity Project zawiera id, displayRepresentation (jak wyświetlać encję w UI) i defaultQuery (jak wyszukiwać encje). AppEnum — wyliczenie dla parametrów wyboru, które automatycznie generuje UI z elementem picker w Shortcuts. Zamiast ręcznego tworzenia listy parametrów wystarczy zadeklarować enum, conforming do AppEnum.

Przykład 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")
    }
}

Parametry intentów i ich walidacja

Parametry AppIntent są deklarowane przez property wrapper @Parameter, który automatycznie integruje się z UI Shortcuts i zapytaniami głosowymi Siri. Każdy parametr ma title (wyświetlany w Shortcuts) i może zawierać opis, wartości domyślne, ograniczenia. AppIntent obsługuje standardowe typy: String, Int, Double, Bool, a także niestandardowe typy przez AppEntity i AppEnum.

Walidacja parametrów jest wykonywana w metodzie perform() przed wykonaniem logiki. Jeśli parametry są nieprawidłowe, intent zwraca błąd przez IntentError. Do złożonej walidacji można zaimplementować metodę validate(), która jest wywoływana przed perform() i może dostarczyć informację zwrotną użytkownikowi przez IntentDialog jeszcze przed wykonaniem polecenia. Jest to szczególnie przydatne w scenariuszach głosowych Siri, gdzie łatwiej jest dopytać użytkownika niż wykonać nieprawidłowe polecenie.

Parametry z walidacją

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

Tworzenie intentu w Swift: przykład

Pełny przykład intentu do wyszukiwania notatek w aplikacji demonstruje pracę z AppEntity i EntityQuery. Intent SearchNotesIntent przyjmuje ciąg wyszukiwania i zwraca listę znalezionych notatek. AppEntity Note opisuje strukturę notatki, a EntityQuery implementuje wyszukiwanie w magazynie. Wynik jest zwracany przez IntentResult z tablicą encji, którą Shortcuts wyświetla użytkownikowi.

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

Integracja z Shortcuts i Siri

Po zadeklarowaniu AppIntent integracja z Shortcuts i Siri następuje automatycznie. Aplikacja Shortcuts skanuje wszystkie AppIntent-y z zainstalowanych aplikacji i wyświetla je na liście dostępnych działań. Użytkownik może dodać intent do swojego polecenia, skonfigurować jego parametry i połączyć z innymi działaniami. Dla Siri intenty pojawiają się jako polecenia głosowe bez dodatkowej konfiguracji ze strony dewelopera.

Deweloper może poprawić integrację, dodając suggestedInvocationPhrase — zalecaną frazę do wywołania głosowego. Na przykład dla intentu dodawania zadania: suggestedInvocationPhrase = "Add new task". Siri analizuje tę frazę i proponuje ją użytkownikowi podczas nauki poleceń głosowych. Można również określić categories — kategorię intentu (create, view, search, edit), która pomaga Shortcuts grupować działania według znaczenia.

Kategorie intentów dla Shortcuts