Conheça o App Intents

Olá! Sou James, gerente de engenharia da equipe Swift Intelligence Frameworks. Estou animado para falar sobre o App Intents, um framework para estender a capacidade de descoberta, a visibilidade e os recursos do seu app em todo o sistema e em todas as plataformas Apple. Vou começar falando sobre o papel cada vez mais importante do App Intents no ecossistema de desenvolvedores da Apple. Depois, mostrarei como usar o framework para disponibilizar as ações e entidades do seu app para as pessoas em todo o sistema. No final, compartilharei detalhes importantes que você deve saber ao escrever seu App Intents. Antes de falarmos como usar o App Intents, temos de falar sobre o “porquê”. O App Intents é mais que o framework que você traz para o seu app para criar recursos. É um ecossistema que permite que a funcionalidade do app se expanda para todo o sistema.

O App Intents permite oferecer resultados personalizados no Spotlight, experiências com base no contexto no botão de Ação, configurabilidade e interatividade em widgets, controles fáceis na Central de Controle e ações personalizadas para o Apple Pencil Pro.

Novidade este ano, o Spotlight pode invocar as ações do app de qualquer lugar do Mac.

O framework App Intents permite que você propicie experiências robustas aos clientes, mesmo quando eles não estão no app. Tudo começa com as ações que o app pode realizar, como abrir uma nota, começar um treino ou adicionar um item a uma lista de compras. São os verbos do app e, como você deve imaginar, você os descreve criando App Intents, ou simplesmente Intents. Ao criar um Intent, você fornece ao sistema informações adicionais para executar corretamente a ação. Os Intents podem precisar de parâmetros e valores de retorno. Essas entradas e saídas podem ser tipos de Swift nativos ou tipos definidos no app. É possível criar dois tipos de valores com o App Intents. Use um AppEnum para os tipos com um conjunto constante de valores e, para fontes dinâmicas, use uma AppEntity. AppEnums e AppEntities são os substantivos no seu app. Os atalhos de app permitem elevar suas principais Intents, tornando-as mais acessíveis e detectáveis. Eles aparecem ao pesquisar no Spotlight, usar a Siri, configurar o botão de Ação e muito mais. Digamos que estas sejam as frases do seu app, feitas a partir de um Intent e de parâmetros que o Intent precise executar. Acho que a melhor forma de aprender é colocar em prática. Vejamos o que é necessário para criar meu primeiro Intent. Adoro viajar com minha família, e estou trabalhando em um app para conferir marcos famosos ao redor do mundo. Meu app tem algumas seções. Posso rolar uma lista de marcos famosos, vê-los em um mapa ou visualizar coleções criadas por mim. Muitos usuários gostam de rolar a grade dos marcos. Vou criar um App Intent para tornar a navegação diretamente para essa parte do app mais conveniente. Então, como faço isso? Começarei definindo uma estrutura nova que adota o protocolo App Intents. Os requisitos mínimos para um App Intent são um título e um método de execução.

O título é uma string exclusiva e localizada que aparecerá como o nome do Intent. O método de execução contém a lógica do Intent. Vou usar um navegador compartilhado para abrir a visualização dos marcos. A navegação deve ser feita no thread principal, por isso vou marcar com @MainActor.

O método de execução retorna um resultado do Intent. Os resultados do Intent podem conter várias coisas, inclusive diálogos que a Siri pode falar e um fragmento da visualização. Por padrão, executar um Intent não colocará o app em primeiro plano. Então, fornecer diálogo e um fragmento é ótimo para mostrar o resultado da ação.

Como esse Intent foi projetado para navegar em telas no app, vou configurar o Intent para abrir quando for executado. Vou definir a nova propriedade supportedModes como primeiro plano para abrir o app antes da execução do Intent, e isso basta para criar o primeiro Intent. Depois de instalar o app, os Intents podem ser encontrados em Atalhos. Posso criar um novo atalho e adicionar meu Intent de navegação. Ele coloca o app em primeiro plano e me leva diretamente à visualização dos marcos. Meu app também tem seções para visualizar coleções e exibir os marcos em um mapa. Seria ótimo se o Intent também pudesse acessar essas partes do app. Meu app usa um simples Swift Enum para modelar seções. Para tornar o tipo compatível com o framework, vou adotar o protocolo AppEnum. Os AppEnums têm apenas alguns requisitos. Eles devem ser instanciáveis a partir de uma string, então vou adicionar um valor bruto. Um TypeDisplayRepresentation descreve o tipo como um todo, e um CaseDisplayRepresentation descreve cada caso do Enum.

