Intents Extension: المفاهيم الأساسية وتكامل Siri Intents في iOS

ما هو Intents Extension في iOS

Intents Extension هو إضافة تطبيق تسمح لـ Siri و Shortcuts وخدمات النظام الأخرى باستدعاء وظائف التطبيق من خلال البروتوكول الموحد INIntentHandler. عندما يقول المستخدم «يا Siri، أرسل رسالة في Messenger X»، تقوم Siri بتنشيط الإضافة المقابلة، وتمرير معلمات الطلب، وتلقي النتيجة للنطق بها.

على عكس الأنواع الأخرى من الإضافات، يعمل Intents Extension في الخلفية بدون واجهة مرئية — تعرض Siri الرد عبر الصوت أو بطاقة نصية. يمكن للإضافة اختياريًا توفير واجهة مستخدم مخصصة عبر INUIHostedViewProviding، والتي يتم عرضها داخل Siri قبل تنفيذ الأمر للتأكيد.

الإضافة لا تملك وصولاً إلى شاشة الجهاز ولا يمكنها بدء الإجراءات بنفسها — فقط استجابة لطلب من Siri أو Shortcuts. هذا يضمن الأمان: يتحكم المستخدم دائمًا في الإجراءات التي ينفذها التطبيق عبر الأوامر الصوتية.

SiriKit ومجالات الأوامر

SiriKit هو إطار عمل Apple للتكامل مع Siri، الذي تم تقديمه في iOS 10. يحدد مجالات — فئات الإجراءات التي يمكن لـ Siri معالجتها: الرسائل، المكالمات الهاتفية، المدفوعات، القوائم، التذكيرات، الصور، التمارين، الحجوزات وغيرها. كل مجال لديه مجموعة ثابتة من الأوامر والردود.

المجالات القياسية

INSendMessageIntent — إرسال الرسائل. INStartWorkoutIntent — بدء التمرين. INSearchForPhotosIntent — البحث عن الصور. INRequestRideIntent — طلب رحلة. كل مجال يحدد معلمات إلزامية واختيارية يستخرجها Siri من الطلب الصوتي. وفقًا لـ Apple، لا تتطلب المجالات القياسية ملف 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 الإجراء بل تطلب توضيحًا. على سبيل المثال، إذا قال المستخدم «أرسل رسالة إلى Alex» ولكن هناك ثلاثة Alex في جهات الاتصال — تعيد الإضافة resolve مع طلب توضيح، وتسأل Siri «أي Alex؟»

INIntentResponse ورموز الحالة

INIntentResponse هو كائن تعيده الإضافة في معالج الإكمال بعد تنفيذ الأمر. تحتوي الاستجابة على رمز نتيجة (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 بناءً على هذا التعريف.

توصي Apple بتضمين ما لا يزيد عن 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 بطاقة قياسية بنوع الأمر واسم التطبيق. لمعظم الأوامر، واجهة المستخدم القياسية كافية، وتوصي Apple بإضافة واجهة مخصصة فقط عندما تحسن الفهم حقًا — على سبيل المثال، لعرض مسار أو تأكيد دفعة.

الأمان والتأكيد

للأوامر المتعلقة بالمالية أو البيانات الشخصية، المصادقة مطلوبة. يدعم INIntentResponse رمز requiresAuthentication الذي يجبر Siri على طلب Face ID أو Touch ID قبل التنفيذ. بعد المصادقة، تتلقى الإضافة تأكيدًا عبر استدعاء handle منفصل، حيث يتم التحقق من حالة المصادقة.

تؤكد Apple بشكل خاص: لا يجب على 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)
    }
}