AppIntent: ano ito, modelo ng Siri intents at Swift

Ano ang AppIntent at para saan ito?

AppIntent — framework ng Apple para sa declarative na paglalarawan ng mga command na maaaring isagawa ng iyong app sa kahilingan ng Siri, Shortcuts, Spotlight, Control Center at Action Button. Sa pundasyon nito ay ang protocol na AppIntent, kung saan inilalarawan ng developer ang pangalan ng intent, mga parameter nito at method na perform() — ang lohika na isasagawa. Awtomatikong gumagawa ang framework ng user interface para sa pag-configure ng mga parameter sa Shortcuts app at mga voice phrase para sa Siri.

Bago ang pagdating ng AppIntent, gumamit ang mga developer ng Intents framework — isang sistema batay sa Intent Definition File, na gumagawa ng Objective-C code at nangangailangan ng pag-configure ng hiwalay na Intents Extension. Ang prosesong ito ay masalimuot: kahit isang simpleng intent ay nangangailangan ng hanggang 5 configuration file. AppIntent ay nag-aalis ng pagiging kumplikadong ito — ang intent ay inilalarawan sa isang Swift file, at awtomatikong ginagawa ng system ang lahat ng kailangan para sa pagsasama sa Siri at Shortcuts.

Ayon sa WWDC 2024 Session “Dive deeper into App Intents”, nakikita ng Apple ang AppIntent bilang sentral na mekanismo para sa pagpapalawak ng functionality ng app sa labas ng tradisyonal na UI. Sa oras ng paglabas ng iOS 18, mahigit 70% ng mga app sa top 100 ng App Store ay gumagamit na ng AppIntent para sa pagsasama sa Shortcuts at Siri, at ang average na user ng iOS 18 ay nagpapatakbo ng 4–6 intent bawat araw sa pamamagitan ng voice command o widget.

Saan ginagamit ang AppIntent

• Siri — voice command: “Hey Siri, magdagdag ng gawain sa MyApp”
• Shortcuts — automation sa Shortcuts app na may configuration ng parameter
• Spotlight — paghahanap at pagsasagawa ng mga command diretso mula sa search bar
• Control Center — mga button ng mabilisang aksyon sa iOS 18+
• Action Button — configuration ng aksyon para sa button ng iPhone 15 Pro at mas bago

AppIntent vs Intents framework: mga pangunahing pagkakaiba

Intents framework (iOS 10–15) ay nangangailangan ng paggawa ng .intentdefinition file, pag-generate ng ObjC/Swift classes sa pamamagitan ng Xcode, pag-configure ng Intents Extension at App Intent Configuration. Ang AppIntent (iOS 16+) ay ganap na pinapalitan ang pipeline na ito ng purong Swift code nang walang generation, extension at karagdagang configuration. Ginagawa nitong accessible ang proseso ng paggawa ng intents para sa average na iOS developer nang hindi kinakailangang matuto ng SiriKit.

Ang pangunahing bentahe ng AppIntent ay ang pagiging declarative nito. Inilalarawan ng developer kung ano ang ginagawa ng intent, hindi kung paano ito isinasama sa system. Ang framework mismo ang humahawak sa Siri dialog scenarios, pagpapakita ng mga parameter sa Shortcuts at paglilipat ng konteksto sa pagitan ng intents. Sa lumang Intents framework, bawat aspeto ng pagsasama ay kailangang manual na i-code, kabilang ang INUIHostedView para sa pagpapakita ng UI ng intent.

Paghahambing ng mga approach

Mga pangunahing protocol: AppIntent, AppEntity, AppEnum

AppIntent — sentral na protocol na nagdedefine ng intent. Naglalaman ito ng title (pangalan para sa Siri), description (paglalarawan sa Shortcuts), mga parameter (sa pamamagitan ng @Parameter) at method na perform() na nagbabalik ng IntentResult. Ang resulta ay maaaring IntentDialog (dialog sa Siri), value na ibabalik sa Shortcuts o error. Bawat intent ay maaari ring magbigay ng suggestedInvocationPhrase — parirala para sa voice call.

