Criar shortcuts.xml

Depois de identificar a funcionalidade do app e a intent integrada (BII, na sigla em inglês) correspondente para implementação, declare as BIIs que podem ser usadas com a função definindo um elemento capability em um arquivo de recurso shortcuts.xml. Declarar uma BII como um elemento capability registra o suporte para essa intent semântica no seu app e permite o fulfillment de consulta por voz da intent usando o Google Assistente.

O processamento de linguagem natural é usado pelo Google Assistente para extrair parâmetros de uma consulta do usuário. A referência de intents integradas lista os campos que cada BII pode extrair de uma consulta de usuário associada. Por exemplo, se um usuário invocar o recurso [actions.intent.GET_FOOD_OBSERVATION][] no seu app dizendo "Ok Google, pergunte ao AppDeExemplo o que eu comi no almoço da sexta-feira passada", o Google Assistente extrai os seguintes parâmetros de BII da solicitação do usuário:

• foodObservation.forMeal = "https://schema.googleapis.com/MealTypeLunch"
• foodObservation.startTime = "2024-09-06T00:00:00"
• foodObservation.endTime = "2024-09-06T23:59:59"

O Google Assistente transmite os parâmetros de BII para a intent de fulfillment definida em capability. Um ou mais elementos intent podem ser definidos em um recurso para acomodar as diferentes maneiras em que um usuário pode invocar uma BII. Por exemplo, você pode definir uma intent de fulfillment que exija os dois parâmetros de BII no exemplo acima. Depois, você pode definir uma segunda intent que exija um único parâmetro de BII, foodObservation.forMeal, que vai informar todas as refeições em um dia específico, como "Ok Google, pergunte ao ExampleApp o que eu comi no almoço".

Visão geral

Para configurar as Ações no app, use um arquivo shortcuts.xml localizado no diretório res/xml do projeto do app e crie uma referência ao shortcuts.xml no manifesto. Adicione uma referência ao shortcuts.xml no manifesto do app seguindo estas etapas:

1. No arquivo de manifesto do app (AndroidManifest.xml), localize uma atividade cujos filtros de intent estejam configurados para a ação android.intent.action.MAIN e a categoria android.intent.category.LAUNCHER.

2. Adicione uma referência ao shortcuts.xml no AndroidManifest.xml usando uma tag <meta-data> na Activity que tenha filtros de intent para MAIN e LAUNCHER, conforme mostrado abaixo:

   <meta-data
      android:name="android.app.shortcuts"
      android:resource="@xml/shortcuts" />
   

O exemplo acima declara um recurso XML para o arquivo xml/shortcuts.xml no APK. Para ver mais detalhes sobre como configurar atalhos, consulte Criar atalhos estáticos na documentação para desenvolvedores Android.

É necessário usar a biblioteca Jetpack androidx.core:core:1.6.0 (ou mais recente) no seu projeto Android para evitar erros de compilação ao definir os recursos das Ações no app no shortcuts.xml. Para mais detalhes, consulte Introdução ao Android Jetpack.

Atalhos estáticos

Ao definir seu capability, você pode declarar elementos shortcut estáticos no shortcuts.xml para ampliar a funcionalidade do recurso. Os atalhos estáticos são ingeridos pelo Google Assistente quando você faz upload de uma versão para o Google Play Console. Como esses atalhos só podem ser criados e atualizados criando novas versões, eles são mais úteis para destacar atividades e conteúdos comuns no app.

É possível ativar as seguintes funções das Ações no app com atalhos estáticos:

• Atalhos de recurso: crie atalhos que iniciem uma instância do seu capability contendo valores de parâmetros predefinidos de intent. Por exemplo, você pode declarar um atalho "Iniciar uma corrida" para o app, que invoca o recurso da BII START_EXERCISE no seu app fitness.

  Esses atalhos contêm os atributos intent, shortLabel e longLabel, permitindo que eles sejam sugeridos e enviados como ícones (link em inglês) em plataformas proativas, como o Google Assistente, ou ao tocar no ícone de um app na tela de início do Android e o manter pressionado. Um atalho de ação também pode servir como um atalho de entidade, detalhado abaixo, quando associado a um capability usando uma tag <capability-binding>.

