AppIntent: nó là gì, mô hình intent Siri và Swift

AppIntent là gì và tại sao cần nó?

AppIntent là framework của Apple để mô tả khai báo các lệnh mà ứng dụng của bạn có thể thực thi theo yêu cầu từ Siri, Shortcuts, Spotlight, Control Center và Action Button. Nó dựa trên giao thức AppIntent, nơi nhà phát triển mô tả tên intent, tham số của nó và phương thức perform() — logic có thể thực thi. Framework tự động tạo giao diện người dùng để cấu hình tham số trong ứng dụng Shortcuts và cụm từ thoại cho Siri.

Trước AppIntent, các nhà phát triển sử dụng Intents framework — một hệ thống dựa trên tệp Intents Definition File tạo mã Objective-C và yêu cầu thiết lập Intents Extension riêng. Quá trình này rất cồng kềnh: ngay cả một intent đơn giản cũng cần tới 5 tệp cấu hình. AppIntent loại bỏ sự phức tạp này — một intent được mô tả trong một tệp Swift duy nhất và hệ thống tự động tạo mọi thứ cần thiết để tích hợp với Siri và Shortcuts.

Theo phiên WWDC 2024 "Dive deeper into App Intents", Apple coi AppIntent là cơ chế trung tâm để mở rộng chức năng ứng dụng vượt ra ngoài giao diện người dùng truyền thống. Vào thời điểm iOS 18 ra mắt, hơn 70% ứng dụng trong top 100 App Store đã sử dụng AppIntent để tích hợp với Shortcuts và Siri, và người dùng iOS 18 trung bình khởi chạy 4–6 intent mỗi ngày qua lệnh thoại hoặc widget.

AppIntent được sử dụng ở đâu

• Siri — lệnh thoại: "Hey Siri, thêm nhiệm vụ vào MyApp"
• Shortcuts — tự động hóa trong ứng dụng Phím tắt với cấu hình tham số
• Spotlight — tìm kiếm và thực thi lệnh trực tiếp từ thanh tìm kiếm
• Control Center — nút hành động nhanh trên iOS 18+
• Action Button — gán hành động cho nút iPhone 15 Pro và mới hơn

AppIntent vs Intents framework: khác biệt chính

Intents framework (iOS 10–15) yêu cầu tạo tệp .intentdefinition, tạo lớp ObjC/Swift qua Xcode, thiết lập Intents Extension và App Intent Configuration. AppIntent (iOS 16+) thay thế hoàn toàn quy trình này bằng mã Swift thuần túy mà không cần tạo, mở rộng hay cấu hình thêm. Điều này làm cho quy trình tạo intent có thể tiếp cận được với nhà phát triển iOS trung bình mà không cần nghiên cứu SiriKit.

Lợi thế chính của AppIntent là tính khai báo. Nhà phát triển mô tả intent làm gì, không phải nó tích hợp với hệ thống như thế nào. Bản thân framework xử lý các kịch bản hội thoại Siri, hiển thị tham số trong Shortcuts và chuyển ngữ cảnh giữa các intent. Trong Intents framework cũ, mọi khía cạnh tích hợp phải được mã hóa thủ công, bao gồm INUIHostedView để hiển thị giao diện người dùng intent.

So sánh cách tiếp cận

Giao thức chính: AppIntent, AppEntity, AppEnum

AppIntent là giao thức trung tâm xác định một intent. Nó chứa title (tên cho Siri), description (mô tả trong Shortcuts), tham số (qua @Parameter) và phương thức perform() trả về IntentResult. Kết quả có thể là IntentDialog (hội thoại với Siri), giá trị trả về cho Shortcuts hoặc lỗi. Mỗi intent cũng có thể cung cấp suggestedInvocationPhrase — cụm từ để gọi bằng giọng nói.

AppEntity mô tả các thực thể mà intent làm việc. Ví dụ, nếu ứng dụng quản lý dự án, AppEntity Project chứa id, displayRepresentation (cách hiển thị thực thể trong giao diện người dùng) và defaultQuery (cách tìm kiếm thực thể). AppEnum là liệt kê cho tham số lựa chọn tự động tạo giao diện người dùng với phần tử chọn trong Shortcuts. Thay vì tạo danh sách tham số thủ công, chỉ cần khai báo enum tuân thủ AppEnum.

Ví dụ AppEnum và tham số

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

Tham số intent và xác thực của chúng

Các tham số của AppIntent được khai báo qua property wrapper @Parameter, tự động tích hợp với giao diện người dùng Shortcuts và yêu cầu giọng nói Siri. Mỗi tham số có title (hiển thị trong Shortcuts) và có thể bao gồm mô tả, giá trị mặc định và ràng buộc. AppIntent hỗ trợ các loại tiêu chuẩn: String, Int, Double, Bool, cũng như các loại tùy chỉnh qua AppEntity và AppEnum.

Việc xác thực tham số được thực hiện trong phương thức perform() trước khi thực thi logic. Nếu tham số không hợp lệ, intent trả về lỗi qua IntentError. Để xác thực phức tạp, có thể triển khai phương thức validate(), được gọi trước perform() và có thể cung cấp phản hồi cho người dùng qua IntentDialog ngay cả trước khi thực thi lệnh. Điều này đặc biệt hữu ích cho các kịch bản giọng nói Siri, nơi hỏi lại người dùng dễ hơn thực thi lệnh không chính xác.

Tham số với xác thực

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

Tạo intent trong Swift: ví dụ

Một ví dụ hoàn chỉnh về intent tìm kiếm ghi chú trong ứng dụng minh họa làm việc với AppEntity và EntityQuery. SearchNotesIntent nhận chuỗi tìm kiếm và trả về danh sách ghi chú tìm thấy. AppEntity Note mô tả cấu trúc ghi chú và EntityQuery triển khai tìm kiếm trong kho lưu trữ. Kết quả được trả về qua IntentResult với mảng thực thể, Shortcuts hiển thị cho người dùng.

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

Tích hợp với Shortcuts và Siri

Sau khi khai báo AppIntent, việc tích hợp với Shortcuts và Siri diễn ra tự động. Ứng dụng Shortcuts quét tất cả AppIntents từ các ứng dụng đã cài đặt và hiển thị chúng trong danh sách hành động có sẵn. Người dùng có thể thêm intent vào phím tắt của mình, cấu hình tham số và kết hợp với các hành động khác. Đối với Siri, intent xuất hiện dưới dạng lệnh thoại mà không cần thiết lập thêm từ nhà phát triển.

Nhà phát triển có thể cải thiện tích hợp bằng cách thêm suggestedInvocationPhrase — cụm từ được đề xuất để gọi bằng giọng nói. Ví dụ, cho intent thêm nhiệm vụ: suggestedInvocationPhrase = "Add new task". Siri phân tích cụm từ này và đề xuất nó cho người dùng khi học lệnh thoại. Cũng có thể chỉ định categories — danh mục intent (create, view, search, edit), giúp Shortcuts nhóm các hành động theo ý nghĩa.

Danh mục intent cho Shortcuts