Intents Extension: مفاهیم کلیدی و ادغام Siri Intents در iOS

Intents Extension در iOS چیست

Intents Extension یک افزونه برنامه است که به Siri، Shortcuts و سایر سرویس‌های سیستمی اجازه می‌دهد از طریق پروتکل استاندارد INIntentHandler عملکرد برنامه را فراخوانی کنند. وقتی کاربر می‌گوید «سلام Siri، پیامی در پیام‌رسان X ارسال کن»، Siri افزونه مربوطه را فعال می‌کند، پارامترهای درخواست را منتقل می‌کند و نتیجه را برای گفتن دریافت می‌کند.

بر خلاف سایر انواع افزونه‌ها، Intents Extension در پس‌زمینه بدون رابط قابل مشاهده کار می‌کند — Siri خود پاسخ را با صدا یا کارت متنی نمایش می‌دهد. افزونه می‌تواند به صورت اختیاری یک رابط سفارشی از طریق INUIHostedViewProviding ارائه دهد که قبل از اجرای فرمان برای تأیید درون Siri نمایش داده می‌شود.

افزونه به صفحه نمایش دستگاه دسترسی ندارد و نمی‌تواند به طور مستقل اقداماتی را آغاز کند — فقط در پاسخ به درخواست Siri یا Shortcuts. این امر امنیت را تضمین می‌کند: کاربر همیشه کنترل می‌کند که برنامه چه اقداماتی را از طریق دستورات صوتی انجام می‌دهد.

SiriKit و دامنه‌های ایننت

SiriKit فریمورک اپل برای ادغام با Siri است که در iOS 10 معرفی شد. این فریمورک دامنه‌ها را تعریف می‌کند — دسته‌بندی اقداماتی که Siri می‌تواند پردازش کند: پیام‌ها، تماس‌های تلفنی، پرداخت‌ها، لیست‌ها، یادآوری‌ها، عکس‌ها، تمرینات، رزروها و موارد دیگر. هر دامنه مجموعه ثابتی از ایننت‌ها و پاسخ‌ها دارد.

دامنه‌های استاندارد

INSendMessageIntent — ارسال پیام. INStartWorkoutIntent — شروع تمرین. INSearchForPhotosIntent — جستجوی عکس. INRequestRideIntent — سفارش تاکسی. هر دامنه پارامترهای اجباری و اختیاری را تعریف می‌کند که Siri از درخواست صوتی استخراج می‌کند. به گفته اپل، برای دامنه‌های استاندارد فایل intentdefinition لازم نیست — پیاده‌سازی کنترل‌کننده مربوطه کافی است.

برای برنامه‌هایی که در دامنه‌های استاندارد قرار نمی‌گیرند، از iOS 14 امکان اینت‌های سفارشی فراهم شده است. برنامه انواع دستورات و پارامترهای خود را از طریق Intents.intentdefinition تعریف می‌کند و Siri بر اساس مثال‌های ارائه شده توسط توسعه‌دهنده، عبارات مربوطه را تشخیص می‌دهد.

پیکربندی در Info.plist

Intents Extension از طریق کلید IntentsSupported در Info.plist ثبت می‌شود، جایی که تمام کلاس‌های ایننتی که افزونه پردازش می‌کند فهرست می‌شوند. Siri از این لیست برای انتخاب افزونه مناسب هنگام تشخیص فرمان صوتی استفاده می‌کند. اگر چند افزونه از یک ایننت پشتیبانی کنند، Siri به کاربر انتخاب می‌دهد.

class MessageIntentHandler: NSObject,
    INSendMessageIntentHandling {

    func handle(
        intent: INSendMessageIntent,
        completion: @escaping
            (INSendMessageIntentResponse) -> Void
    ) {
        let response = INSendMessageIntentResponse(
            code: .success, userActivity: nil)
        completion(response)
    }
}

INIntentHandler: پردازش درخواست‌ها

INIntentHandler پروتکلی است که متدهایی را برای پردازش هر مرحله از کار ایننت تعریف می‌کند: حل پارامترها، تأیید و اجرا. افزونه این متدها را برای هر نوع ایننتی که پشتیبانی می‌کند پیاده‌سازی می‌کند.

سه مرحله پردازش

resolve — بررسی و دقیق‌کردن پارامترهای ایننت. Siri این متد را برای هر پارامتر فراخوانی می‌کند. اگر پارامتری مشخص نشده یا نادرست باشد، افزونه درخواست دقیق‌کردن را برمی‌گرداند و Siri سؤال اضافی از کاربر می‌پرسد. confirm — تأیید قصد. افزونه بررسی می‌کند که آیا می‌تواند ایننت را در زمینه فعلی اجرا کند. handle — اجرای واقعی عملیات و بازگرداندن نتیجه.

تقسیم به سه مرحله برای تجربه کاربری صوتی حیاتی است: اگر پارامتری تشخیص داده نشود، Siri عمل را انجام نمی‌دهد بلکه دوباره می‌پرسد. مثلاً اگر کاربر گفت «به الکسی پیام بده» اما در مخاطبین سه الکسی وجود دارد — افزونه resolve با درخواست دقیق‌کردن برمی‌گرداند و Siri می‌پرسد «کدام الکسی؟».

INIntentResponse و وضعیت‌ها

