Intents Extension: kluczowe pojęcia i integracja Siri Intents w iOS

Czym jest Intents Extension w iOS

Intents Extension to rozszerzenie aplikacji, które pozwala Siri, Shortcuts i innym usługom systemowym wywoływać funkcjonalność aplikacji poprzez standaryzowany protokół INIntentHandler. Gdy użytkownik mówi „Hej Siri, wyślij wiadomość w Messengerze X”, Siri aktywuje odpowiednie rozszerzenie, przekazuje parametry żądania i otrzymuje wynik do wypowiedzenia.

W przeciwieństwie do innych typów rozszerzeń, Intents Extension działa w tle bez widocznego interfejsu — Siri sama wyświetla odpowiedź głosem lub kartą tekstową. Rozszerzenie może opcjonalnie udostępnić niestandardowy interfejs przez INUIHostedViewProviding, który jest wyświetlany wewnątrz Siri przed wykonaniem polecenia w celu potwierdzenia.

Rozszerzenie nie ma dostępu do ekranu urządzenia i nie może inicjować działań samodzielnie — tylko w odpowiedzi na żądanie od Siri lub Shortcuts. Zapewnia to bezpieczeństwo: użytkownik zawsze kontroluje, jakie działania wykonuje aplikacja za pomocą poleceń głosowych.

SiriKit i domeny intentów

SiriKit to framework Apple do integracji z Siri, wprowadzony w iOS 10. Definiuje domeny — kategorie działań, które Siri może obsługiwać: wiadomości, połączenia telefoniczne, płatności, listy, przypomnienia, zdjęcia, treningi, rezerwacje i inne. Każda domena ma stały zestaw intentów i odpowiedzi.

Standardowe domeny

INSendMessageIntent — wysyłanie wiadomości. INStartWorkoutIntent — rozpoczęcie treningu. INSearchForPhotosIntent — wyszukiwanie zdjęć. INRequestRideIntent — zamawianie taksówki. Każda domena definiuje obowiązkowe i opcjonalne parametry, które Siri wyodrębnia z zapytania głosowego. Według Apple, dla standardowych domen nie jest wymagany plik intentdefinition — wystarczy zaimplementować odpowiedni handler.

Dla aplikacji, które nie mieszczą się w standardowych domenach, od iOS 14 pojawiła się możliwość niestandardowych intentów. Aplikacja definiuje własne typy poleceń i ich parametry przez Intents.intentdefinition, a Siri uczy się rozpoznawać odpowiednie frazy na podstawie przykładów dostarczonych przez programistę.

Konfiguracja w Info.plist

Intents Extension rejestruje się przez klucz IntentsSupported w Info.plist, gdzie wymieniane są wszystkie klasy intentów, które rozszerzenie obsługuje. Siri używa tej listy do wyboru odpowiedniego rozszerzenia przy rozpoznawaniu polecenia głosowego. Jeśli kilka rozszerzeń obsługuje ten sam intent, Siri proponuje użytkownikowi wybór.

