AppIntent: o que é, modelo de intents Siri e Swift

O que é AppIntent e para que serve?

AppIntent é um framework da Apple para descrever declarativamente comandos que seu aplicativo pode executar a pedido do Siri, Shortcuts, Spotlight, Control Center e Action Button. Baseia-se no protocolo AppIntent, onde o desenvolvedor descreve o nome do intent, seus parâmetros e o método perform() — a lógica executável. O framework gera automaticamente uma interface de usuário para configurar parâmetros no aplicativo Shortcuts e frases de voz para o Siri.

Antes do AppIntent, os desenvolvedores usavam o Intents framework — um sistema baseado no arquivo Intents Definition File que gerava código Objective-C e exigia a configuração de uma extensão Intents Extension separada. Este processo era complicado: mesmo um intent simples exigia até 5 arquivos de configuração. AppIntent elimina essa complexidade — um intent é descrito em um único arquivo Swift, e o sistema gera automaticamente tudo o que é necessário para a integração com Siri e Shortcuts.

De acordo com a sessão WWDC 2024 "Dive deeper into App Intents", a Apple vê o AppIntent como o mecanismo central para estender a funcionalidade dos aplicativos além da interface de usuário tradicional. Na época do lançamento do iOS 18, mais de 70% dos aplicativos do top 100 da App Store já usavam AppIntent para integração com Shortcuts e Siri, e o usuário médio do iOS 18 executa de 4 a 6 intents por dia através de comandos de voz ou widgets.

Onde AppIntent é usado

• Siri — comandos de voz: "Hey Siri, adicione uma tarefa ao MyApp"
• Shortcuts — automação no aplicativo Atalhos com configuração de parâmetros
• Spotlight — pesquisa e execução de comandos diretamente da barra de pesquisa
• Control Center — botões de ação rápida no iOS 18+
• Action Button — atribuição de uma ação ao botão do iPhone 15 Pro e posteriores

AppIntent vs Intents framework: diferenças principais

Intents framework (iOS 10–15) exigia a criação de um arquivo .intentdefinition, geração de classes ObjC/Swift via Xcode, configuração de Intents Extension e App Intent Configuration. O AppIntent (iOS 16+) substitui completamente esse pipeline com código Swift puro, sem geração, extensões ou configurações adicionais. Isso torna o processo de criação de intents acessível para o desenvolvedor iOS médio sem estudar SiriKit.

A principal vantagem do AppIntent é a declaratividade. O desenvolvedor descreve o que o intent faz, não como ele se integra ao sistema. O próprio framework lida com cenários de diálogo do Siri, exibição de parâmetros no Shortcuts e transferência de contexto entre intents. No antigo Intents framework, cada aspecto da integração tinha que ser codificado manualmente, incluindo INUIHostedView para exibir a interface de usuário do intent.

Comparação de abordagens

Protocolos principais: AppIntent, AppEntity, AppEnum

AppIntent é o protocolo central que define um intent. Ele contém um title (nome para o Siri), description (descrição no Shortcuts), parâmetros (via @Parameter) e o método perform() que retorna IntentResult. O resultado pode ser IntentDialog (diálogo com Siri), um valor para retornar ao Shortcuts ou um erro. Cada intent também pode fornecer suggestedInvocationPhrase — uma frase para invocação por voz.

AppEntity descreve entidades com as quais os intents trabalham. Por exemplo, se um aplicativo gerencia projetos, o AppEntity Project contém id, displayRepresentation (como exibir a entidade na interface do usuário) e defaultQuery (como pesquisar entidades). AppEnum é uma enumeração para parâmetros de seleção que gera automaticamente uma interface de usuário com um elemento picker no Shortcuts. Em vez de criar manualmente uma lista de parâmetros, basta declarar um enum em conformidade com AppEnum.

Exemplo de AppEnum e parâmetro

enum TaskPriority: String, AppEnum {
    case low, medium, high
    
    static var typeDisplayRepresentation: TypeDisplayRepresentation =
        "Priority"
    
