AppIntent: این چیست، مدل اینتنت‌های Siri و Swift

AppIntent چیست و به چه کاری می‌آید؟

AppIntent — چارچوب Apple برای توصیف اعلامی دستوراتی که برنامه شما می‌تواند به درخواست Siri، Shortcuts، Spotlight، Control Center و Action Button انجام دهد. در پایه آن پروتکل AppIntent قرار دارد که در آن توسعه‌دهنده نام اینتنت، پارامترها و روش perform() — منطق اجرایی را توصیف می‌کند. چارچوب به طور خودکار رابط کاربری برای تنظیم پارامترها در برنامه Shortcuts و عبارات صوتی برای Siri تولید می‌کند.

قبل از ایجاد AppIntent، توسعه‌دهندگان از Intents framework استفاده می‌کردند — سیستمی مبتنی بر Intent Definition File که کد Objective-C تولید می‌کرد و نیازمند تنظیم Intents Extension جداگانه بود. این فرآیند پیچیده بود: حتی یک اینتنت ساده تا 5 فایل پیکربندی نیاز داشت. AppIntent این پیچیدگی را برطرف می‌کند — اینتنت در یک فایل Swift توصیف می‌شود و سیستم به طور خودکار هر چیز لازم برای یکپارچگی با Siri و Shortcuts را تولید می‌کند.

به گزارش WWDC 2024 Session «Dive deeper into App Intents»، Apple AppIntent را به عنوان مکانیسم مرکزی برای افزایش کارکرد برنامه‌ها در ورای UI سنتی می‌بیند. تا زمان انتشار iOS 18، بیش از 70% برنامه‌های بین ۱۰۰ برتر App Store قبلاً از AppIntent برای یکپارچگی با Shortcuts و Siri استفاده می‌کنند و کاربر معمولی iOS 18 روزانه 4–6 اینتنت از طریق دستورات صوتی یا واجت‌ها اجرا می‌کند.

AppIntent در کجا استفاده می‌شود

• Siri — دستورات صوتی: «Hey Siri، یک وظیفه به MyApp اضافه کن»
• Shortcuts — خودکارسازی در برنامه میانبرها با تنظیم پارامترها
• Spotlight — جستجو و اجرای دستورات مستقیماً از نوبار جستجو
• Control Center — دکمه‌های اقدام سریع در iOS 18+
• Action Button — تنظیم اقدام برای دکمه iPhone 15 Pro و جدیدتر

AppIntent در مقابل Intents framework: تفاوت‌های کلیدی

Intents framework (iOS 10–15) نیازمند ایجاد فایل .intentdefinition، تولید کلاس‌های ObjC/Swift توسط Xcode، تنظیم Intents Extension و App Intent Configuration بود. AppIntent (iOS 16+) کاملاً این خط لوله را با کد Swift خالص بدون تولید، افزایش و پیکربندی‌های اضافی جایگزین می‌کند. این فرآیند ایجاد اینتنت را برای توسعه‌دهنده معمولی iOS بدون یادگیری SiriKit قابل دسترس می‌سازد.

مزیت کلیدی AppIntent اعلامی بودن آن است. توسعه‌دهنده توصیف می‌کند که اینتنت چه کاری انجام می‌دهد، نه اینکه چگونه با سیستم یکپارچه می‌شود. چارچوب خود سناریوهای گفتگویی Siri، نمایش پارامترها در Shortcuts و انتقال زمینه بین اینتنت‌ها را مدیریت می‌کند. در Intents framework قدیمی، هر جنبه از یکپارچگی باید دستی کدنویسی می‌شد، از جمله INUIHostedView برای نمایش UI اینتنت.

مقایسه رویکردها

پروتکل‌های اصلی: AppIntent، AppEntity، AppEnum

AppIntent — پروتکل مرکزی که اینتنت را تعریف می‌کند. آن شامل title (نام برای Siri)، description (توضیح در Shortcuts)، پارامترها (از طریق @Parameter) و روش perform() است که IntentResult بازمی‌گرداند. نتیجه می‌تواند IntentDialog (گفتگو با Siri)، مقدار بازگشتی به Shortcuts یا خطا باشد. هر اینتنت می‌تواند همچنین suggestedInvocationPhrase — عبارت برای فراخوان صوتی ارائه دهد.

