Intents personalizadas

Cada app é diferente, e nem toda funcionalidade corresponde a uma intent integrada (BII, na sigla em inglês) de Ações no app. Nos casos em que não há uma BII para a funcionalidade do app, é possível usar uma intent personalizada para implementar 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 do 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 Tipos com suporte.
• Intents personalizadas precisam conter exemplos de padrões de consulta utilizáveis. Consulte Padrões de consulta.
• Cada consulta aceita, no máximo, dois parâmetros de texto. Esse limite não se aplica a outros tipos de dados.
• As intents personalizadas oferecem suporte apenas à localidade en-US. Além disso, as configurações de idioma do dispositivo e do Google Assistente precisam ser iguais.

Tipos com suporte

As intents personalizadas têm suporte aos seguintes tipos de schema.org (link em inglês) para extração de parâmetros:

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

Definir Ações no app com intents personalizadas

Assim como em outras Ações no app que usam BIIs, 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>, inclua os namespaces dos atributos que você quer acessar, como mostrado no exemplo a seguir:

<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>

Os nomes de intents personalizadas não podem começar com actions.intent, porque esse namespace é reservado às BIIs. Em vez disso, ao nomear as intents personalizadas, use o prefixo custom.actions.intent para diferenciá-las das BIIs e das intents do Android, que funcionam de forma diferente.

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>
...

Defina atalhos para intents personalizadas em shortcuts.xml usando o mesmo formato de atalhos para BIIs.

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 usa 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.

Observação: no momento, o inventário da Web não tem suporte para parâmetros de intent personalizada.

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 BIIs, em que as consultas já 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.

Observação: cada intent personalizada pode ser associada a até cem padrões de consulta.

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

• "Ok Google, abra o app de jogo de exemplo e comece a fazer um bolo."
• "Ok Google, abra o app de jogo de exemplo e comece a fazer uma torta de maçã."
• "Ok Google, inicie o app de jogo de exemplo e faça cinco bolos."
• "Ok Google, use o app de jogo de exemplo 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.

Observação: o Google Assistente faz correspondências exatas com base nos padrões de consulta fornecidos para intents personalizadas. A correspondência do padrão de consulta não inclui frases de invocação e usa a configuração de idioma do Google Assistente.

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 do marcador para um parâmetro, como <parameter name="date1" ... (em actions.xml) ou <parameter android:name="date1" ... (em shortcuts.xml), use $date1.

O código a seguir descreve padrões que correspondem às consultas do usuário mostradas anteriormente 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 permitem o uso de condicionais. Por exemplo, set (an)? appointment $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.