Essas representações devem ser valores constantes, pois essas informações são usadas em tempo de compilação.

No meu Intent, vou adicionar uma variável nova para manter a opção de navegação. Vou adicionar o atributo @Parameter para transformar isso em um parâmetro de Intent. Os parâmetros de Intent atuam como entradas para Intents. Eles podem ser obrigatórios ou opcionais. Tornei isso obrigatório, então o tempo de execução garantirá que ele tenha um valor antes da execução.

Vou atualizar o método de execução para usar a opção de navegação resolvida e alterar o título para refletir a nova ação.

Voltando ao meu atalho, agora vejo a opção de navegação como um parâmetro editável. Quando eu executar o Intent, o Atalhos solicitará a seção. Vou escolher Mapa, e abrirá diretamente essa visualização. Os tipos de framework do App Intents são altamente personalizáveis. Isso permite colocar os elementos essenciais no lugar e refinar a experiência. Vou adicionar algumas informações ao Intent, aprimorando seu uso.

Por padrão, o Atalhos mostrará cada parâmetro como uma linha. Tocar na linha exibirá uma lista de valores para esse tipo. Isso funciona, mas posso fazer algumas coisas para refinar a experiência.

Um AppEnum requer apenas um título para cada caso de Enum, mas pode ser configurado com informações adicionais, como um ícone.

Para adicionar um ícone, terei de usar o inicializador DisplayRepresentation. Posso então adicionar um símbolo para cada caso. Assim que eu fizer isso, o Atalhos exibirá a imagem no seletor. Os Intents podem ser configurados com uma representação fluente, semelhante a uma frase, chamada ParameterSummary. Um ParameterSummary descreve a ação e seus parâmetros de forma legível por humanos.

Vou fornecer o resumo com meu parâmetro interpolado na string. O Atalhos exibirá o resumo com o parâmetro selecionável alinhado, fornecendo uma descrição mais útil da ação.

Na verdade, isso ainda não parece uma frase. Posso corrigir adicionando um título personalizado ao parâmetro.

Já que estou aqui, também vou adicionar uma caixa de diálogo personalizada ao solicitar um valor. Uma novidade este ano: Ao implementar um ParameterSummary para o Intent, incluindo os parâmetros necessários, será possível executar a ação no Spotlight no Mac. Para saber mais sobre novas adições ao Spotlight, recomendo que você assista a esta sessão.

Modelar as ações do app como Intents permite que os clientes criem atalhos e automações úteis. No entanto, alguns Intents são tão essenciais para o app que devem estar disponíveis no momento em que ele é instalado. Você pode fornecê-las adotando atalhos de app.

Um atalho de app expõe automaticamente um App Intent em todo o sistema. Os atalhos de app ganham destaque nas buscas no Spotlight. As pessoas podem usar a Siri para ativar um atalho de app falando uma frase predefinida. Pode-se definir que eles sejam executados a partir do botão de Ação ou do Apple Pencil. Os atalhos serão exibidos no app Atalhos sem qualquer configuração do usuário, e o que é melhor: Só é preciso compilar algumas linhas de código. Vejamos como.

Apps fornecem atalhos por meio de um provedor de atalhos de app. Seu app deve definir um único provedor, contendo todos os atalhos de app. Um atalho de app usa uma instância de um Intent, bem como uma lista de frases, um título e uma imagem. As frases de um atalho de app podem ser ditas ou digitadas para que a Siri execute o atalho. Cada frase deve incluir o marcador de posição applicationName. As frases podem incluir até um parâmetro de Intent. Caso seja fornecido, um atalho de app para cada valor desse tipo será criado.

