Intents personalizadas

Cada app é diferente, e nem toda funcionalidade corresponde a uma intent integrada de Ações no app. Nos casos em que não há uma intent integrada (BII, na sigla em inglês) para a funcionalidade do seu app, você pode usar uma intent personalizada para ampliar o app com Ações no app.

Assim como as BIIs, as intents personalizadas seguem o esquema do shortcuts.xml e atuam como pontos de conexão entre o Google Assistente e os fulfillments definidos. As intents personalizadas também têm parâmetros de intent, que você pode associar a parâmetros no fulfillment correspondente.

Ao contrário das BIIs, as intents personalizadas exigem padrões de consulta para descrever exemplos de consultas que um usuário pode dizer. Essa abordagem é diferente das intents integradas, que modelam maneiras comuns de os usuários expressarem essa intent.

Limitações

Intents personalizadas têm as seguintes limitações:

  • O nome de uma intent personalizada não pode começar com actions.intent.
  • O nome de uma intent personalizada não pode ser igual ao de outra no seu app.
  • Apenas determinados tipos de dados estão disponíveis para extração de parâmetros pelo Google Assistente. Consulte a seção abaixo para ver a lista de tipos com suporte.
  • No máximo dois parâmetros de texto são aceitos por consulta. Esse limite não se aplica a outros tipos de dados.
  • Apenas a localidade en-US tem suporte a intents personalizadas. O dispositivo e o Google Assistente precisam estar configurados para esse idioma.

Tipos com suporte

As intents personalizadas têm suporte aos seguintes tipos de schema.org para extração de parâmetros:

  • https://schema.org/Text
  • https://schema.org/Date
  • https://schema.org/Time
  • https://schema.org/Number

Como definir Ações no app com intents personalizadas

Assim como em outras Ações no app que usam intents integradas, você define uma intent personalizada no elemento <capability> no shortcuts.xml.

Os recursos são definidos no elemento raiz <shortcuts>. Ao definir o elemento <shortcuts>, você precisa incluir os namespaces dos atributos que quer acessar.

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  ...
</shortcuts>

Forneça o nome da intent personalizada no atributo android:name e faça referência a um arquivo de recursos de padrões de consulta no atributo queryPatterns.

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.EXAMPLE_INTENT"
      app:queryPatterns="@array/ExampleQueries">
    <intent ...>
      <url-template
          android:value="http://custom.com{?number_of_items,item_name}" />
      <parameter
          android:name="number_of_items"
          android:key="number_of_items"
          android:mimeType="https://schema.org/Number" />
      <parameter
          android:name="item_name"
          android:key="item_name"
          android:mimeType="https://schema.org/Text" />
    </intent>
  </capability>
  ...
</shortcuts>

Ao nomear suas intents personalizadas, recomendamos usar o prefixo custom.actions.intent para diferenciar essas das intents integradas e do Android, que funcionam de forma diferente. Os nomes de intents personalizadas não podem começar com actions.intent, porque esse namespace é reservado às intents integradas.

Para cada parâmetro, forneça o tipo de schema.org que melhor descreve o significado do parâmetro. Por exemplo, você pode usar https://schema.org/Date para descrever uma data que você espera receber:

...
<intent>
  <url-template android:value="https://example.com/appt{?apptType,date,time}" />
  <parameter
      android:name="date"
      android:key="date"
      android:mimeType="https://schema.org/Date" />
  ...
</intent>
...

A definição de atalho no shortcuts.xml usa nas intents personalizadas o mesmo formato das integradas. O código a seguir descreve uma ação no app que usa os padrões de consulta referenciados para acionar a intent personalizada SCHEDULE_APPOINTMENT e um conjunto definido de valores, DRIVERS_LICENSE e VEHICLE_REGISTRATION, para o parâmetro apptType.

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.SCHEDULE_APPOINTMENT"
      app:queryPatterns="@array/scheduleApptQueries">
    <intent ...>
      <url-template android:value="https://example.com/appt{?apptType,date,time}" />
      <parameter
          android:name="date"
          android:key="date"
          android:mimeType="https://schema.org/Date" />
      <parameter
          android:name="time"
          android:key="time"
          android:mimeType="https://schema.org/Time" />
      <!-- The following parameter has no type because the shortcuts are bound to it -->
      <parameter android:name="apptType" android:key="apptType" />
    </intent>
    ...