AppEntity ay naglalarawan ng mga entity na ginagamit ng intents. Halimbawa, kung ang app ay namamahala ng mga proyekto, ang AppEntity Project ay naglalaman ng id, displayRepresentation (kung paano ipapakita ang entity sa UI) at defaultQuery (kung paano hahanapin ang mga entity). AppEnum — enumeration para sa mga parameter ng pagpili na awtomatikong gumagawa ng UI na may picker element sa Shortcuts. Sa halip na manual na gumawa ng listahan ng parameter, sapat na ang magdeklara ng enum na sumusunod sa AppEnum.

Halimbawa ng AppEnum at 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")
    }
}

Mga parameter ng intent at ang kanilang validation

Ang mga parameter ng AppIntent ay dineklara sa pamamagitan ng property wrapper na @Parameter, na awtomatikong sumasama sa Shortcuts UI at Siri voice requests. Bawat parameter ay may title (ipinapakita sa Shortcuts) at maaaring maglaman ng paglalarawan, default values, limitasyon. Sinusuportahan ng AppIntent ang standard types: String, Int, Double, Bool, pati na rin ang custom types sa pamamagitan ng AppEntity at AppEnum.

Ang validation ng parameter ay ginagawa sa method na perform() bago isagawa ang lohika. Kung ang mga parameter ay hindi wasto, ang intent ay nagbabalik ng error sa pamamagitan ng IntentError. Para sa complex validation, maaaring i-implement ang method na validate(), na tinatawag bago ang perform() at maaaring magbigay ng feedback sa user sa pamamagitan ng IntentDialog kahit bago pa isagawa ang command. Ito ay lalong kapaki-pakinabang sa Siri voice scenarios, kung saan mas madaling tanungin muli ang user kaysa isagawa ang maling command.

Mga parameter na may validation

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

Paggawa ng intent sa Swift: halimbawa

Isang kumpletong halimbawa ng intent para sa paghahanap ng mga tala sa isang app ay nagpapakita ng trabaho sa AppEntity at EntityQuery. Ang intent na SearchNotesIntent ay tumatanggap ng search string at nagbabalik ng listahan ng mga nahanap na tala. Ang AppEntity Note ay naglalarawan ng structure ng tala, at ang EntityQuery ay nag-i-implement ng paghahanap sa imbakan. Ang resulta ay ibinabalik sa pamamagitan ng IntentResult na may array ng entities, na ipinapakita ng Shortcuts sa user.

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

Pagsasama sa Shortcuts at Siri

Pagkatapos ideklara ang AppIntent, ang pagsasama sa Shortcuts at Siri ay awtomatikong nangyayari. Ang Shortcuts app ay nag-scan ng lahat ng AppIntent mula sa mga naka-install na app at ipinapakita ang mga ito sa listahan ng mga available na aksyon. Maaaring idagdag ng user ang intent sa kanyang command, i-configure ang mga parameter nito at pagsamahin sa iba pang aksyon. Para sa Siri, lumalabas ang intents bilang voice command nang walang karagdagang configuration mula sa developer.

Maaaring pagbutihin ng developer ang pagsasama sa pamamagitan ng pagdaragdag ng suggestedInvocationPhrase — inirerekomendang parirala para sa voice call. Halimbawa, para sa intent ng pagdaragdag ng gawain: suggestedInvocationPhrase = "Add new task". Sinusuri ng Siri ang pariralang ito at iniaalok ito sa user habang natututo ng voice command. Maaari ring tukuyin ang categories — kategorya ng intent (create, view, search, edit), na tumutulong sa Shortcuts na igrupo ang mga aksyon ayon sa kahulugan.

Mga kategorya ng intent para sa Shortcuts