Essa estrutura simples basta para criar um atalho de app. O Atalhos mostrará os atalhos do seu app em uma nova seção. As frases influenciam os atalhos de app que são criados. Fornecer uma frase sem um parâmetro criará um atalho de app usando o título e o nome da imagem. Como forneci uma frase com um AppEnum, será criado um atalho de app para cada caso.

Posso executar meu Intent com a Siri ou o Spotlight. Os atalhos de app são ótimos para tornar os Intents detectáveis. Para saber mais sobre a criação de atalhos de apps, confira esta sessão da WWDC23.

Os marcos são um conceito central no meu app. Seria ótimo poder executar ações com base nos Intents. Ao contrário da lista constante de opções de navegação, os marcos são dinâmicos, então não posso usar um AppEnum. Em vez disso, vou criar uma entidade do app para modelar meus marcos.

Meu app já tem um tipo de marco. Embora eu possa conformá-lo à entidade do app, neste caso, vou criar uma nova estrutura LandmarkEntity. Esse tipo atuará como uma ponte entre o App Intents e meu modelo de dados subjacente.

As entidades devem ser identificáveis, então adicionarei uma ID. É importante que esse identificador seja persistente e que você possa procurar instâncias de sua entidade por essa ID. Voltaremos a falar disso. Semelhante a um Intent com parâmetros, as entidades podem ter propriedades indicadas com o atributo @Property. Elas serão expostas aos clientes em Atalhos e poderão ser usadas em ações de Localizar e Filtrar. Eu poderia definir esses valores a partir do meu modelo de dados, mas agora posso adicionar Getters às minhas propriedades de entidade, usando o novo atributo @ComputedProperty. Em vez de copiar valores entre esses tipos, posso transferir para o meu modelo de dados. Assim como AppEnums, as entidades do app exigem uma representação para o tipo e as instâncias do tipo.

As entidades do app requerem uma informação adicional, conhecida como consulta.

Diferente de um AppEnum, que tem um conjunto conhecido de valores, as entidades do app são dinâmicas. Meu app pode ter vários marcos. As consultas são o modo como o sistema interpreta minhas entidades. Ele faz isso respondendo a uma série de perguntas diferentes. O primeiro tipo de pergunta é: “Que entidades existem?” A consulta é responsável por responder a essa pergunta e retornar uma coleção de entidades correspondentes.

As consultas aceitam muitas dessas perguntas. Por exemplo, uma consulta de strings de entidade: “Você tem uma entidade que corresponda a esta string?” Uma consulta de propriedade de entidade pode ser: “Quais são os marcos deste estado?”

Todas as consultas devem responder a uma pergunta muito específica: “Qual é a entidade desta ID?”

Isso permite que o sistema faça referência exclusiva a uma entidade e só a resolva quando necessário.

Posso fornecer a consulta ao criar um tipo que combine com o protocolo de consulta de entidade. O método entities(for:) é como as consultas respondem à pergunta: “Qual entidade tem essa ID?” Ele usa uma matriz de identificadores e retorna uma matriz de instâncias de entidade. Voltaremos à pergunta “Que entidades existem?” mais tarde. As consultas precisam de acesso a um banco de dados local ou outra dependência para buscar instâncias. Posso usar o atributo @Dependency para injetar dependências em minha consulta. Vou precisar registrar minha dependência usando o Gerenciador de Dependência de App compartilhado. É preciso registrar dependências o mais cedo possível no ciclo de vida do seu app. Agora que criei uma entidade Marco, posso usá-la de acordo com meus Intents. Ao viajar, seria ótimo saber qual é o marco mais próximo. Farei um App Intent para me mostrar isso. Vou começar com um Intent básico do marco mais próximo. Vou precisar buscar o marco mais próximo do meu modelo de dados. As dependências também são compatíveis com Intents, para que eu possa adicionar a dependência. Para o método de execução, vou adicionar um ReturnsValue da entidade Marco. Os tipos usados como parâmetros de Intent podem retornar de um Intent. Um valor retornado pode ser usado como entrada para outro Intent, como em um atalho de várias etapas. Também retornarei uma caixa de diálogo e um fragmento de visualização. Isso permite que meu Intent mostre ou fale o respectivo resultado. Por fim, posso implementar o método de execução. Depois de encontrar o marco mais próximo, retornarei um resultado contendo a entidade, a caixa de diálogo e a visualização. Ao fornecer uma caixa de diálogo e uma visualização, garanto que os clientes sempre encontrem o marco mais próximo, não importa como o Intent foi invocado. Fazer um atalho de app para esse Intent facilitará ainda mais a execução do Intent. Os clientes agora podem usar a Siri ou o Spotlight para ter acesso a esse Intent, mesmo que o telefone esteja no bolso. Intents, entidades e consultas são os pilares do App Intents. Cada protocolo tem subprotocolos e configurações que proporcionam funcionalidade adicional. Vamos ver como refinar minha entidade de app para fornecer experiências adicionais. Gostaria de ver facilmente uma foto do marco mais próximo de mim. Posso usar o app Atalhos para me ajudar. Vou começar criando um atalho e adicionando o Intent Find Closest Landmark. Para conferir os resultados, vou adicionar uma ação Show Content. Isso vai pegar o resultado do meu Intent e renderizá-lo. Por padrão, essa ação mostrará a representação de visualização da entidade Marco, mas posso escolher qualquer propriedade de entidade para renderizar.