class MessageIntentHandler: NSObject,
    INSendMessageIntentHandling {

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

INIntentHandler: obsługa żądań

INIntentHandler — protokół, który definiuje metody obsługi każdego etapu pracy intentu: rozwiązywanie parametrów, potwierdzanie i wykonanie. Rozszerzenie implementuje te metody dla każdego typu intentu, który obsługuje.

Trzy etapy obsługi

resolve — sprawdzenie i doprecyzowanie parametrów intentu. Siri wywołuje tę metodę dla każdego parametru. Jeśli parametr nie został określony lub jest nieprawidłowy, rozszerzenie zwraca prośbę o doprecyzowanie, a Siri zadaje użytkownikowi dodatkowe pytanie. confirm — potwierdzenie zamiaru. Rozszerzenie sprawdza, czy może wykonać intent w bieżącym kontekście. handle — faktyczne wykonanie operacji i zwrócenie wyniku.

Podział na trzy etapy jest krytyczny dla głosowego UX: jeśli parametr nie został rozpoznany, Siri nie wykonuje działania, tylko dopyta. Na przykład, jeśli użytkownik powiedział „Wyślij wiadomość do Aleksieja”, ale w kontaktach jest trzech Aleksiejów — rozszerzenie zwraca resolve z prośbą o doprecyzowanie, a Siri pyta „Do którego Aleksieja?”.

INIntentResponse i statusy

INIntentResponse — obiekt, który rozszerzenie zwraca w completion po wykonaniu intentu. Response zawiera kod wyniku (success, failure, requiresAuthentication, inProgress) i opcjonalne dane do wypowiedzenia przez Siri. Kod określa, jak Siri zareaguje: success — potwierdzenie głosowe, failure — komunikat o błędzie, inProgress — wskazanie długotrwałej operacji.

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

Tworzenie niestandardowych intentów

Od iOS 14 programiści otrzymali możliwość definiowania własnych intentów poza standardowymi domenami SiriKit. Niestandardowe intenty opisuje się w pliku Intents.intentdefinition — jest to edytor wizualny w Xcode, gdzie tworzy się nowe typy poleceń z parametrami i odpowiedziami.

Struktura niestandardowego intentu

Każdy niestandardowy intent składa się z INIntent (definicja żądania) i INIntentResponse (definicja odpowiedzi). INIntent zawiera parametry z typem danych — String, Integer, CurrencyAmount, znalezione obiekty i inne. INIntentResponse zawiera właściwości do zwrócenia wyniku i tablicę kodów odpowiedzi. Xcode automatycznie generuje klasy Swift na podstawie tej definicji.

Apple zaleca, aby niestandardowy intent zawierał nie więcej niż 5 parametrów — nadmierna liczba pogarsza rozpoznawanie mowy i komplikuje doświadczenie użytkownika. Dla każdego parametru warto podać przykładowe frazy w Assistant Dialog, aby Siri nauczyła się je poprawnie rozpoznawać.

Przykładowe frazy dla Siri

W Intents.intentdefinition dla każdego intentu można podać przykładowe zdania — frazy, które użytkownik wypowie do Siri, aby aktywować intent. Przykłady: „Zamów kawę w MojejAplikacji”, „Poproś MojąAplikację o znalezienie przepisu na pizzę”. Siri używa tych fraz do trenowania rozpoznawania i proponuje je użytkownikowi podczas konfiguracji Shortcuts.

// Intents.intentdefinition (edytor wizualny)
Intent: OrderCoffeeIntent
Parameters:
  - beverage (String)
  - size (String)
  - quantity (Integer)
Response:
  - orderNumber (String)
  - price (CurrencyAmount)
Phrases:
  - "Order coffee in MyApp"
  - "Get a latte from MyApp"

Interakcja głosowa i INUIHostedViewProviding

INUIHostedViewProviding — protokół, który pozwala Intents Extension wyświetlać niestandardowy interfejs wewnątrz Siri przed wykonaniem polecenia. Na przykład przy zamawianiu taksówki rozszerzenie może wyświetlić mapę z trasą i kosztem, a użytkownik potwierdza działanie dotknięciem.

Konfiguracja interfejsu

Protokół definiuje metodę configure(with:for:completion:), w której rozszerzenie otrzymuje intent i zwraca UIViewController, który zostanie osadzony w Siri. Rozmiar kontrolera jest ograniczony — maksymalna wysokość 200 punktów. Zaleca się używanie kompaktowych kart z kluczowymi informacjami: kwota, czas, adres.

Niestandardowy interfejs jest opcjonalny — jeśli rozszerzenie nie implementuje INUIHostedViewProviding, Siri wyświetla standardową kartę z typem intentu i aplikacją. Dla większości intentów standardowy UI jest wystarczający, a Apple zaleca dodawanie niestandardowego interfejsu tylko wtedy, gdy rzeczywiście poprawia zrozumienie — na przykład do wyświetlania trasy lub potwierdzenia płatności.

Bezpieczeństwo i potwierdzenie

Dla intentów związanych z finansami lub danymi osobowymi wymagane jest uwierzytelnienie. INIntentResponse obsługuje kod requiresAuthentication, który wymusza na Siri poproszenie o Face ID lub Touch ID przed wykonaniem. Po uwierzytelnieniu rozszerzenie otrzymuje potwierdzenie przez osobne wywołanie handle, gdzie sprawdzany jest status uwierzytelnienia.

Apple szczególnie podkreśla: Intents Extension nie powinien żądać własnego hasła ani biometrii — używane jest uwierzytelnianie systemowe. Przechowywanie tokenów dostępu w Keychain ze wspólnym dostępem między aplikacją a rozszerzeniem to standardowa praktyka dla długotrwałych sesji.

class IntentViewController: UIViewController {

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