• Atalhos de entidade. Os atalhos de entidade fornecem uma lista de valores de parâmetro compatíveis para o fulfillment da consulta de voz de um capability. Por exemplo, um atalho de entidade com uma lista de tipos de exercício ("caminhada", "corrida" etc.) vinculados ao parâmetro da BII exercise.name do recurso START_EXERCISE. Se uma fala do usuário corresponder a uma entidade, o ID do shortcutId será transmitido para a intent em vez do valor bruto da consulta.

  Os atalhos da Entity não definem os atributos intent, shortLabel ou longLabel. Por isso, eles não são sugeridos em plataformas proativas. Para saber mais, consulte a seção Inventário inline para Ações no app.

Esquema de recursos

A tabela a seguir descreve o esquema de Ações no app para elementos capability no shortcuts.xml. Ao incluir uma tag, todos os atributos dela são obrigatórios, a menos que marcados como "opcionais".

Descrição do esquema de recursos

Nesta seção, descrevemos os elementos do esquema de capability.

<capability>

Um elemento capability que define a intent da ação no app que pode ser usada no seu aplicativo. Cada elemento <capability> no arquivo shortcuts.xml precisa fornecer pelo menos uma <intent> para processar o fulfillment da ação.

Atributos:

• android:name: ID da ação da intent integrada (por exemplo, [actions.intent.GET_FOOD_OBSERVATION][]). Para acessar uma lista de intents integradas com suporte, consulte a referência de intents integradas.
• app:queryPatterns: uma matriz de strings das consultas esperadas do usuário para essa intent. Esse atributo só é aplicável a intents personalizadas, porque as BIIs já incluem modelos das maneiras comuns em que os usuários expressam as tarefas que estão tentando fazer ou as informações que procuram.

<intent>

Elemento intent do Android que define como uma consulta de usuário precisa ser atendida usando a funcionalidade do app. Os desenvolvedores podem fornecer várias tags <intent> em um capability. O Google Assistente tenta realizar uma consulta de usuário utilizando a primeira <intent> em um capability para o qual todos os parâmetros necessários são fornecidos.

Atributos:

• android:action: o tipo de Action da intent. O valor padrão é ACTION_VIEW.
• android:targetClass: classe da atividade de destino. Por exemplo, "com.example.exercise.ExerciseActivity"
• android:targetPackage: pacote que contém a classe da atividade de destino. Por exemplo, "com.example.exercise.
• android:data: esse campo vai ser substituído por <url-template> se essa tag for declarada na intent.

<url-template>

Modelo para criação de um URI de link direto que será aberto no dispositivo. O modelo pode ser ampliado com parâmetros de intent integrada caso todos os parâmetros necessários para ele estejam disponíveis. Para ver exemplos do modelo de URL HTTP, consulte o artigo da Wikipédia sobre modelos de URL. O formato segue a especificação de modelos de URI RFC6570 (links em inglês).

Confira abaixo alguns exemplos de valores de modelo de URL:

Para saber mais sobre como configurar modelos de URL, consulte os modelos de URL no fulfillment.

<extra>

Define os dados de extras para uma intent. No caso das Ações no app, esse campo é usado apenas para ativar a [invocação de app em primeiro plano][] para um capability.

<parameter>

Associa um parâmetro de BII a valores de parâmetros de intent. Para mais informações, consulte a seção Correspondência e dados de parâmetros.

Atributos:

