Desenvolva para o app Atalhos e o Spotlight com o App Intents

Olá. Eu sou Ayaka e faço parte da equipe Shortcuts. Esta é a sessão "Desenvolver para o Atalhos e o Spotlight com o App Intents". O framework App Intents deixa os recursos dos seus apps mais visíveis nas nossas plataformas, permitindo que as pessoas usem as funcionalidades principais deles em locais como Atalhos e Spotlight. O app Atalhos permite que as pessoas conectem diferentes apps e suas ações para facilitar o dia a dia. Use o Atalhos para automatizar tarefas repetitivas e conectar-se a outras funcionalidades de outros apps. Por exemplo, para salvar uma receita do Safari em uma nota no app Notas. Este ano, estamos levando o poder da Apple Intelligence para o Atalhos, para tornar a integração dessas ações mais fácil e até mais divertida. Agora você pode executar ações do Atalhos, inclusive as ações do seu app, no Spotlight no Mac. Hoje, vamos mostrar como adotar o App Intents para fazer seu app funcionar perfeitamente com o Atalhos e o Spotlight. Começaremos apresentando a nova ação Use Model, que permite usar modelos da Apple Intelligence nos atalhos. Vamos detalhar como essa ação funciona e mostrar novas formas de executar o Atalhos pelo Spotlight e Automações no Mac. Vamos começar. Esta é a nova ação Use Model. É uma das muitas novas ações inteligentes que adicionamos ao Atalhos este ano, junto com ações para Image Playground, Ferramentas de Escrita e outras. Com essa nova ação, tarefas antes tediosas, como analisar texto ou formatar dados, agora são tão simples quanto escrever algumas palavras. Escolha um modelo grande em servidor na Computação Privada na Nuvem para lidar com solicitações complexas, protegendo sua privacidade, ou o modelo no dispositivo para solicitações simples que não precisam de conexão com a rede. Você pode escolher o ChatGPT se quiser aproveitar seu amplo conhecimento de mundo. Por exemplo, você pode usar um modelo para filtrar eventos do calendário relacionados a uma viagem específica, resumir conteúdo da Web para obter a palavra do dia e até ficar a par da cena gastronômica de San Francisco perguntando ao ChatGPT as novidades. Aqui está um exemplo de atalho que usa um modelo. É um atalho simples que me ajuda a organizar as notas que faço no trabalho diariamente. Primeiro, analisa cada nota criada hoje e usa o modelo com a pergunta: "Esta nota está relacionada à criação de recursos para o app Atalhos?" Se estiver, ele adiciona a nota à pasta de projetos do Atalhos. Como estou usando o resultado do modelo e uma ação if, que espera uma entrada booleana, o tempo de execução gera automaticamente um resultado booleano. Em vez de retornar "Sim, esta nota parece ser sobre a criação de recursos para o app Atalhos", que é útil, mas longo e do tipo errado, o modelo retorna uma resposta booleana de sim ou não, que posso passar para a ação If. Se precisar de mais controle, escolha explicitamente um desses tipos de resultado integrados. Por exemplo, você pode fazer isso ao testar a ação para um fluxo que está planejando, antes de decidir a qual ação conectar à saída. Hoje, quero analisar o texto, o dicionário e o conteúdo dos seus apps e revisar o que você, desenvolvedor, deve fazer para garantir que o resultado do modelo se conecte bem com o que seu app aceita como entrada. Vamos começar com o texto. O texto é a base dos modelos de linguagem. À primeira vista, pode parecer a opção mais simples e fácil, mas na verdade há muita complexidade e detalhes. Literalmente. Isso acontece porque os modelos respondem com texto com formatação. Por exemplo, partes da resposta podem estar em negrito ou itálico. Ela pode até conter uma lista ou uma tabela como esta. Se seu app aceita conteúdo com texto com formatação, garanta que seu App Intents use o tipo de string atribuído para parâmetros de texto, quando apropriado. Uma string atribuída é a combinação de caracteres, intervalos e um dicionário que juntos definem como o texto deve ser renderizado. Com compatibilidade com a entrada da string atribuída, o resultado do modelo pode se conectar perfeitamente e sem perdas ao seu app. Vamos conferir isso na prática. Tenho aqui um atalho que usa o ChatGPT para criar um modelo de entrada de diário para eu usar no app Bear. Pedi para o modelo incluir uma tabela de registro de humor para manhã, tarde e noite, além de um espaço para refletir sobre os destaques do dia. O atalho então pega o resultado do modelo e o envia para a ação Criar Nota do app Bear. Vou mostrar como isso funciona executando o atalho.