A entidade Marco não mostra uma imagem diretamente, mas um caminho para a imagem. Posso usar o protocolo Transferable para declarar uma representação de imagem para a entidade. Transferable é uma maneira declarativa de descrever diferentes representações de dados para um tipo. Essas representações podem ser usadas para compartilhar dados entre os apps. Fornecerei os dados da imagem como parte da representação de transferência do tipo. De volta ao Atalhos, agora posso mostrar a representação de imagem da entidade. Executar meu atalho mostrará a imagem do marco. Declarar uma representação de imagem tem outras vantagens. Posso usar esse valor de imagem como entrada para qualquer ação que tire uma foto, mesmo em outros apps. Para saber mais sobre Transferable, confira estas sessões.

Gostaria de fazer mais uma alteração na minha entidade para facilitar a localização no sistema. O Spotlight oferece uma pesquisa semântica eficaz em todos os apps. Doar entidades para o Spotlight amplia a compreensão do sistema sobre seu conteúdo. Para que o Spotlight indexe minha entidade, posso adotar o protocolo de entidade indexada. Uma entidade indexada inclui um conjunto de atributos principais do Spotlight.

Uma novidade este ano é poder adicionar chaves de indexação do Spotlight diretamente nas propriedades. Anotar propriedades permite que o Spotlight mostre informações mais relevantes aos clientes. Ao doar entidades indexadas, o framework cuidará da criação do item pesquisável e do atributo definidos para você. Após a doação das entidades, elas podem ser encontradas no Spotlight. Por padrão, tocar em uma entidade colocará o app em primeiro plano. Posso tornar essa experiência ainda melhor e abrir diretamente a visualização de detalhes do marco. Começarei criando um Intent em conformidade com o protocolo Open Intent. Os Intents que adotarem esse protocolo abrirão o app antes que seja executado, então não preciso incluir um modo compatível. As ações OpenIntents devem ter um parâmetro de destino. Ao tocar em uma entidade no Spotlight, ela executará a ação OpenIntent correspondente, se houver.

Em vez de chamar meu navegador, posso adotar o novo protocolo TargetContentProvidingIntent, projetado especificamente para navegação. Esses Intents não exigem um método de execução. Em vez disso, posso anexar um modificador onAppIntentExecution à visualização. Ao fechar, posso usar o parâmetro do Intent para executar uma navegação na SwiftUI.