• android:name: nome do parâmetro da BII que deve ser associado a esse parâmetro de intent. O nome precisa ser um campo no nível da folha do parâmetro de BII, por exemplo, foodObservation.aboutFood.name.
• android:key: chave definida pelo desenvolvedor de um valor de parâmetro de BII. Por exemplo, você pode definir contact_name para o parâmetro de BII message.recipient.name.
• android:mimeType: o Tipo MIME do parâmetro, como text/*. Esse campo é obrigatório apenas para parâmetros de intents personalizadas.
• android:required: declara se a consulta do usuário precisa incluir esse parâmetro para que a intent seja usada para fulfillment. Se o parâmetro não estiver disponível, o Google Assistente vai tentar realizar a consulta do usuário usando a próxima intent definida para o elemento capability.

<shortcut-fulfillment>

Especifica que uma intent definida em um atalho de inventário inline para um parâmetro especificado é usada para fulfillment. Para ver mais detalhes, consulte a seção Fulfillment usando intents de atalhos.

<parameter> (para <shortcut-fulfillment>)

Atributo opcional que associa um único parâmetro de BII ao fulfillment do atalho de inventário inline. Para ver mais detalhes, consulte a seção Fulfillment usando intents de atalhos.

Atributo:

• android:name: nome do parâmetro de BII para associar ao fulfillment do atalho do inventário inline. O nome precisa ser um campo no nível da folha do parâmetro de BII (por exemplo, menuItem.name).

<slice>

Permite que o Google Assistente incorpore o resultado de uma consulta correspondente a esse capability como um Slice do Android. Para ver mais detalhes, consulte Integrar Ações no app com Slices do Android.

Esquema de atalho

A tabela abaixo descreve os atributos dos elementos shortcut usados para ativar a funcionalidade de Ações no app. Ao incluir uma tag, todos os atributos dela são obrigatórios, a menos que marcados como "opcionais".

Descrição do esquema de atalho

Nesta seção, descrevemos os elementos do esquema de shortcut.

<shortcut>

Um <shortcut> do Android definido no shortcuts.xml com determinados atributos que são relevantes para as Ações no app. Os valores de string dos campos shortcutShortLabel e shortcutLongLabel são referenciados usando os recursos de string do APK.

Atributos:

• android:shortcutId: identificador desse atalho.
• android:shortcutShortLabel: recurso de string que representa uma frase de atalho curta. Por exemplo, "@string/callDavidShort", que representa o valor "Call David" (Ligar para David).
• android:shortcutLongLabel: recurso de string que representa uma frase de atalho longa. Por exemplo, "@string/callDavidLong", que representa o valor "Make an audio call to David" (Fazer uma chamada de áudio para David).

<intent>

Intent do Android associada a esse atalho. Essa intent é executada quando um usuário inicia esse atalho por voz ou por toque.

Os atributos de intent do shortcut são idênticos aos atributos de capability do intent.

<capability-binding>

Associa um shortcut a um capability de Ações no app. A adição desse elemento a um shortcut permite que ele realize o fulfillment de voz usando o Assistant.

Atributos:

• android:key: o atributo android:name do capability ao qual esse shortcut está vinculado. Por exemplo: actions.intent.START_EXERCISE.

<parameter-binding>

Atributo opcional que associa um shortcut a um único parâmetro de um capability de Ações no app. Se um parameter-binding for definido para um shortcut, o atalho vai poder ser usado para fornecer uma entidade de inventário inline a um parâmetro de BII. Para mais detalhes, consulte a seção Inventário inline para Ações no app.

Atributos:

• android:key: o nome do parâmetro de BII capability para associar a esse atalho. Por exemplo: exercise.name.
• android:value: o valor de entity Pode ser uma única entity ou uma lista de recursos.

<extra>

Os dados do pacote de extra para o atalho. O sameAs é o único dado relevante para elementos shortcut de Ações no app. O URL sameAs se refere a uma página da Web de referência que identifica claramente a entidade. Usado para especificar um valor de enumeração apenas se o tipo de parâmetro da intent for um subtipo de schema.org/Enumeration (link em inglês). Ele é necessário para campos de parâmetro com tipos que são subtipos de schema.org/Enumeration. Por exemplo, MealTypeBreakfast (link em inglês).

Atributos:

• android:key: o valor aceito para Ações no app é o sameAs.
• android:value: o valor do URL sameAs.

Para mais detalhes, consulte a seção Corresponder valores de parâmetro enumerados.

Opções de fulfillment de intents

Você define elementos de intent em um <capability> para declarar como o Google Assistente atende ou responde a comandos de voz do usuário que correspondem a esse recurso. Há várias maneiras de configurar a forma como uma intent inicia um destino de fulfillment no app, dependendo de como a navegação do aplicativo é estruturada.

As seguintes opções de fulfillment estão disponíveis:

• Intents explícitas: inicie um componente de app específico definindo os atributos targetClass e targetPackage para a intent. Esse é o método recomendado de fulfillment de Ações no app.

• Links diretos: inicie destinos de apps usando links diretos do Android definindo uma tag <url-template> no elemento intent. Esse método é útil caso a navegação do seu app já dependa de links diretos.

• Dados de intent: você pode fornecer um URI de fulfillment no atributo android:data da intent. Esse campo será substituído por dados de <url-template> se essa tag também for definida na intent.

Correspondência e dados de parâmetros

Por padrão, o Google Assistente envia parâmetros de BII extraídos da consulta do usuário para seu app como dados extra da intent do Android definidos no elemento capability.

Outra opção seria declarar uma tag <url-template> no capability com marcadores de posição para parâmetros dinâmicos. Esse modelo é associado a uma das suas atividades do Android usando um URL de links do app, um esquema personalizado ou um URL baseado em intent.

Como usar extras de intent

O exemplo a seguir demonstra uma intent explícita definida para um fulfillment de capability:

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

Considerando o exemplo acima, para uma consulta de usuário como "Ok Google, peça um café com leite do ExampleApp", o app recebe uma intent que invoca o componente: targetPackage, targetClass. Esse componente recebe um extra com key = "exercise", value = "Running".

Usar um modelo de URL para links diretos do Android

Caso o app já consiga processar URLs vinculados a ele, com parâmetros dinâmicos, você pode definir um <url-template> na intent para gerar links diretos do Android para fulfillment. O exemplo a seguir define um <url-template>:

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://start{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

Considerando o exemplo acima, para uma consulta de usuário como "Ok Google, peça um café com leite do AppDeExemplo", o app recebe o URL gerado: "myapp://start?exercise=Corrida".

Para associar o parâmetro de BII a uma posição no seu URL, use o atributo android:name da tag <parameter>. Esse atributo corresponde ao valor android:key no modelo de URL que você quer substituir pelas informações do usuário. O valor de android:key precisa estar presente no <url-template> e ser escrito entre chaves ({}).

Corresponder valores de parâmetro enumerados

Alguns parâmetros de BII fornecem valores enumerados para sua intent de fulfillment, como os valores de texto com suporte da BII RECORD_FOOD_OBSERVATION. Para esses parâmetros, o Google Assistente faz a correspondência da consulta do usuário ("Breakfast", que significa "Café da manhã" em inglês) com uma entidade cujo valor sameAs corresponde ao URL do esquema de enumeração (https://schema.googleapis.com/MealTypeBreakfast). Para associar valores de enumeração para uma entity com suporte, você declara uma associação de sameAs no seu shortcut. O exemplo a seguir demonstra uma associação de sameAs para um atalho de entidade inline:

<shortcut android:shortcutId="meal_breakfast" >
    <capability-binding android:key="actions.intent.RECORD_FOOD_OBSERVATION">
        <parameter-binding android:key="foodObservation.forMeal" />
    </capability-binding>
    <extra
        android:key="sameAs"
        android:value="http://schema.googleapis.com/MealTypeBreakfast" />
</shortcut>

<capability android:name="actions.intent.RECORD_FOOD_OBSERVATION">
  <intent targetPackage="com.example.app" targetClass="com.example.app.Class">
    <parameter android:name="foodObservation.forMeal" android:key="for_meal" />
  </intent>
</capability>

No exemplo acima, se o recurso RECORD_FOOD_OBSERVATION acionar uma correspondência para o tipo de refeição "breakfast" (café da manhã), o extra a seguir será enviado com o fulfillment intent:

• key = "for_meal"
• value = "meal_breakfast"

Recursos

Os seguintes recursos de Ações no app estão disponíveis no shortcuts.xml.

Inventário inline para Ações no app

No caso de alguns parâmetros de BII, atalhos podem ser usados ao guiar a extração de entidades para um conjunto de entidades com suporte especificadas no shortcuts.xml, conhecido como inventário inline. Para mais detalhes, consulte a página Inventário inline.

Intents personalizadas

As intents personalizadas podem ser declaradas no shortcuts.xml para ativar recursos de voz no seu app que não correspondem às BIIs disponíveis. Embora sejam semelhantes a uma definição de BII em termos de funcionalidade, as intents personalizadas exigem dois atributos adicionais no shortcuts.xml:

• app:queryPatterns: recurso de matriz que declara os diferentes padrões de consulta para uma intent personalizada.

• android:mimeType: tipo de parâmetro de uma intent personalizada. Esse campo não é obrigatório para BIIs, já que nelas o tipo de parâmetro é conhecido. Para parâmetros de intent personalizada, um tipo semântico com suporte precisa ser declarado.

Para mais detalhes, consulte a página Intents personalizadas.