Intents Extension: concetti chiave e integrazione Siri Intents in iOS

Cos'è Intents Extension in iOS

Intents Extension è un'estensione dell'app che consente a Siri, Shortcuts e altri servizi di sistema di invocare funzionalità dell'app tramite il protocollo standardizzato INIntentHandler. Quando un utente dice “Ehi Siri, invia un messaggio in Messenger X”, Siri attiva l'estensione corrispondente, passa i parametri della richiesta e riceve il risultato per la vocalizzazione.

A differenza di altri tipi di estensioni, Intents Extension funziona in background senza un'interfaccia visibile — Siri mostra la risposta tramite voce o una scheda di testo. L'estensione può opzionalmente fornire un'interfaccia personalizzata tramite INUIHostedViewProviding, che viene visualizzata all'interno di Siri prima di eseguire un comando per la conferma.

L'estensione non ha accesso allo schermo del dispositivo e non può avviare azioni autonomamente — solo in risposta a una richiesta da Siri o Shortcuts. Ciò garantisce la sicurezza: l'utente controlla sempre quali azioni l'app esegue tramite comandi vocali.

SiriKit e domini di intent

SiriKit è il framework Apple per l'integrazione con Siri, introdotto in iOS 10. Definisce domini — categorie di azioni che Siri può gestire: messaggi, chiamate telefoniche, pagamenti, elenchi, promemoria, foto, allenamenti, prenotazioni e altri. Ogni dominio ha un insieme fisso di intent e risposte.

Domini standard

INSendMessageIntent — invio di messaggi. INStartWorkoutIntent — inizio allenamento. INSearchForPhotosIntent — ricerca foto. INRequestRideIntent — prenotazione corsa. Ogni dominio definisce parametri obbligatori e opzionali che Siri estrae dalla richiesta vocale. Secondo Apple, i domini standard non richiedono un file intentdefinition — è sufficiente implementare l'handler corrispondente.

Per le app che non rientrano nei domini standard, iOS 14 ha introdotto la possibilità di utilizzare intent personalizzati. L'app definisce i propri tipi di comando e i relativi parametri tramite Intents.intentdefinition, e Siri impara a riconoscere le frasi corrispondenti sulla base di esempi forniti dallo sviluppatore.

Configurazione in Info.plist

Intents Extension viene registrato tramite la chiave IntentsSupported in Info.plist, che elenca tutte le classi di intent gestite dall'estensione. Siri utilizza questo elenco per selezionare l'estensione appropriata quando riconosce un comando vocale. Se più estensioni supportano lo stesso intent, Siri chiede all'utente di scegliere.

class MessageIntentHandler: NSObject,
    INSendMessageIntentHandling {

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

INIntentHandler: elaborazione delle richieste

INIntentHandler è un protocollo che definisce i metodi per gestire ogni fase dell'elaborazione degli intent: risoluzione dei parametri, conferma ed esecuzione. L'estensione implementa questi metodi per ogni tipo di intent che supporta.

Tre fasi di elaborazione

resolve — convalida e chiarimento dei parametri dell'intent. Siri chiama questo metodo per ogni parametro. Se un parametro è mancante o errato, l'estensione restituisce una richiesta di chiarimento e Siri pone una domanda aggiuntiva all'utente. confirm — conferma dell'intenzione. L'estensione verifica se può eseguire l'intent nel contesto attuale. handle — esecuzione effettiva dell'operazione e restituzione del risultato.

La separazione in tre fasi è fondamentale per l'esperienza utente vocale: se un parametro non viene riconosciuto, Siri non esegue l'azione ma chiede chiarimenti. Ad esempio, se l'utente ha detto “Invia un messaggio ad Alex” ma ci sono tre Alex nei contatti — l'estensione restituisce un resolve con una richiesta di chiarimento e Siri chiede “Quale Alex?”

INIntentResponse e codici di stato

INIntentResponse è un oggetto che l'estensione restituisce nell'handler di completamento dopo aver eseguito l'intent. La risposta contiene un codice di risultato (success, failure, requiresAuthentication, inProgress) e dati opzionali per la vocalizzazione da parte di Siri. Il codice determina come Siri risponde: success — conferma vocale, failure — messaggio di errore, inProgress — indicazione di un'operazione lunga.

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

Creazione di intent personalizzati

Con iOS 14, gli sviluppatori hanno ottenuto la possibilità di definire intent personalizzati al di fuori dei domini standard di SiriKit. Gli intent personalizzati sono descritti nel file Intents.intentdefinition — un editor visivo all'interno di Xcode dove vengono creati nuovi tipi di comando con parametri e risposte.

Struttura dell'intent personalizzato

Ogni intent personalizzato consiste in INIntent (definizione della richiesta) e INIntentResponse (definizione della risposta). INIntent contiene parametri con tipi di dati — String, Integer, CurrencyAmount, oggetti trovati e altri. INIntentResponse contiene proprietà per restituire i risultati e un array di codici di risposta. Xcode genera automaticamente classi Swift basate su questa definizione.

Apple raccomanda di non includere più di 5 parametri in un intent personalizzato — parametri eccessivi degradano il riconoscimento vocale e complicano l'esperienza utente. Per ogni parametro, è consigliabile fornire frasi di esempio nel Dialogo Assistente in modo che Siri impari a riconoscerli correttamente.

Frasi di esempio per Siri

In Intents.intentdefinition, per ogni intent è possibile specificare frasi di esempio — frasi che l'utente dirà a Siri per attivare l'intent. Esempi: “Ordina un caffè nella MiaApp”, “Chiedi alla MiaApp di trovare una ricetta per la pizza”. Siri utilizza queste frasi per l'addestramento al riconoscimento e le suggerisce all'utente durante la configurazione di Shortcuts.

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

Interazione vocale e INUIHostedViewProviding

INUIHostedViewProviding è un protocollo che consente a Intents Extension di mostrare un'interfaccia personalizzata all'interno di Siri prima di eseguire un comando. Ad esempio, durante la prenotazione di una corsa, l'estensione può visualizzare una mappa con il percorso e il costo, e l'utente conferma l'azione toccando.

Configurazione dell'interfaccia

Il protocollo definisce il metodo configure(with:for:completion:), dove l'estensione riceve l'intent e restituisce un UIViewController da incorporare in Siri. Le dimensioni del controller sono limitate — altezza massima 200 punti. Si consiglia di utilizzare schede compatte con informazioni chiave: importo, ora, indirizzo.

L'interfaccia personalizzata è opzionale — se l'estensione non implementa INUIHostedViewProviding, Siri mostra una scheda standard con il tipo di intent e il nome dell'app. Per la maggior parte degli intent, l'interfaccia standard è sufficiente e Apple raccomanda di aggiungere un'interfaccia personalizzata solo quando migliora realmente la comprensione — ad esempio, per visualizzare un percorso o confermare un pagamento.

Sicurezza e conferma

Per gli intent relativi a finanze o dati personali, è richiesta l'autenticazione. INIntentResponse supporta il codice requiresAuthentication, che obbliga Siri a richiedere Face ID o Touch ID prima dell'esecuzione. Dopo l'autenticazione, l'estensione riceve la conferma tramite una chiamata handle separata, dove viene verificato lo stato di autenticazione.

Apple sottolinea specificamente: Intents Extension non deve richiedere la propria password o dati biometrici — viene utilizzata l'autenticazione di sistema. Memorizzare i token di accesso in Keychain con accesso condiviso tra l'app e l'estensione è una pratica standard per sessioni di lunga durata.

class IntentViewController: UIViewController {

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