Intents Extension: ключові поняття та інтеграція Siri Intents в iOS

Що таке Intents Extension в iOS

Intents Extension — це розширення додатка, яке дозволяє Siri, Shortcuts та іншим системним сервісам викликати функціональність додатка через стандартизований протокол INIntentHandler. Коли користувач каже «Привіт Siri, відправ повідомлення в Месенджері X», Siri активує відповідне розширення, передає параметри запиту та отримує результат для озвучування.

На відміну від інших типів розширень, Intents Extension працює у фоновому режимі без видимого інтерфейсу — Siri сама відображає відповідь голосом або текстовою карткою. Розширення може опціонально надати кастомний UI через INUIHostedViewProviding, який відображається всередині Siri перед виконанням команди для підтвердження.

Розширення не має доступу до екрану пристрою і не може ініціювати дії самостійно — лише у відповідь на запит від Siri або Shortcuts. Це забезпечує безпеку: користувач завжди контролює, які дії виконує додаток через голосові команди.

SiriKit та домени інтентів

SiriKit — це фреймворк Apple для інтеграції з Siri, представлений у iOS 10. Він визначає домени — категорії дій, які Siri може обробляти: повідомлення, телефонні дзвінки, платежі, списки, нагадування, фото, тренування, бронювання та інші. Кожен домен має фіксований набір інтентів і відповідей.

Стандартні домени

INSendMessageIntent — надсилання повідомлень. INStartWorkoutIntent — початок тренування. INSearchForPhotosIntent — пошук фотографій. INRequestRideIntent — замовлення таксі. Кожен домен визначає обов'язкові та опціональні параметри, які Siri витягує з голосового запиту. За даними Apple, для стандартних доменів не потрібен файл intentdefinition — достатньо реалізувати відповідний handler.

Для додатків, які не потрапляють у стандартні домени, з 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 — фактичне виконання операції та повернення результату.

Розділення на три етапи критично важливе для голосового UX: якщо параметр не розпізнано, 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-класи на основі цього визначення.

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 відображає стандартну картку з типом інтенту та додатком. Для більшості інтентів стандартний UI достатній, і 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)
    }
}