Agora, ao tocar em um marco no Spotlight, vou navegar direto para a visualização de detalhes desse marco. Gostaria de encerrar esta seção falando um pouco mais sobre consultas e como elas fornecem entidades. Para ver isso na prática, vou criar um novo atalho de app para abrir um marco. Vou adicionar um novo atalho de app ao meu provedor junto com duas frases. Uma com um parâmetro de marco, e outra sem. No entanto, executar meu atalho de app não me dá nenhum marco para escolher. Como você deve ter imaginado, posso usar a consulta para fornecer alguns marcos. Vou implementar o método opcional suggestedEntities na consulta de entidade, retornando os marcos favoritos do cliente. Agora, ao executar o Intent novamente, recebo a lista de entidades sugeridas. As entidades sugeridas também têm outra utilidade. Lembra quando adicionei uma frase parametrizada para esse Intent? Posso gerar um atalho de app para cada entidade sugerida chamando o método updateAppShortcutParameters em meu provedor. Agora posso usar a Siri e o Atalhos para navegar diretamente até meus marcos favoritos. As consultas podem responder a uma série de outras perguntas sobre suas entidades. Se todas as entidades couberem na memória, você poderá usar uma consulta de entidade enumerável para retornar todas elas. O App Intents pode derivar as consultas mais complicadas. Uma consulta de propriedade de entidade permite retornar uma lista classificada de entidades, dado um conjunto de predicados. Vou implementar uma consulta de strings de entidade para permitir a localização de entidades de uma string. Vou ter uma lista de marcos em que a string corresponde ao nome ou à descrição. Os clientes poderão buscar todos os marcos ao configurar um Intent que precisa de um marco. Vimos só o básico do framework App Intents e suas inúmeras capacidades. Confira a documentação do App Intents para ver como usar o framework e encantar seus usuários. Gostaria de terminar com algumas informações sobre a arquitetura por trás do App Intents. Ao criar seu app com o App Intents, seu código é a fonte da verdade. O App Intents não requer nenhum arquivo de instalação ou configuração. Seu código-fonte do Swift será lido em tempo de compilação para gerar sua representação do App Intents. Essa representação é armazenada dentro do app ou framework. Depois que o app estiver instalado, o sistema usará esses dados para entender os recursos do app sem precisar executá-lo. Vamos conferir um Intent para ver como isso funciona. O nome do Intent torna-se o identificador exclusivo da ação. O título ajuda os usuários a diferenciar os Intents, e a assinatura de retorno do método de execução descreve como renderizar o resultado do Intent. Como esse processo acontece em tempo de compilação, e não em tempo de execução, certos valores devem ser constantes.

Por exemplo, o título de um Intent deve ser constante. Chamar para uma função ou propriedade computada resultará em um erro. Esse processamento acontece individualmente para cada destino no app. Para compartilhar os tipos de App Intent entre os destinos, é preciso ter alguns outros fatores em mente. Ano passado, apresentamos a possibilidade do app e das extensões App Intents fazerem referência aos tipos de Intent definidos em um framework. Este ano, estamos felizes em anunciar que é possível adicionar App Intents a pacotes do Swift e bibliotecas estáticas. Ao usar tipos de App Intent entre destinos, você deve fornecer ao tempo de execução informações adicionais de cada destino. Isso garante que os tipos sejam indexados e validados corretamente. Vamos ver como se faz. Meu app tem apenas um único destino contendo todo o meu código do App Intents. Quero apresentar uma nova extensão do App Intents para hospedar alguns Intents. Ambos os alvos precisarão de acesso aos marcos. Então, vou criar um pacote Swift e mover minha entidade Marco para ele. Para compartilhar tipos entre destinos, preciso registrar cada destino como um AppIntentsPackage. Primeiro, vou criar um AppIntentsPackage no mesmo destino da entidade. Vou adicionar outro AppIntentsPackage ao destino do app. Posso fornecer uma lista de pacotes incluídos, então incluirei o que acabei de criar. Por fim, farei o mesmo da minha extensão. Isso garantirá que o tempo de execução do App Intents tenha acesso adequado a todos os tipos definidos no pacote. Você deve usar o AppIntentsPackage ao referenciar código não compilado em uma biblioteca estática.

Hora de encerrar a apresentação. Se esta foi sua primeira noção do App Intents, comece devagar, adicionado o primeiro atalho ao seu app. Depois, explore o framework para verificar quais recursos podem agregar mais valor a seus clientes. Para saber mais sobre o App Intents, temos outras ótimas sessões este ano. Agradeço por assistir!