E aí está minha nova entrada de diário para hoje. Ela inclui texto com formatação, como negrito em informações importantes, e também a tabela de registro de humor que solicitei. Destaques para hoje? Que tal “Gravei a apresentação da WWDC”?

Enfim, vou terminar esta sessão mais tarde. Como o app Intent Criar Nota do app Bear é compatível com a string atribuída, ele usou o resultado com texto com formatação do modelo e o exibiu sem perdas.

Para saber mais sobre a compatibilidade com strings atribuídas no seu app, confira o vídeo "Novidades do Foundation" e a sessão "Codificar junto: texto com formatação". A seguir, vamos conferir o dicionário. O tipo de resultado de dicionário é útil quando você precisa de vários dados retornados de uma só solicitação em um formato estruturado. Por exemplo, quero criar um atalho que examine todos os arquivos na minha pasta de notas fiscais, extraia informações como provedor, valor e data e adicione-as como uma linha a uma planilha para eu controlar minhas finanças. Para isso, posso usar o modelo para extrair essas informações e especificar como quero que o dicionário de saída seja formatado. Depois, posso usar os valores do dicionário em ações seguintes, como adicionar uma linha em uma planilha. Graças aos modelos de linguagem, consigo transformar dados não estruturados, como o conteúdo de um PDF, na estrutura de que preciso para conectá-los a outra ação. Por fim, vamos abordar o conteúdo dos seus apps. O conteúdo dos apps é representado como entidades definidas por você usando o framework App Intents. Por exemplo, um app de calendário pode fornecer entidades para calendários e eventos. Se os App Intents são as ações ou os verbos do seu app, as App Entities são os substantivos. Você também pode passar App Entities para o modelo. Se você passar uma lista de entidades, como eventos do calendário na solicitação, uma opção extra será exibida: o tipo de entidade do app que você passou. Por exemplo, se eu passar uma lista de eventos do calendário, posso pedir ao modelo para filtrar apenas os eventos relacionados a uma viagem específica. Nos bastidores, a ação envia uma representação JSON da sua entidade para o modelo, então você deve garantir que todas as informações que deseja que ele analise estejam expostas na definição da entidade. Primeiro, todas as propriedades da entidade expostas ao Atalhos serão convertidas em string e incluídas na representação JSON. O nome fornecido na typeDisplayRepresentation será incluído para indicar ao modelo o que essa entidade representa, como um evento de calendário. O título e o subtítulo fornecidos na displayRepresentation da entidade também serão incluídos. Vamos conferir um exemplo.

Na representação simplificada de um evento de calendário, serão incluídos o título do evento, a data de início e de término, o nome do tipo fornecido pela typeDisplayRepresentation e o título e subtítulo fornecidos na displayRepresentation. Essas strings definidas nas entidades também são exibidas no app Atalhos ao inspecionar as propriedades de uma entidade sendo passada para outra ação, então você deve verificar se estão adequadas nesse contexto. Agora que sabemos como estruturar as entidades, vamos garantir que haja uma forma de passar essas entidades para o modelo. Neste caso, as entidades de calendário para filtrar. No Atalhos, a forma mais comum de obter entidades é por meio da ação Encontrar. Esse tipo de ação permite que as pessoas obtenham entidades do seu app usando as próprias propriedades como filtros, como a data de início de um evento ou o respectivo calendário. Você pode criar uma ação Encontrar implementando suas próprias consultas que seguem os protocolos EnumerableEntityQuery e EntityPropertyQuery. Se você já doa suas entidades do app para o Core Spotlight adotando o protocolo IndexedEntity, pode usar novas APIs para associar as propriedades da sua App Entity às chaves de atributos correspondentes do Spotlight, para que o sistema gere uma ação Encontrar. Vamos ver nosso exemplo de EventEntity de antes. Aqui, eu já adaptei EventEntity ao protocolo IndexedEntity. O título, o subtítulo e a imagem da DisplayRepresentation serão associados às suas respectivas chaves de atributo do Spotlight.

Para associar propriedades da sua entidade à chave de atributo correspondente na entidade Spotlight, use o novo parâmetro de chave de indexação. A propriedade eventTitle está sendo associada à chave de atributo eventTitle Spotlight.

