Inventário inline

Ao implementar Ações no app Android, pode ser necessário processar solicitações que são variações de um tema. Por exemplo, digamos que seu app fitness implemente a intent integrada (BII, na sigla em inglês) START_EXERCISE para permitir que os usuários iniciem uma ampla variedade de treinos pedindo ao Google Assistente algo como: "Ok Google, comece uma corrida no app de exemplo".

Para atender a essa intent, é necessário que sua lógica de correspondência de solicitação processe cada tipo de treino, incluindo variações como "correr", "corrida" ou "corrida". Essa lógica rapidamente se torna complicada conforme a variedade de treinos com suporte aumenta.

Para BIIs com suporte, como START_EXERCISE, é possível evitar essa lógica de correspondência complexa usando um inventário inline. Um inventário inline é um conjunto de atalhos estáticos do Android definidos em shortcuts.xml que representam recursos e conteúdo no seu app.

Cada atalho contém um identificador de item e uma lista de sinônimos que representam variações na forma como os usuários podem se referir ao item. Durante a invocação, a BII compara o parâmetro de BII fornecido pelo usuário com a lista de sinônimos. Quando uma correspondência é encontrada, o parâmetro de BII é atualizado para o identificador de item do atalho correspondente.

Um inventário inline permite que o Google Assistente simplifique os valores de parâmetro de BII fornecidos ao seu aplicativo durante as invocações de Ações no app.

Os inventários inline funcionam como tabelas de pesquisa para parâmetros de BII, expressando várias maneiras como os usuários se referem a recursos ou conteúdo no app usando identificadores de itens definidos por você. Eles simplificam a lógica de correspondência de solicitações do app, permitindo que os fulfillments prevejam identificadores de itens dos parâmetros de BII.

Diagrama de fluxo de usuários do inventários inline
Figura 1. Um diagrama de fluxo de um recurso START_EXERCISE que usa um inventário inline para interpretar nomes de treino fornecidos pelo usuário para tipos de exercícios com suporte no app.

Limitações e alternativas

Os atalhos de inventário inline têm as seguintes limitações:

  • Limite de atalhos:até mil atalhos de inventário inline podem ser definidos por app.
  • Limite de sinônimos:cada atalho de inventário inline pode conter no máximo 20 valores de sinônimos.
  • Definição estática:os atalhos de inventário inline são declarados estaticamente em shortcuts.xml e só podem ser atualizados para os usuários publicando uma nova versão do app.

Devido ao requisito de configuração estática, um inventário inline é mais adequado para estender informações de apps não personalizadas que mudam com pouca frequência ao Google Assistente, como itens de menu, trajetos de ônibus ou tamanhos de bebidas. Para outros tipos de conteúdo, considere estas alternativas:

  • Inventário da Web:permite que o Google Assistente consulte o conteúdo público da Web ao fazer a correspondência de consultas do usuário com identificadores de conteúdo do app compatíveis. As consultas de inventário da Web ocorrem em tempo real durante uma invocação, permitindo que você estenda catálogos de produtos, postagens de mídias sociais e outros conteúdos atualizados com frequência para o Google Assistente.

  • Atalhos dinâmicos:estendem um inventário de conteúdo personalizado do app ao Google Assistente. Os atalhos dinâmicos permitem que os usuários repitam rapidamente ações comuns, como pedir de novo a bebida favorita em um app de pedidos de comida ou extrair uma lista de compras em um app de anotações.

Criar um inventário inline

Um inventário inline simplifica o desenvolvimento, oferecendo ao Google Assistente uma maneira prática de traduzir as diferentes maneiras como os usuários solicitam o conteúdo e os recursos do app para os identificadores previsíveis esperados pelo aplicativo. Por exemplo, suponha que seu app ofereça diferentes treinos que os usuários possam começar a usar por voz e que eles esperem que os usuários façam as seguintes solicitações para o mesmo tipo de exercício:

  • Ok Google, iniciar uma corrida no app de exemplo.
  • Ok Google, começar uma corrida no app de exemplo.

No atalho do inventário inline, defina o shortcutId como "CARDIO_RUN", o identificador de exercício esperado pelo app. Em seguida, especifique "corrida" e "jog" como sinônimos associados ao shortcutId. Depois, quando um usuário acionar a Ação no app com as consultas anteriores, o Google Assistente vai usar o identificador "CARDIO_RUN" para o parâmetro de BII ao gerar uma intent de fulfillment.

O snippet abaixo de um exemplo de arquivo app/res/shortcuts.xml implementa esse caso:

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

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
    </capability-binding>
</shortcut>

Na amostra anterior, o inventário inline shortcut declara uma tag <parameter-binding> em um elemento <capability-binding>, que o vincula ao parâmetro de BII exercise.name definido no elemento <capability>.

