Siri Intent：关键概念、SiriKit 和与 Siri 集成

Co to jest Siri Intent

Siri Intent — to mechanizm umożliwiający aplikacji iOS przetwarzanie poleceń głosowych wypowiadanych przez użytkownika przez Siri. Gdy użytkownik mówi «Siri, wyślij wiadomość do Telegram do Jana», Siri rozpoznaje intent (INSendMessageIntent), określa aplikację, która może go obsłużyć (Telegram), przekazuje parametry (kontakt «Jan», treść wiadomości) i uruchamia IntentHandler aplikacji. Cały proces trwa 0,5–2 sekund i nie wymaga otwierania aplikacji.

Architektura Siri Intent obejmuje trzy komponenty. Pierwszy — plik .intentdefinition opisujący strukturę intentu: parametry (String, Integer, INPerson), frazy wyzwalające i odpowiedzi. Drugi — IntentHandler implementujący protokół obsługi: otrzymuje parametry, wykonuje działanie (np. wysyła wiadomość przez API aplikacji) i zwraca INInteraction z kodem wyniku. Trzeci — Intents Extension, osobny target w Xcode, działający we własnym procesie. Siri uruchamia Intents Extension przy zapytaniu głosowym, przekazuje mu dane i otrzymuje wynik. Extension nie ma UI — wykonuje się w tle i musi zakończyć w ciągu 5–10 sekund.

Zastosowania Siri Intent: wysyłanie wiadomości (INSendMessageIntent), wykonywanie połączeń (INStartCallIntent), wysyłanie płatności (INSendPaymentIntent), tworzenie notatek (INCreateNoteIntent), treningi (INStartWorkoutIntent), zdjęcia (INSearchForPhotosIntent), rezerwacja podróży (INBookRestaurantReservationIntent), funkcje samochodowe (INSetCarLockStatusIntent). Każda domena ma ścisły schemat parametrów i ograniczenia określone przez Apple dla bezpieczeństwa.

SiriKit: architektura i domeny

SiriKit — framework przedstawiony przez Apple w iOS 10 (2016). Zapewnia gotowe domeny (Intents) dla typowych działań: wiadomości, połączenia, płatności, notatki, przypomnienia, zdjęcia, treningi, rezerwacje, funkcje samochodowe, wyszukiwanie. Dla każdej domeny Apple określiła zestaw klas Intent (INSendMessageIntent, INStartCallIntent), które aplikacja implementuje przez IntentHandler. SiriKit automatycznie generuje UI-potwierdzenie przed wykonaniem (dla płatności i wiadomości potwierdzenie jest obowiązkowe).

Domeny SiriKit:

• Wiadomości (Messages) — INSendMessageIntent, INSearchForMessagesIntent, INSetMessageAttributeIntent
• Połączenia (Calls) — INStartCallIntent, INSearchForCallHistoryIntent
• Płatności (Payments) — INSendPaymentIntent, INRequestPaymentIntent
• Notatki (Notes) — INCreateNoteIntent, INSearchForNotesIntent, INAddTasksIntent
• Przypomnienia (Reminders) — INCreateTaskListIntent, INAddTasksIntent, INSetTaskAttributeIntent
• Treningi (Workouts) — INStartWorkoutIntent, INPauseWorkoutIntent, INEndWorkoutIntent
• Zdjęcia (Photos) — INSearchForPhotosIntent, INStartPhotoPlaybackIntent
• Samochód (CarPlay) — INSetCarLockStatusIntent, INGetCarLockStatusIntent
• Wyszukiwanie (Search) — INSearchForMessagesIntent, INSearchForNotebookItemsIntent

Ograniczenia SiriKit: programista nie może tworzyć własnych domen — może używać tylko predefiniowanych. To ograniczenie zostało rozwiązane w iOS 16 wraz z pojawieniem się App Intents, który umożliwia tworzenie dowolnych poleceń głosowych dla dowolnych działań aplikacji.

App Intents: nowy framework

App Intents — framework Apple, przedstawiony w iOS 16 (2022) i znacznie rozszerzony w iOS 17–18. W przeciwieństwie do SiriKit ze stałymi domenami, App Intents umożliwia programiście definiowanie własnych poleceń głosowych dla dowolnych działań aplikacji: «Siri, dodaj mleko do listy zakupów w AnyList», «Siri, zapisz spotkanie w Fantastical», «Siri, włącz światło w salonie w Home». Niestandardowe intenty definiuje się przez protokół AppIntent z określeniem parametrów, fraz i schematu potwierdzenia.

Komponenty App Intents:

• AppIntent — protokół do opisu działania: title, description, parameters, perform()
• IntentParameter — parametry polecenia z typami (String, Int, URL, Entity, Measurement)
• IntentDialog — dialogi dla Siri: zapytanie o potwierdzenie, odpowiedź o sukcesie lub błędzie
• WidgetIntent — podzbiór App Intents do obsługi kliknięć w widżetach (iOS 17+)
• Shortcuts — App Intents automatycznie integrują się z aplikacją Shortcuts