Há alguns casos em que não existe uma chave de atributo correspondente já existente. Nesses casos, use o parâmetro de chave de indexação personalizada na propriedade para especificar uma chave personalizada, como fiz com a propriedade notes. Esta é a ação Encontrar que estará disponível no app Atalhos, com base na Indexed Entity. Confira o App Intents do app de monitoramento de viagem disponível em developer.apple.com como outro exemplo. Isso é tudo o que você precisa saber sobre como estruturar as entidades do seu app e fornecê-las ao modelo. Agora, vamos ver outra coisa que as pessoas podem fazer com a ação Use Model. Essa ação dá a opção de "acompanhamento" da solicitação, permitindo interações com o modelo para ajustar a resposta até que esteja correta antes de passá-la para a próxima ação. Deixe-me mostrar como tenho usado isso. Como tenho tentado cozinhar mais, tenho um atalho para extrair a lista de ingredientes de uma receita usando um modelo e adicioná-la à minha Lista de Compras no app Things. Ao ativar a opção de acompanhamento, tenho a possibilidade de revisar minha solicitação inicial e fazer ajustes. Por exemplo, posso pedir ao modelo para fazer modificações na receita antes de salvar os ingredientes. Vamos conferir uma receita de pizza que eu achei no Safari. Aqui está uma receita de pizza napolitana que um amigo compartilhou comigo. Parece muito boa. Vou executar meu atalho para salvar os ingredientes na minha Lista de Compras.

Vou precisar de 400 g de farinha tipo 00, 100 g de farinha integral, fermento e sal. Ficou ótimo. Na verdade, vou fazer uma festa da pizza, então vou fazer um pouco a mais.

Como ativei o acompanhamento, apareceu um campo de texto para eu acompanhar. Vou fazer uma solicitação: "Dobre a receita."

Agora preciso de 800 g de farinha tipo 00 e 200 g de farinha integral. Perfeito!

E aqui estão os ingredientes para minha festa da pizza, no app Things. E essa é a sua nova ação Use Model. Vamos explorar o Spotlight no Mac.

O Spotlight permite pesquisar apps e documentos em todo o sistema. Neste ano, você pode executar ações do seu app diretamente no Spotlight no Mac. Seus apps podem exibir ações no Spotlight adotando App Intents, assim como você faz para o Atalhos. As melhores práticas para criar App Intents para o Atalhos se aplicam ao Spotlight, incluindo a elaboração de um resumo dos parâmetros. Um resumo de parâmetros é uma breve descrição em linguagem natural do que o App Intent realiza, incluindo os parâmetros que precisa executar.

Esse mesmo resumo de parâmetros é exibido no editor do Atalhos quando você cria um atalho. O Spotlight é focado em executar coisas rapidamente. Para isso, as pessoas precisam fornecer, direto no Spotlight, todas as informações que a Intent precisa para executar. Vou explicar como fazer isso. O resumo de parâmetros, o que as pessoas verão na interface do Spotlight, deve incluir todos os parâmetros obrigatórios que não têm valor padrão. Se você tiver um Intent que não tem parâmetros obrigatórios como esse, não é necessário fornecer um resumo de parâmetros. O Spotlight pode recorrer a exibir apenas o título do Intent nesse caso. Você também deve garantir que o Intent não esteja oculto do Atalhos no Spotlight. Por exemplo, ao definir "is discoverable" como false ou "assistant only" como true na implementação do seu Intent. Se você já adotou um Intent para configuração de widget que não tem um método perform, ele também não aparecerá no Spotlight. Vamos explorar alguns exemplos.

Tenho aqui um Intent chamado CreateEventIntent que as pessoas podem usar para criar um evento no calendário. Ele tem três parâmetros: title, start date e end date. Esse Intent aparecerá no Spotlight porque todos os parâmetros obrigatórios estão incluídos no resumo de parâmetros. Porém, se eu adicionar um novo parâmetro notes como obrigatório, sem valor padrão, e não incluí-lo no resumo de parâmetros, o Intent não aparecerá no Spotlight. Mas se eu tornar o parâmetro notes opcional, o Intent voltará a aparecer no Spotlight.

Como alternativa, eu poderia manter o parâmetro obrigatório e fornecer um valor padrão, como uma string vazia neste caso.

