Intents Extension: concepte cheie și integrarea Siri Intents în iOS

Ce este Intents Extension în iOS

Intents Extension este o extensie de aplicație care permite Siri, Shortcuts și altor servicii sistemice să apeleze funcționalitatea aplicației prin protocolul standardizat INIntentHandler. Când utilizatorul spune „Hei Siri, trimite un mesaj în Messenger X”, Siri activează extensia corespunzătoare, transmite parametrii cererii și primește rezultatul pentru a fi rostit.

Spre deosebire de alte tipuri de extensii, Intents Extension funcționează în fundal fără interfață vizibilă — Siri însăși afișează răspunsul vocal sau printr-o carte text. Extensia poate oferi opțional o interfață personalizată prin INUIHostedViewProviding, care este afișată în interiorul Siri înainte de executarea comenzii pentru confirmare.

Extensia nu are acces la ecranul dispozitivului și nu poate iniția acțiuni independent — doar ca răspuns la o cerere de la Siri sau Shortcuts. Aceasta asigură securitatea: utilizatorul controlează întotdeauna ce acțiuni execută aplicația prin comenzi vocale.

SiriKit și domeniile de intenții

SiriKit este framework-ul Apple pentru integrarea cu Siri, introdus în iOS 10. Acesta definește domenii — categorii de acțiuni pe care Siri le poate procesa: mesaje, apeluri telefonice, plăți, liste, memento-uri, fotografii, antrenamente, rezervări și altele. Fiecare domeniu are un set fix de intenții și răspunsuri.

Domenii standard

INSendMessageIntent — trimiterea mesajelor. INStartWorkoutIntent — începerea antrenamentului. INSearchForPhotosIntent — căutarea fotografiilor. INRequestRideIntent — comanda unui taxi. Fiecare domeniu definește parametri obligatorii și opționali pe care Siri îi extrage din cererea vocală. Potrivit Apple, pentru domeniile standard nu este necesar fișierul intentdefinition — este suficient să implementați handler-ul corespunzător.

Pentru aplicațiile care nu se încadrează în domeniile standard, începând cu iOS 14 a apărut posibilitatea intențiilor personalizate. Aplicația definește propriile tipuri de comenzi și parametrii lor prin Intents.intentdefinition, iar Siri învață să recunoască frazele corespunzătoare pe baza exemplelor furnizate de dezvoltator.

Configurare în Info.plist

Intents Extension se înregistrează prin cheia IntentsSupported din Info.plist, unde se listează toate clasele de intenții pe care extensia le procesează. Siri folosește această listă pentru a selecta extensia potrivită la recunoașterea unei comenzi vocale. Dacă mai multe extensii suportă aceeași intenție, Siri oferă utilizatorului posibilitatea de a alege.

class MessageIntentHandler: NSObject,
    INSendMessageIntentHandling {

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

INIntentHandler: procesarea cererilor

INIntentHandler — protocolul care definește metodele de procesare a fiecărei etape a lucrului cu intenția: rezolvarea parametrilor, confirmarea și executarea. Extensia implementează aceste metode pentru fiecare tip de intenție pe care îl suportă.

Trei etape de procesare

resolve — verificarea și clarificarea parametrilor intenției. Siri apelează această metodă pentru fiecare parametru. Dacă un parametru nu este specificat sau este incorect, extensia returnează o cerere de clarificare, iar Siri adresează utilizatorului o întrebare suplimentară. confirm — confirmarea intenției. Extensia verifică dacă poate executa intenția în contextul curent. handle — executarea efectivă a operației și returnarea rezultatului.

Împărțirea în trei etape este critică pentru UX-ul vocal: dacă un parametru nu este recunoscut, Siri nu execută acțiunea, ci reîntreabă. De exemplu, dacă utilizatorul a spus „Trimite un mesaj lui Alexei”, dar în contacte sunt trei Alexei — extensia returnează resolve cu o cerere de clarificare, iar Siri întreabă „Cărui Alexei?”.

INIntentResponse și statusuri

INIntentResponse — obiectul pe care extensia îl returnează în completion după executarea intenției. Response conține codul rezultatului (success, failure, requiresAuthentication, inProgress) și date opționale pentru a fi rostite de Siri. Codul determină modul în care Siri reacționează: success — confirmare vocală, failure — mesaj de eroare, inProgress — indicarea unei operații de lungă durată.

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

Crearea intențiilor personalizate

Începând cu iOS 14, dezvoltatorii au primit posibilitatea de a defini propii intenții în afara domeniilor standard SiriKit. Intențiile personalizate sunt descrise în fișierul Intents.intentdefinition — un editor vizual din Xcode unde se creează noi tipuri de comenzi cu parametri și răspunsuri.

Structura unei intenții personalizate

Fiecare intenție personalizată constă din INIntent (definiția cererii) și INIntentResponse (definiția răspunsului). INIntent conține parametri cu tipuri de date — String, Integer, CurrencyAmount, obiecte găsite și altele. INIntentResponse conține proprietăți pentru returnarea rezultatului și un array de coduri de răspuns. Xcode generează automat clase Swift pe baza acestei definiții.

Apple recomandă ca o intenție personalizată să nu aibă mai mult de 5 parametri — un număr excesiv degradează recunoașterea vocală și complică experiența utilizatorului. Pentru fiecare parametru este de dorit să se furnizeze exemple de fraze în Assistant Dialog, pentru ca Siri să învețe să le recunoască corect.

Fraze exemplu pentru Siri

În Intents.intentdefinition pentru fiecare intenție se pot specifica propoziții exemplu — fraze pe care utilizatorul le va spune lui Siri pentru a activa intenția. Exemple: „Comandă cafea în AplicațiaMea”, „Roagă AplicațiaMea să găsească o rețetă de pizza”. Siri folosește aceste fraze pentru a învăța recunoașterea și le propune utilizatorului la configurarea Shortcuts.

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

Interacțiunea vocală și INUIHostedViewProviding

INUIHostedViewProviding — protocolul care permite Intents Extension să afișeze o interfață personalizată în interiorul Siri înainte de executarea comenzii. De exemplu, la comanda unui taxi, extensia poate afișa o hartă cu ruta și costul, iar utilizatorul confirmă acțiunea prin atingere.

Configurarea interfeței

Protocolul definește metoda configure(with:for:completion:), unde extensia primește intenția și returnează un UIViewController care va fi încorporat în Siri. Dimensiunea controlerului este limitată — înălțimea maximă 200 de puncte. Se recomandă utilizarea unor cărți compacte cu informații cheie: sumă, timp, adresă.

Interfața personalizată este opțională — dacă extensia nu implementează INUIHostedViewProviding, Siri afișează o carte standard cu tipul intenției și aplicația. Pentru majoritatea intențiilor, UI-ul standard este suficient, iar Apple recomandă adăugarea unei interfețe personalizate doar atunci când îmbunătățește cu adevărat înțelegerea — de exemplu, pentru afișarea rutei sau confirmarea plății.

Securitate și confirmare

Pentru intențiile legate de finanțe sau date personale este necesară autentificarea. INIntentResponse suportă codul requiresAuthentication, care forțează Siri să solicite Face ID sau Touch ID înainte de executare. După autentificare, extensia primește confirmarea printr-un apel separat handle, unde se verifică statusul autentificării.

Apple subliniază în mod special: Intents Extension nu trebuie să solicite propria parolă sau biometrie — se utilizează autentificarea sistemică. Stocarea tokenurilor de acces în Keychain cu acces partajat între aplicație și extensie este practica standard pentru sesiuni de lungă durată.

class IntentViewController: UIViewController {

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