A definição de atalho no shortcuts.xml usa nas intents personalizadas o mesmo formato das integradas. O código a seguir descreve uma ação no app que usa os padrões de consulta referenciados para acionar a intent personalizada SCHEDULE_APPOINTMENT e um conjunto definido de valores, DRIVERS_LICENSE e VEHICLE_REGISTRATION, para o parâmetro apptType.

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.SCHEDULE_APPOINTMENT"
      app:queryPatterns="@array/scheduleApptQueries">
    <intent ...>
     <url-template android:value="https://example.com/appt{?apptType,date,time}" />
       <parameter
          android:name="date"
          android:key="date"
          android:mimeType="https://schema.org/Date" />
       <parameter
          android:name="time"
          android:key="time"
          android:mimeType="https://schema.org/Time" />
       <!-- The following parameter has no type because the shortcuts are bound to it -->
       <parameter android:name="apptType" android:key="apptType" />
    </intent>
  </capability>

  <shortcut
      android:shortcutShortLabel="Driver's License"
      android:shortcutId="DRIVERS_LICENSE">
    <capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
      <parameter-binding
          android:key="apptType"
          android:value="@string/driversLicense" />
    </capability-binding>
  </shortcut>

  <shortcut
      android:shortcutsShortLabel="Vehicle Registration"
      android:shortcutId="VEHICLE_REGISTRATION">
    <capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
      <parameter-binding
          android:key="apptType"
          android:value="@string/vehicleRegistration" />
    </capability-binding>
  </shortcut>
</shortcuts>

É possível configurar parâmetros de intent personalizada com o inventário inline, que pode ser usado para orientar a extração da entidade para um conjunto de entidades com suporte, especificado no shortcuts.xml.

Padrões de consulta

Cada intent personalizada que você usa requer um conjunto de consultas esperadas do usuário para essa intent. Essa abordagem é diferente das intents integradas, em que as consultas são baseadas em maneiras comuns de os usuários expressarem as tarefas que estão tentando realizar ou as informações que procuram.

Em um arquivo de recursos do Android (geralmente o /res/values/strings.xml), especifique padrões de consulta como itens em uma matriz de strings. Quando a ação no app for invocada, o Google Assistente vai verificar a consulta do usuário em relação aos seus padrões de consulta como parte da correspondência da intent do usuário para o fulfillment. Cada padrão de consulta fornecido representa uma frase que você considera válida para a intent personalizada correspondente.

Ao fornecer padrões de consulta para intents personalizadas, é esperado que cada padrão siga uma invocação explícita, como "abra o ExampleApp e" ou "inicie o ExampleApp e". Por exemplo, considere as seguintes consultas do usuário:

  • "Ok Google, abra o ExampleGameApp e comece a fazer um bolo."
  • "Ok Google, abra o ExampleGameApp e comece a fazer uma torta de maçã."
  • "Ok Google, inicie o ExampleGameApp e faça cinco bolos."
  • "Ok Google, use o ExampleGameApp para faça um bolo cinco vezes."

Para corresponder às consultas do usuário, forneça padrões que contenham a parte da consulta após a frase de invocação. Para informações que você quer extrair da consulta, como texto ou um número fornecido pelo usuário, atribua valores ao parâmetro de intent correspondente com marcadores de posição no padrão da consulta.

Para se referir a um parâmetro em um padrão de consulta, adicione $ ao nome do parâmetro no seu padrão. Por exemplo, para criar um valor de marcador para um parâmetro, como <parameter name="date1" ... (actions.xml) ou <parameter android:name="date1" ... (shortcuts.xml), você usaria $date1.

O código a seguir descreve padrões que correspondem às consultas do usuário mostradas acima e extrai valores para os nomes de itens e para o número de itens a serem feitos:

<resources>
  <string-array name="ExampleQueries">
    <item>start making a $text1</item>
    <item>start making an $text1</item>
    <item>craft $number1 $text1 items</item>
    <item>produce $text1 $number1 times</item>
  </string-array>
</resources>

Os padrões de consulta têm suporte ao uso de condicionais. Por exemplo, "marcar (um)? horário $date $time". Nesse caso, tanto "marcar horário hoje ao meio-dia" quanto "marcar um horário hoje ao meio-dia" são consultas válidas.