App Intents vs SiriKit: główna różnica — elastyczność. SiriKit jest ograniczony do 10 domen, App Intents umożliwia tworzenie dowolnych poleceń. SiriKit wymaga osobnego targetu Intents Extension, App Intents działa wewnątrz głównej aplikacji. SiriKit używa Intents.framework (Objective-C/Swift), App Intents — nowej deklaratywnej składni Swift z makrami @Intent, @Parameter. Według danych Apple, App Intents jest używany w 70% nowych projektów z obsługą Siri na 2025 rok.

Przykład kodu: Swift Intents

Przykład tworzenia niestandardowego App Intent do dodawania notatki w aplikacji. Demonstruje nowoczesne podejście z użyciem frameworka App Intents w iOS 16+.

import AppIntents

// 1. 用于添加笔记的自定义 Intent
struct AddNoteIntent: AppIntent {
    // 命令名称（在 Shortcuts 中可见）
    static var title: LocalizedStringResource = "添加笔记"

    // 命令描述
    static var description: LocalizedStringResource = "在应用程序中创建新笔记"

    // 命令参数
    @Parameter(title: "笔记内容")
    var noteContent: String

    @Parameter(title: "分类", default: "常规")
    var category: String

    // 执行操作
    func perform() async throws -> some IntentResult {
        // 通过本地存储创建笔记
        let note = Note(content: noteContent, category: category)
        try await NoteStore.shared.save(note)

        // 返回结果并附带 Siri 对话
        return .result(
            dialog: .response("笔记 \"\(noteContent)\" 已创建")
        )
    }
}

// 2. App Shortcut Provider — 注册命令
struct NotesShortcuts: AppShortcutsProvider {
    @AppShortcutsBuilder
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: AddNoteIntent(),
            phrases: [
                "在 \(.applicationName) 中添加笔记",
                "在 \(.applicationName) 中使用 \(.\$noteContent) 创建笔记",
                "在 \(.applicationName) 中记录 \(.\$noteContent)",
            ]
        )
    }
}

// 3. 用于消息的 SiriKit Intent（经典方法）
class MessageIntentHandler: NSObject, INSendMessageIntentHandling {

    func resolveRecipients(
        for intent: INSendMessageIntent,
        completion: @escaping ([INPersonResolutionResult]) -> Void
    ) {
        guard let recipients = intent.recipients else {
            completion([.needsRequired()])
            return
        }
        // 通过应用程序的通讯录解决联系人
        let results = recipients.map { INPersonResolutionResult.success(with: $0) }
        completion(results)
    }

    func handle(
        intent: INSendMessageIntent,
        completion: @escaping (INSendMessageIntentResponse) -> Void
    ) {
        // 通过应用程序的 API 发送消息
        let response = INSendMessageIntentResponse(
            code: .success, userActivity: nil
        )
        completion(response)
    }
}

Kluczowe elementy: AppIntent — protokół dla niestandardowego polecenia głosowego; @Parameter — makro określające parametry polecenia; perform() — metoda wykonująca działanie i zwracająca wynik z dialogiem dla Siri; AppShortcutsProvider — rejestruje polecenia aplikacji w Siri i Shortcuts; INSendMessageIntentHandling — protokół SiriKit do obsługi domeny wiadomości. Frazy wyzwalające są określane przez .applicationName i \.$parameter dla różnorodności.

Zalecenia i ograniczenia

Zalecenia dotyczące tworzenia Siri Intent: definiuj zrozumiałe frazy wyzwalające z wariantami wymowy; zwracaj informacyjny dialog po wykonaniu (sukces/błąd); obsługuj przypadki niekompletnych parametrów przez metody resolve z prośbą o doprecyzowanie; zapisuj INInteraction po wykonaniu do uczenia Siri; testuj na rzeczywistym urządzeniu (symulator nie obsługuje Siri). Dla App Intents używaj @Intent z inAppSearchKeywords dla lepszego rozpoznawania.

Ograniczenia: SiriKit Intents są ograniczone do 10 domen. Intents Extension wykonuje się z limitem 5–10 sekund — po przekroczeniu Siri zgłasza błąd. Siri Intent nie ma UI — cały interfejs jest generowany przez Siri. App Intents są dostępne tylko na iOS 16+ (pokrycie ~85% urządzeń na 2026). Do obsługi iOS 13–15 należy używać SiriKit. Prywatność: Siri nie przekazuje aplikacji nagrania audio — tylko rozpoznany tekst parametrów. Dla poufnych działań (płatności, wiadomości) wymagane jest potwierdzenie od użytkownika.

Wydajność i debugowanie: Intents Extension uruchamia się w oddzielnym procesie z ograniczeniem pamięci 30–50 MB. Do debugowania użyj schematu «Intents Extension» w Xcode z dołączeniem do procesu Siri. Logi są wypisywane w konsoli urządzenia. App Intents debuguje się przez aplikację Shortcuts na urządzeniu. INInteraction jest zapisywany lokalnie i używany przez Siri do sugestii — usuwaj nieaktualne interakcje przez INInteraction delete.