Para saber as melhores práticas de criação de resumos de parâmetros, como escolher os parâmetros opcionais, confira o vídeo "Criar App Intents para experiências no sistema." Depois que seu Intent aparecer no Spotlight, otimize a experiência do usuário. Isso inclui sugestões de suporte, busca por digitação e oferecer opções para execução em primeiro e segundo plano. Vamos conferir. Quando alguém busca e seleciona seu Intent no Spotlight, é necessário preencher os parâmetros obrigatórios antes de executá-lo. Para agilizar essa interação, você deve fornecer sugestões para preencher esses parâmetros. Existem alguns protocolos que você pode implementar para isso.

Você pode implementar suggestedEntities como parte do protocolo EntityQuery ou todas as entidades como parte do protocolo EnumerableEntityQuery. Você deve usar entidades sugeridas quando quiser oferecer um subconjunto de uma lista grande ou ilimitada de entidades, por exemplo, uma lista de eventos do calendário para o dia seguinte, em vez de todos os eventos. allEntities é ideal quando a lista de entidades é menor e limitada, por exemplo, uma lista de fusos horários. Você também pode marcar o conteúdo na tela configurando a propriedade appEntityIdentifier em NSUserActivity para fornecer sugestões baseadas no conteúdo ou entidade ativo no momento. Como a visualização detalhada de um evento específico no calendário. Para saber sobre essa API, confira a sessão "Explorar os avanços do App Intents". Por fim, seu Intent também pode adotar o protocolo PredictableIntent, para que o Spotlight exiba sugestões baseadas em como esse Intent é usado. Vamos analisar a experiência quando alguém começa a digitar em um campo de parâmetro. Se você já implementou sugestões, automaticamente terá funcionalidades básicas de busca e filtragem para as sugestões fornecidas. No entanto, caso haja mais entidades além das sugestões que alguém pode querer selecionar, você deve adicionar suporte a pesquisa mais avançada implementando consultas.

Você pode implementar o protocolo EntityStringQuery ou implementar IndexedEntity, como vimos anteriormente. Confira um exemplo de implementação de EntityStringQuery no App Intents do app com código de exemplo, disponível em developer.apple.com. Para saber detalhes sobre como implementar IndexedEntity, confira o vídeo "Novidades do App Intents" de 2024. Agora, vamos considerar a experiência de execução da ação. No exemplo de criação de um evento, às vezes as pessoas preferem que a ação seja executada em segundo plano, de maneira rápida, mas em outros casos, é interessante ver o evento criado no próprio app. Para permitir ambos os tipos de experiência, você pode separar seus Intents, quando apropriado, em Intents de primeiro e segundo plano. Por exemplo, podemos definir o Intent Criar evento como um Intent de segundo plano, permitindo que as pessoas criem eventos no calendário sem abrir o app. Também podemos ter um Intent Abrir evento que leva o app para o primeiro plano ao abrir um evento específico, o que é uma ação útil. Podemos então combinar esses dois Intents fazendo com que o Intent de segundo plano retorne o Intent de primeiro plano como OpensIntent. Neste caso, o Intent Criar evento pode retornar um Intent Abrir evento como OpensIntent. Para saber mais detalhes sobre isso, confira o vídeo "Detalhes do App Intents". E esse é o Spotlight no Mac. Agora, vamos abordar as Automações. Neste ano, estamos trazendo as automações pessoais para o Mac, com novos tipos de automações, como automações para pastas e unidades externas, criadas para o Mac, além de tipos que você já conhece do iOS, como Hora do Dia e Bluetooth. Por exemplo, posso fazer que meu atalho de processamento de notas fiscais ser executado toda vez que eu adicionar uma nova nota fiscal a uma pasta específica em vez de executá-lo manualmente. Se o seu Intent estiver disponível no macOS, ele poderá ser usado no Atalhos para ser executado como parte das Automações no Mac. Isso inclui apps do iOS que podem ser instalados no macOS.

Isso adiciona o Spotlight e as Automações no Mac às várias formas de executar Atalhos, incluindo botão de Ação, Central de Controle e muito mais. Com a adição de novas ações inteligentes como Use Model, as possibilidades de como as ações do seu app podem ser usadas em todo o sistema são infinitas. Vamos finalizar com alguns próximos passos. Primeiro, exponha o conteúdo do seu app como entidades que funcionem bem no Atalhos, incluindo a nova ação Use Model. Isso significa expor ações de busca e garantir que as entidades apresentem propriedades-chave que você gostaria que o modelo pudesse analisar. Use strings atribuídas para permitir que texto com formatação seja passado para seus apps, como vimos na demonstração do app Bear. Por fim, otimize seus Intents para o Spotlight no Mac e garanta que também fiquem ótimos no Atalhos. Agradeço sua participação!