INIntentResponse شیئی است که افزونه پس از اجرای ایننت در completion برمی‌گرداند. Response شامل کد نتیجه (success، failure، requiresAuthentication، inProgress) و داده‌های اختیاری برای گفتن توسط Siri است. کد نحوه واکنش Siri را تعیین می‌کند: success — تأیید صوتی، failure — پیام خطا، inProgress — نشان‌دهنده عملیات طولانی.

func resolve(
    for intent: INSendMessageIntent,
    with completion: @escaping
        (INStringResolutionResult) -> Void
) {
    if let text = intent.content, !text.isEmpty {
        completion(.success(with: text))
    } else {
        completion(.needsValue())
    }
}

ایجاد ایننت‌های سفارشی

از iOS 14 توسعه‌دهندگان امکان تعریف اینت‌های خود را خارج از دامنه‌های استاندارد SiriKit به دست آوردند. ایننت‌های سفارشی در فایل Intents.intentdefinition توضیح داده می‌شوند — این یک ویرایشگر بصری درون Xcode است که در آن انواع جدیدی از دستورات با پارامترها و پاسخ‌ها ایجاد می‌شوند.

ساختار ایننت سفارشی

هر ایننت سفارشی از INIntent (تعریف درخواست) و INIntentResponse (تعریف پاسخ) تشکیل شده است. INIntent شامل پارامترهایی با نوع داده — String، Integer، CurrencyAmount، اشیاء یافت شده و موارد دیگر است. INIntentResponse شامل ویژگی‌هایی برای بازگرداندن نتیجه و آرایه‌ای از کدهای پاسخ است. Xcode به طور خودکار کلاس‌های Swift را بر اساس این تعریف تولید می‌کند.

اپل توصیه می‌کند که ایننت سفارشی بیش از 5 پارامتر نداشته باشد — تعداد زیاد تشخیص صدا را کاهش می‌دهد و تجربه کاربر را پیچیده می‌کند. برای هر پارامتر بهتر است نمونه عبارات در Assistant Dialog ارائه شود تا Siri تشخیص صحیح را بیاموزد.

نمونه عبارات برای Siri

در Intents.intentdefinition برای هر ایننت می‌توان جملات نمونه مشخص کرد — عباراتی که کاربر برای فعال‌سازی ایننت به Siri خواهد گفت. مثال‌ها: «در برنامه من قهوه سفارش بده»، «از برنامه من بخواه دستور پیتزا پیدا کند». Siri از این عبارات برای یادگیری تشخیص استفاده می‌کند و هنگام تنظیم Shortcuts به کاربر پیشنهاد می‌دهد.

// Intents.intentdefinition (ویرایشگر بصری)
Intent: OrderCoffeeIntent
Parameters:
  - beverage (String)
  - size (String)
  - quantity (Integer)
Response:
  - orderNumber (String)
  - price (CurrencyAmount)
Phrases:
  - "Order coffee in MyApp"
  - "Get a latte from MyApp"

تعامل صوتی و INUIHostedViewProviding

INUIHostedViewProviding پروتکلی است که به Intents Extension اجازه می‌دهد قبل از اجرای فرمان، رابط سفارشی را درون Siri نمایش دهد. مثلاً هنگام سفارش تاکسی، افزونه می‌تواند نقشه‌ای با مسیر و هزینه نمایش دهد و کاربر عمل را با لمس تأیید کند.

پیکربندی رابط

پروتکل متد configure(with:for:completion:) را تعریف می‌کند که در آن افزونه ایننت را دریافت کرده و UIViewController را برمی‌گرداند که در Siri جاسازی می‌شود. اندازه کنترل‌کننده محدود است — حداکثر ارتفاع 200 نقطه. استفاده از کارت‌های فشرده با اطلاعات کلیدی توصیه می‌شود: مبلغ، زمان، آدرس.

رابط سفارشی اختیاری است — اگر افزونه INUIHostedViewProviding را پیاده‌سازی نکند، Siri یک کارت استاندارد با نوع ایننت و برنامه نمایش می‌دهد. برای بیشتر ایننت‌ها UI استاندارد کافی است و اپل توصیه می‌کند فقط زمانی رابط سفارشی اضافه شود که واقعاً درک را بهبود می‌بخشد — مثلاً برای نمایش مسیر یا تأیید پرداخت.

امنیت و تأیید

برای ایننت‌های مرتبط با امور مالی یا داده‌های شخصی احراز هویت لازم است. INIntentResponse از کد requiresAuthentication پشتیبانی می‌کند که Siri را وادار می‌کند قبل از اجرا Face ID یا Touch ID را درخواست کند. پس از احراز هویت، افزونه تأیید را از طریق فراخوانی جداگانه‌ای به نام handle دریافت می‌کند که در آن وضعیت احراز هویت بررسی می‌شود.

اپل به طور ویژه تأکید می‌کند: Intents Extension نباید رمز عبور یا بیومتریک خود را درخواست کند — از احراز هویت سیستمی استفاده می‌شود. ذخیره توکن‌های دسترسی در Keychain با دسترسی مشترک بین برنامه و افزونه، روش استاندارد برای نشست‌های طولانی مدت است.

class IntentViewController: UIViewController {

    func configure(
        with intent: INIntent,
        completion: @escaping
            (UIViewController?) -> Void
    ) {
        let cardView = ConfirmationCardView()
        let hostingController =
            UIHostingController(rootView: cardView)
        completion(hostingController)
    }
}