O recurso de matriz de strings @array/run_names especifica uma lista de sinônimos em res/values/arrays.xml que o Google Assistente reconhece e mapeia para o ID do item "CARDIO_RUN":

<!-- Synonym values for "CARDIO_RUN" inline inventory -->
<resources>
  <string-array name="run_names">
    <item>Run</item>
    <item>Jog</item>
    <item>Sprint</item>
  </string-array>
</resources>

Quando um <url-template> é fornecido para o capability, o shortcutId de um valor correspondente é inserido no URL gerado no marcador correspondente do parâmetro. O código abaixo de um exemplo de arquivo app/res/shortcuts.xml implementa esse caso:

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

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
  </capability-binding>
</shortcut>

No exemplo anterior, o Google Assistente gera o link direto do fulfillment myapp://workout?exercise=CARDIO_RUN.

Fulfillment usando intents de atalhos

Por padrão, um atalho fornece o shortcutId do valor de um inventário inline correspondente à intent do capability a que o atalho é vinculado, conforme declarado na tag <capability-binding> do atalho. Como outra opção, é possível especificar que uma intent definida no próprio atalho seja usada para fulfillment adicionando uma tag <shortcut-fulfillment> ao capability.

O código de um exemplo de arquivo app/res/shortcuts.xml abaixo implementa o fulfillment de atalho:

<capability android:name="actions.intent.START_EXERCISE">
  <shortcut-fulfillment>
    <parameter android:name="exercise.name"/>
  </shortcut-fulfillment>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
  </capability-binding>
  <intent android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</shortcut>

No exemplo anterior, se a consulta do usuário corresponder a um valor de inventário inline para o parâmetro exercise.name, a tag <shortcut-fulfillment> vai especificar que o intent do atalho vinculado é usado para fulfillment.

Inventário inline para BIIs de recurso de apps abertos

Embora o inventário inline seja, geralmente, um recurso opcional para as BIIs aceitas, ele é necessário para algumas BIIs, como OPEN_APP_FEATURE. Essa BII usada com frequência permite que os usuários tenham links diretos para recursos específicos do app usando o Google Assistente. A BII do recurso de app aberto exige um inventário inline de nomes de recursos do app para verificar se o recurso solicitado pelo usuário existe antes de criar um link direto para o seu app.

O código abaixo de um exemplo de arquivo app/res/shortcuts.xml implementa essa BII com um único atalho que representa o recurso de status do pedido do app:

<capability android:name="actions.intent.OPEN_APP_FEATURE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MyClass">
    <parameter
       android:name="feature"
       android:key="featureParam" />
  </intent>
  <!-- Required fallback fulfillment to handle when parameters are missing from user query. -->
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MyClass">
    <parameter
       android:name="HOME_SCREEN"
       android:key="featureParam" />
  </intent>
</capability>

<!-- Inline inventory for OPEN_APP_FEATURE. -->

<shortcut android:shortcutId="ORDER_STATUS">
  <capability-binding android:key="actions.intent.OPEN_APP_FEATURE">
    <parameter-binding
      android:key="feature"
      android:value="@array/order_status_names" />
    </capability-binding>
</shortcut>

Os recursos da matriz de strings em res/values/arrays.xml, @array/order_status_names, especificam uma lista de sinônimos desse recurso:

<resources>
  <string-array name="order_status_names">
    <item>Order status</item>
    <item>Orders</item>
    <item>Order history</item>
  </string-array>
</resources>

Com o recurso anterior em vigor, o Google Assistente pode fazer o fulfillment de várias frases para o mesmo recurso:

  • "Ok Google, mostre o status do meu pedido no app de exemplo".
  • "Ok Google, mostre meus pedidos no app de exemplo".
  • "Ok Google, mostre meu histórico de pedidos no app de exemplo".

Testar inventários inline

Para testar o inventário, inspecione os valores de parâmetros das BIIs que o Google Assistente fornece ao aplicativo para fazer o fulfillment dos recursos relevantes das Ações no app. Um inventário inline funciona substituindo o valor fornecido pelo usuário de um parâmetro de BII vinculado ao inventário pelo shortcutId de um atalho correspondente do inventário inline.

Por exemplo, um recurso de BII START_EXERCISE pode usar um inventário inline para converter o parâmetro de BII fornecido pelo usuário "executar" para o ID de exercício correspondente, "CARDIO_RUN".

O plug-in do Google Assistente permite visualizar Ações no app de inventário inline no Google Assistente em um dispositivo de teste. Teste seu inventário usando o plug-in, seguindo estas etapas:

  1. Configure os parâmetros vinculados ao inventário do seu recurso de BIIs com valores de sinônimos associados ao inventário inline.
  2. Acione a BII do plug-in no dispositivo de teste fazendo a invocação dela.
  3. Inspecione os valores de parâmetro resultantes que o Google Assistente fornece ao aplicativo durante o fulfillment de Ações no app.