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