AppEntity نهادهایی را که اینتنت‌ها با آن‌ها کار می‌کنند توصیف می‌کند. به عنوان مثال، اگر برنامه پروژه‌ها را مدیریت می‌کند، AppEntity Project شامل id، displayRepresentation (چگونگی نمایش نهاد در UI) و defaultQuery (چگونگی جستجوی نهادها) است. AppEnum — شمارش برای پارامترهای انتخابی که به طور خودکار UI با عنصر picker در Shortcuts تولید می‌کند. به جای ایجاد دستی لیست پارامترها، کافی است enumی مطابق با AppEnum اعلام کنید.

مثال AppEnum و پارامتر

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

پارامترهای اینتنت و اعتبارسنجی آنها

پارامترهای AppIntent از طریق property wrapper @Parameter اعلام می‌شوند که به طور خودکار با UI Shortcuts و درخواست‌های صوتی Siri یکپارچه می‌شود. هر پارامتر دارای title (در Shortcuts نمایش داده می‌شود) است و می‌تواند شامل توضیح، مقادیر پیش‌فرض، محدودیت‌ها باشد. AppIntent از انواع استاندارد: String، Int، Double، Bool و همچنین انواع سفارشی از طریق AppEntity و AppEnum پشتیبانی می‌کند.

اعتبارسنجی پارامترها در روش perform() قبل از اجرای منطق انجام می‌شود. اگر پارامترها نامناسب باشند، اینتنت با IntentError خطا بازمی‌گرداند. برای اعتبارسنجی پیچیده، می‌توان روش validate() را پیاده‌سازی کرد که قبل از perform() فراخوانده می‌شود و می‌تواند از طریق IntentDialog بازخورد را به کاربر حتی قبل از اجرای دستور ارائه دهد. این به ویژه در سناریوهای صوتی Siri مفید است که دوباره پرسیدن از کاربر آسان‌تر از اجرای یک دستور نادرست است.

پارامترها با اعتبارسنجی

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

ایجاد اینتنت در Swift: مثال

مثال کامل اینتنت برای جستجوی یادداشت‌ها در برنامه کار با AppEntity و EntityQuery را نشان می‌دهد. Intent SearchNotesIntent یک رشته جستجو می‌گیرد و لیستی از یادداشت‌های پیدا شده را بازمی‌گرداند. AppEntity Note ساختار یادداشت را توصیف می‌کند و EntityQuery جستجو در ذخیره را پیاده‌سازی می‌کند. نتیجه از طریق IntentResult با مجموعه‌ای از نهادها بازگردانده می‌شود که Shortcuts به کاربر نمایش می‌دهد.

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

یکپارچگی با Shortcuts و Siri

پس از اعلام AppIntent، یکپارچگی با Shortcuts و Siri به طور خودکار انجام می‌شود. برنامه Shortcuts تمام AppIntent-های برنامه‌های نصب شده را اسکن می‌کند و آن‌ها را در لیست اقدامات موجود نمایش می‌دهد. کاربر می‌تواند اینتنت را به دستور خود اضافه کند، پارامترهای آن را تنظیم کند و با سایر اقدامات ترکیب کند. برای Siri، اینتنت‌ها بدون تنظیم اضافی از طرف توسعه‌دهنده به عنوان دستورات صوتی ظاهر می‌شوند.

توسعه‌دهنده می‌تواند با افزودن suggestedInvocationPhrase — عبارت پیشنهادی برای فراخوان صوتی یکپارچگی را بهبود بخشد. به عنوان مثال برای اینتنت افزودن وظیفه: suggestedInvocationPhrase = "Add new task". Siri این عبارت را تحلیل می‌کند و آن را در زمان یادگیری دستورات صوتی به کاربر پیشنهاد می‌دهد. همچنین می‌توان categories — دسته‌بندی اینتنت (create, view, search, edit) را مشخص کرد که به Shortcuts کمک می‌کند اقدامات را بر اساس معنا گروه‌بندی کند.

دسته‌بندی اینتنت‌ها برای Shortcuts