Inventário inline

Ao implementar Ações no app Android, talvez você se depare com ter que lidar com solicitações que são variações de um tema. Por exemplo, digamos que seu fitness implementa a intent integrada (BII) do START_EXERCISE para permitir os usuários iniciam vários treinos perguntando ao Google Assistente coisas como: "Ok Google, iniciar uma corrida no app de exemplo."

Para atender a essa intent, sua lógica de correspondência de solicitação precisa lidar com cada tipo de treino, incluindo variações como "correr", “sprint”, ou "raça". Essa lógica rapidamente se torna complicada conforme a variedade de treinos com suporte aumenta.

Para BIIs com suporte, como START_EXERCISE, você pode evitar essa correspondência complexa usando um inventário inline. Um inventário inline é um conjunto de imagens estáticas Atalhos do Android definidos em shortcuts.xml para representar 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.

Com um inventário inline, o Google Assistente pode simplificar o parâmetro de BII fornecidos ao seu aplicativo durante as invocações de Ações no app.

Inventários inline funcionam como tabelas de consulta para parâmetros de BII, Expressar várias maneiras pelas quais os usuários se referem aos recursos ou ao conteúdo do app usando os identificadores de item definidos por você. Elas simplificam a correspondência de solicitações do app lógica, permitindo que os fulfillments prevejam identificadores de itens da BII parâmetros.

Figura 1. Um diagrama de fluxo de um recurso START_EXERCISE que usa uma inventário inline para interpretar nomes de treinos fornecidos pelo usuário para tipos de exercício no aplicativo.

Observação :o inventário inline é compatível com parâmetros específicos de determinadas BIIs Para mais detalhes, consulte a seção "Inventário" disponibilidade por campo" na referência da BII.

Limitações e alternativas

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

• Limite de atalhos:é possível ter no máximo mil atalhos de inventário inline. definidos por app.
• Limite de sinônimos:cada atalho de inventário inline pode conter no máximo 20 de sinônimos.
• Definição estática:os atalhos de inventário inline são declarados estaticamente. no shortcuts.xml e só podem ser atualizados para os usuários publicando um novo mais recente do seu app.

Devido à exigência de configuração estática, é melhor ter um inventário inline adequado para estender informações de aplicativos não personalizadas com pouca frequência para Google Assistente, como itens do cardápio, rotas 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 conteúdo público da Web quando: correspondência entre consultas do usuário e identificadores de conteúdo do app compatíveis. Inventário da Web as consultas ocorrem em tempo real durante uma invocação, o que permite estender catálogos de produtos, postagens em redes 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. para o Google Assistente. Os atalhos dinâmicos permitem que os usuários reproduzam rapidamente ações, como pedir a bebida novamente em um aplicativo de pedidos de comida ou puxando uma lista de compras em um app de anotações.

Criar um inventário inline

O inventário inline simplifica o desenvolvimento porque oferece ao Google Assistente uma maneira prática de traduzir as diferentes maneiras como os usuários solicitam o conteúdo e os recursos do seu app nos identificadores previsíveis esperados pelo aplicativo. Para exemplo, suponha que seu aplicativo oferece diferentes treinos que os usuários podem começar a usar a voz deles, e seu aplicativo espera 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, comece uma corrida no app de exemplo.

No atalho do inventário inline, você define shortcutId como "CARDIO_RUN". o identificador de exercício esperado pelo app. Depois, você especifica "run" e "correr" como sinônimos associados ao shortcutId. Então, quando um usuário acionar sua Ação no app com as consultas anteriores, o Google Assistente usa o identificador "CARDIO_RUN" para o parâmetro de BII ao gerar uma intent de fulfillment.

O snippet a seguir de um exemplo de arquivo app/res/shortcuts.xml implementa neste 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 reconhecer e mapear 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 do um valor correspondente é inserido no URL gerado no momento marcador de posição do parâmetro. O código de um exemplo a seguir O arquivo app/res/shortcuts.xml implementa este 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 de fulfillment myapp://workout?exercise=CARDIO_RUN:

Observação: o inventário inline aceita no máximo um parameter por elemento intent de fulfillment de um capability.

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 a seguir de um exemplo de arquivo app/res/shortcuts.xml implementa 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> especifica que o intent do atalho vinculado é usado para fulfillment.

Observação: cada inventário inline <shortcut> destinado ao fulfillment de atalhos precisa conter um fulfillment <intent>. Para evitar erros de atendimento, Não use atalhos que não contenham elementos de intent para atalho. atendimento do pedido.

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. Isso as BII usadas com frequência permitem que os usuários criem 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 existe um recurso solicitado pelo usuário antes de criar um link direto para seu app.

O código a seguir de um exemplo de arquivo app/res/shortcuts.xml implementa isso 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, especifica uma lista de sinônimos para este 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. Uma linha de comando inventário funciona substituindo o valor fornecido pelo usuário de uma BII vinculada ao inventário com o shortcutId de um atalho de inventário inline correspondente.

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

Com o plug-in do Google Assistente, você pode visualizar seu app de inventário inline. Ações 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âmetros resultantes que o Google Assistente fornece ao seu aplicativo durante o fulfillment de Ações no app.