Intents Extension: conceitos-chave e integração do Siri Intents no iOS

O que é Intents Extension no iOS

Intents Extension é uma extensão de aplicativo que permite que Siri, Shortcuts e outros serviços do sistema invoquem funcionalidades do aplicativo através do protocolo padronizado INIntentHandler. Quando um usuário diz “Ei Siri, envie uma mensagem no Messenger X”, a Siri ativa a extensão correspondente, passa os parâmetros da solicitação e recebe o resultado para verbalização.

Ao contrário de outros tipos de extensões, o Intents Extension funciona em segundo plano sem uma interface visível — a Siri exibe a resposta por voz ou cartão de texto. A extensão pode opcionalmente fornecer uma interface personalizada através do INUIHostedViewProviding, que é exibida dentro da Siri antes de executar um comando para confirmação.

A extensão não tem acesso à tela do dispositivo e não pode iniciar ações por conta própria — apenas em resposta a uma solicitação da Siri ou do Shortcuts. Isso garante a segurança: o usuário sempre controla quais ações o aplicativo executa através de comandos de voz.

SiriKit e domínios de intents

SiriKit é o framework da Apple para integração com a Siri, apresentado no iOS 10. Ele define domínios — categorias de ações que a Siri pode manipular: mensagens, chamadas telefônicas, pagamentos, listas, lembretes, fotos, treinos, reservas e outros. Cada domínio tem um conjunto fixo de intents e respostas.

Domínios padrão

INSendMessageIntent — envio de mensagens. INStartWorkoutIntent — início de treino. INSearchForPhotosIntent — pesquisa de fotos. INRequestRideIntent — solicitação de viagem. Cada domínio define parâmetros obrigatórios e opcionais que a Siri extrai da solicitação de voz. Segundo a Apple, os domínios padrão não requerem um arquivo intentdefinition — basta implementar o handler correspondente.

Para aplicativos que não se encaixam nos domínios padrão, o iOS 14 introduziu a capacidade de usar intents personalizados. O aplicativo define seus próprios tipos de comando e seus parâmetros através do Intents.intentdefinition, e a Siri aprende a reconhecer as frases correspondentes com base em exemplos fornecidos pelo desenvolvedor.

Configuração no Info.plist

O Intents Extension é registrado através da chave IntentsSupported no Info.plist, que lista todas as classes de intents que a extensão manipula. A Siri usa esta lista para selecionar a extensão apropriada ao reconhecer um comando de voz. Se várias extensões suportarem o mesmo intent, a Siri solicita que o usuário escolha.

class MessageIntentHandler: NSObject,
    INSendMessageIntentHandling {

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

INIntentHandler: processamento de solicitações

INIntentHandler é um protocolo que define métodos para lidar com cada etapa do processamento de intents: resolução de parâmetros, confirmação e execução. A extensão implementa esses métodos para cada tipo de intent que suporta.

Três estágios de processamento

resolve — validação e esclarecimento dos parâmetros do intent. A Siri chama este método para cada parâmetro. Se um parâmetro estiver ausente ou incorreto, a extensão retorna uma solicitação de esclarecimento, e a Siri faz uma pergunta adicional ao usuário. confirm — confirmação da intenção. A extensão verifica se pode executar o intent no contexto atual. handle — execução real da operação e retorno do resultado.

A separação em três estágios é fundamental para a experiência do usuário por voz: se um parâmetro não for reconhecido, a Siri não executa a ação, mas pede esclarecimento. Por exemplo, se o usuário disse “Envie uma mensagem para Alex” mas há três Alexes nos contatos — a extensão retorna um resolve com solicitação de esclarecimento, e a Siri pergunta “Qual Alex?”

INIntentResponse e códigos de status

INIntentResponse é um objeto que a extensão retorna no handler de conclusão após executar o intent. A resposta contém um código de resultado (success, failure, requiresAuthentication, inProgress) e dados opcionais para a Siri verbalizar. O código determina como a Siri responde: success — confirmação por voz, failure — mensagem de erro, inProgress — indicação de uma operação demorada.

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

Criação de intents personalizados

Com o iOS 14, os desenvolvedores ganharam a capacidade de definir intents personalizados fora dos domínios padrão do SiriKit. Os intents personalizados são descritos no arquivo Intents.intentdefinition — um editor visual dentro do Xcode onde novos tipos de comando com parâmetros e respostas são criados.

Estrutura do intent personalizado

Cada intent personalizado consiste em INIntent (definição da solicitação) e INIntentResponse (definição da resposta). O INIntent contém parâmetros com tipos de dados — String, Integer, CurrencyAmount, objetos encontrados e outros. O INIntentResponse contém propriedades para retornar resultados e um array de códigos de resposta. O Xcode gera automaticamente classes Swift com base nesta definição.

A Apple recomenda incluir no máximo 5 parâmetros em um intent personalizado — parâmetros excessivos degradam o reconhecimento de voz e complicam a experiência do usuário. Para cada parâmetro, é aconselhável fornecer frases de exemplo no Assistente de Diálogo para que a Siri aprenda a reconhecê-los corretamente.

Frases de exemplo para a Siri

No Intents.intentdefinition, para cada intent você pode especificar frases de exemplo — frases que o usuário dirá à Siri para ativar o intent. Exemplos: “Peça café no MeuApp”, “Peça ao MeuApp para encontrar uma receita de pizza”. A Siri usa essas frases para treinar o reconhecimento e as sugere ao usuário ao configurar o Shortcuts.

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

Interação por voz e INUIHostedViewProviding

INUIHostedViewProviding é um protocolo que permite ao Intents Extension mostrar uma interface personalizada dentro da Siri antes de executar um comando. Por exemplo, ao solicitar uma viagem, a extensão pode exibir um mapa com a rota e o custo, e o usuário confirma a ação tocando.

Configuração da interface

O protocolo define o método configure(with:for:completion:), onde a extensão recebe o intent e retorna um UIViewController para ser incorporado na Siri. O tamanho do controlador é limitado — altura máxima de 200 pontos. Recomenda-se usar cartões compactos com informações-chave: valor, hora, endereço.

A interface personalizada é opcional — se a extensão não implementar o INUIHostedViewProviding, a Siri exibe um cartão padrão com o tipo de intent e o nome do aplicativo. Para a maioria dos intents, a interface padrão é suficiente, e a Apple recomenda adicionar uma interface personalizada apenas quando ela realmente melhora a compreensão — por exemplo, para exibir uma rota ou confirmar um pagamento.

Segurança e confirmação

Para intents relacionados a finanças ou dados pessoais, a autenticação é necessária. O INIntentResponse suporta o código requiresAuthentication, que força a Siri a solicitar Face ID ou Touch ID antes da execução. Após a autenticação, a extensão recebe a confirmação através de uma chamada handle separada, onde o status de autenticação é verificado.

A Apple enfatiza especificamente: o Intents Extension não deve solicitar sua própria senha ou dados biométricos — a autenticação do sistema é usada. Armazenar tokens de acesso no Keychain com acesso compartilhado entre o aplicativo e a extensão é uma prática padrão para sessões de longa duração.

class IntentViewController: UIViewController {

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