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 не изпълнява действието, а препитва. Например, ако потребителят е казал „Изпрати съобщение на Алексей”, но в контактите има трима Алексей — разширението връща 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 показва стандартна карта с типа интент и приложението. За повечето интенти стандартният интерфейс е достатъчен и 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)
    }
}