AppIntent: mi ez, a Siri intenzők modellje és Swift

Mi az AppIntent és mire használjuk?

AppIntent — Apple keretrendszer azon parancsok deklaratív leírására, amelyeket alkalmazása végrehajthat Siri, Shortcuts, Spotlight, Control Center és Action Button kérésére. Alapjául az AppIntent protokoll szolgál, amelyben a fejlesztő leírja az intenz nevét, paramétereit és a perform() metódust — a végrehajtandó logikát. A keretrendszer automatikusan generalája a felhasználói felületet a paraméterek konfigurálásához a Shortcuts alkalmazásban és a hangutasításokat a Siri számára.

Az AppIntent megjelenése előtt a fejlesztők az Intents framework-ot használták — egy Intent Definition File-on alapuló rendszert, amely Objective-C kódot generált és külön Intents Extension konfigurálását igényelte. Ez a folyamat bonyolult volt: még egy egyszerű intenz is akár 5 konfigurációs fájlt igényelt. AppIntent küszöböli ki ezt a bonyolultságot — az intenz egyetlen Swift fájlban van leírva, és a rendszer automatikusan generalál mindent, ami a Siri és Shortcuts integrációhoz szükséges.

A WWDC 2024 „Dive deeper into App Intents” session szerint az Apple az AppIntent-et tekinti az alkalmazások funkcionalitásának hagyományos UI-n túli kiterjesztésének központi mechanizmusaként. Az iOS 18 megjelenésére a top 100 App Store alkalmazás több mint 70%-a már AppIntent-et használ a Shortcuts és Siri integrációhoz, és az átlagos iOS 18 felhasználó naponta 4–6 intenzt indít hangutasításokkal vagy widgetekkel.

Hol használjuk az AppIntent-et

• Siri — hangutasítások: „Hey Siri, adj hozzá feladatot a MyApp-ben”
• Shortcuts — automatizálás a Parancsok alkalmazásban paraméterkonfigurációval
• Spotlight — parancsok keresése és végrehajtása közvetlenül a keresősávból
• Control Center — gyorsművelet gombok iOS 18+ rendszeren
• Action Button — művelet konfigurálása az iPhone 15 Pro és újabb készülékek gombjához

AppIntent vs Intents framework: fő különbségek

Intents framework (iOS 10–15) megkövetelte a .intentdefinition fájl létrehozását, ObjC/Swift osztályok generalását Xcode-on keresztül, Intents Extension és App Intent Configuration konfigurálását. Az AppIntent (iOS 16+) teljesen helyettesíti ezt a csœvezetéket tiszta Swift kóddal generalás, kiterjesztések és további konfigurációk nélkül. Ez az intenzek létrehozásának folyamatát elérhetővé teszi az átlagos iOS fejlesztő számára is, anélkül, hogy meg kellene tanulnia a SiriKit-et.

Az AppIntent fő előnye a deklaratív jelleg. A fejlesztő leírja, mit csinál az intenz, nem azt, hogy hogyan integrálódik a rendszerrel. A keretrendszer maga kezeli a Siri párbeszéd forgatókönyveket, a paraméterek megjelenítését a Shortcuts-ban és a kontextus átadását az intenzek között. A régi Intents framework-ban az integráció minden aspektusát kézzel kellett kódolni, beleértve az INUIHostedView-t az intenz UI megjelenítéséhez.

Megközelítések összehasonlítása

Fő protokollok: AppIntent, AppEntity, AppEnum

AppIntent — központi protokoll, amely meghatározza az intenzet. Tartalmazza a title-t (név a Siri számára), description-t (leírás a Shortcuts-ban), paramétereket (@Parameter-en keresztül) és a perform() metódust, amely IntentResult-ot ad vissza. Az eredmény lehet IntentDialog (párbeszéd Siri-vel), érték a Shortcuts-ba való visszaküldéshez vagy hiba. Minden intenz megadhat suggestedInvocationPhrase-t — egy kifejezést a hanghíváshoz.

AppEntity leírja azokat az entitásokat, amelyekkel az intenzek dolgoznak. Például, ha az alkalmazás projekteket kezel, az AppEntity Project tartalmazza az id-t, displayRepresentation-t (hogyan jelenítse meg az entitást a UI-ban) és defaultQuery-t (hogyan keresse az entitásokat). AppEnum — felsorolás választási paraméterekhez, amely automatikusan UI-t generál egy picker elemmel a Shortcuts-ban. Ahelyett, hogy kézzel hozna létre egy paraméterlistát, elég deklarálni egy enumot, amely megfelel az AppEnum-nak.

Példa AppEnum és paraméter

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

Intenz paraméterek és érvényesítésük

Az AppIntent paraméterek a @Parameter property wrapper-en keresztül kerülnek deklarálásra, amely automatikusan integrálódik a Shortcuts UI-val és a Siri hangkérésekkel. Minden paraméter rendelkezik title-lel (megjelenítve a Shortcuts-ban), és tartalmazhat leírást, alapértelmezett értékeket, korlátozásokat. Az AppIntent támogatja a szabvány típusokat: String, Int, Double, Bool, valamint az egyéni típusokat AppEntity és AppEnum segítségével.

A paraméterek érvényesítése a perform() metódusban történik a logika végrehajtása előtt. Ha a paraméterek helytelenek, az intenz IntentError-on keresztül hibát ad vissza. Összetett érvényesítéshez implementálható a validate() metódus, amely a perform() előtt hívódik meg, és visszajelzést adhat a felhasználónak IntentDialog-on keresztül még a parancs végrehajtása előtt. Ez különösen hasznos a Siri hangforgatókönyvekben, ahol könnyebb újrakérdezni a felhasználót, mint végrehajtani egy helytelen parancsot.

Paraméterek érvényesítéssel

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

Intenz létrehozása Swift-ben: példa

Egy teljes példa jegyzetek keresésére egy alkalmazásban bemutatja a munkát AppEntity-vel és EntityQuery-vel. A SearchNotesIntent intenz fogad egy keresőszöveget, és visszaadja a talált jegyzetek listáját. Az AppEntity Note leírja a jegyzet szerkezetét, az EntityQuery pedig megvalósítja a keresést a tárban. Az eredmény az IntentResult-on keresztül kerül vissza entitások tömbjével, amelyet a Shortcuts megjelenít a felhasználónak.

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

Integráció Shortcuts és Siri között

Az AppIntent deklarálása után a Shortcuts-szal és Siri-vel való integráció automatikusan megtörténik. A Shortcuts alkalmazás beolvassa az összes AppIntent-et a telepített alkalmazásokból, és megjeleníti azokat az elérhető műveletek listájában. A felhasználó hozzáadhatja az intenzt a saját parancsához, konfigurálhatja a paramétereit és kombinálhatja más műveletekkel. Siri számára az intenzek hangutasításként jelennek meg, a fejlesztő részéről többletkonfiguráció nélkül.

A fejlesztő javíthatja az integrációt suggestedInvocationPhrase hozzáadásával — egy ajánlott kifejezés a hanghíváshoz. Például egy feladat hozzáadására szolgáló intenz esetén: suggestedInvocationPhrase = "Add new task". A Siri elemzi ezt a kifejezést, és felajánálja a felhasználónak a hangutasítások tanulása során. Szintén megadható a categories — az intenz kategóriája (create, view, search, edit), amely segíti a Shortcuts-ot a műveletek jelentés szerinti csoportosításában.

Intenz kategóriák a Shortcuts számára