    var displayRepresentation: DisplayRepresentation {
        switch self {
        case .low: "Low"
        case .medium: "Medium"
        case .high: "High"
        }
    }
}

struct CreateTaskIntent: AppIntent {
    static var title: LocalizedStringResource = "Create Task"
    
    @Parameter(title: "Task Name")
    var taskName: String
    
    @Parameter(title: "Priority")
    var priority: TaskPriority
    
    func perform() async throws -> some IntentResult {
        try await TaskManager.shared
            .createTask(name: taskName, priority: priority)
        return .result(dialog: "Task created")
    }
}

Parâmetros de intents e sua validação

Os parâmetros do AppIntent são declarados através do property wrapper @Parameter, que se integra automaticamente com a interface do Shortcuts e as solicitações de voz do Siri. Cada parâmetro tem um title (exibido no Shortcuts) e pode incluir uma descrição, valores padrão e restrições. O AppIntent suporta tipos padrão: String, Int, Double, Bool, bem como tipos personalizados via AppEntity e AppEnum.

A validação de parâmetros é realizada no método perform() antes de executar a lógica. Se os parâmetros forem inválidos, o intent retorna um erro através de IntentError. Para validação complexa, pode-se implementar o método validate(), que é chamado antes do perform() e pode fornecer feedback ao usuário através do IntentDialog antes mesmo de executar o comando. Isso é especialmente útil para cenários de voz do Siri, onde é mais fácil perguntar novamente ao usuário do que executar um comando incorreto.

Parâmetros com validação

struct SendMessageIntent: AppIntent {
    static var title: LocalizedStringResource = "Send Message"
    
    @Parameter(title: "Recipient")
    var recipient: String
    
    @Parameter(title: "Message")
    var message: String
    
    func validate() throws {
        guard message.count >= 1 else {
            throw IntentError.invalidMessage
        }
    }
    
    func perform() async throws -> some IntentResult {
        try await Messenger.shared
            .send(recipient: recipient, text: message)
        return .result(dialog: "Sent!")
    }
}

Criação de um intent em Swift: exemplo

Um exemplo completo de um intent para pesquisar notas em um aplicativo demonstra o trabalho com AppEntity e EntityQuery. O SearchNotesIntent recebe uma string de pesquisa e retorna uma lista de notas encontradas. O AppEntity Note descreve a estrutura da nota, e o EntityQuery implementa a pesquisa no armazenamento. O resultado é retornado via IntentResult com um array de entidades, que o Shortcuts exibe ao usuário.

struct Note: AppEntity {
    let id: UUID
    let title: String
    let content: String
    
    static var typeDisplayRepresentation: TypeDisplayRepresentation =
        "Note"
    
    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "(title)")
    }
}

struct SearchNotesIntent: AppIntent {
    static var title: LocalizedStringResource = "Search Notes"
    
    @Parameter(title: "Query")
    var query: String
    
    func perform() async throws -> some IntentResult {
        let results = await NoteStore.shared
            .search(query)
            .map { $0.toEntity() }
        return .result(value: results)
    }
}

Integração com Shortcuts e Siri

Após declarar um AppIntent, a integração com Shortcuts e Siri acontece automaticamente. O aplicativo Shortcuts escaneia todos os AppIntents dos aplicativos instalados e os exibe na lista de ações disponíveis. O usuário pode adicionar um intent ao seu atalho, configurar seus parâmetros e combiná-lo com outras ações. Para o Siri, os intents aparecem como comandos de voz sem configuração adicional por parte do desenvolvedor.

O desenvolvedor pode melhorar a integração adicionando suggestedInvocationPhrase — uma frase recomendada para invocação por voz. Por exemplo, para um intent de adicionar tarefa: suggestedInvocationPhrase = "Add new task". O Siri analisa esta frase e a sugere ao usuário ao aprender comandos de voz. Também é possível especificar categories — a categoria do intent (create, view, search, edit), que ajuda o Shortcuts a agrupar ações por significado.

Categorias de intents para Shortcuts