Com as Ações no app, os usuários podem acessar diretamente o conteúdo do seu aplicativo dizendo: "Ok Google, mostre o cardápio do Café X no ExampleApp". Esse recurso é chamado de link direto e pode facilitar a vida dos usuários do seu app.
Para atender a esse tipo de pedido, o Google Assistente gera um link direto para um conteúdo correspondente no app. Caso você mantenha seu site com informações de produtos ou conteúdos, e os links diretos no app estejam organizados de acordo com esse conteúdo público da Web, você pode configurar o Google Assistente para buscar no seu site URLs de fulfillment da ação, usando um inventário da Web.
Um inventário da Web é o local do site com URLs de itens que
seu app pode usar. Quando um usuário invoca a ação no app, o Google Assistente usa a consulta
do usuário (como "Café X") para encontrar URLs correspondentes no índice da Pesquisa Google do site especificado
no shortcuts.xml
do seu app Android.
Benefícios
O inventário da Web oferece vantagens para apps com listas de itens grandes e atualizadas com frequência que os usuários podem encontrar ou pedir no app:
Os dados do inventário da Web ficam no seu site, diferente dos dados do inventário inline, que armazenam listas de itens no app. Permitir que o Google Assistente acesse os dados da Web evita o risco dos dados de inventário inline ficarem desatualizados, já que eles só podem ser atualizados com a publicação de uma nova versão do app.
Os inventários inline só podem ter até mil itens. Por outro lado, um inventário da Web não tem limite de itens e pode crescer de acordo com as suas necessidades.
Um inventário da Web pode simplificar a lógica do app ao permitir que o fulfillment processe apenas URLs de conteúdo previsíveis extraídos do site. Por outro lado, se um inventário não estiver configurado, o Google Assistente vai gerar links diretos para o fulfillment, associando os parâmetros de intent a variáveis em um modelo de URL. Depois, o fulfillment precisará analisar o URL gerado dinamicamente para determinar se o usuário solicitou uma entidade com suporte no app.
Como funciona
Durante uma ação no app, o Google Assistente cria links diretos para o conteúdo do aplicativo usando as intents
incorporadas (BIIs, na sigla em inglês) que você define no shortcuts.xml
. Ele utiliza o processamento de linguagem natural
para identificar os itens relevantes no pedido de um usuário e os extrai
em parâmetros de BII. Em seguida, o Google Assistente gera um link direto usando os parâmetros,
com base na sua configuração de fulfillment no arquivo shortcuts.xml.
Há três formas de gerar links diretos para fulfillment:
- Mapeamento de parâmetros: associa os parâmetros de intent a marcadores de posição em um modelo de URL de fulfillment.
- Inventário inline: faz a correspondência dos parâmetros de intent com uma lista de
entities
disponíveis definida no app. - Inventário da Web: faz a correspondência entre os parâmetros de intent e o conteúdo encontrado no índice da Pesquisa Google de um site.
Um inventário da Web é um padrão de URL do site definido pelo desenvolvedor,
como https://www.exampleapp.com/restaurants/.*
, representando um conjunto de
entidades que podem ser usadas por um app.
Se um parâmetro de BII for configurado para um inventário da Web, o Google Assistente vai
consultar o site e realizar uma correspondência de entidade com a consulta do usuário. Em seguida,
o Google Assistente vai transmitir resultados de URL que correspondem ao padrão de URL configurado, como
https://www.exampleapp.com/restaurants/three-dot-cafe
, para o fulfillment.
![](https://developer.android.com/static/guide/app-actions/images/web-inventory-flow.png?authuser=6&hl=pt)
Intents integradas com suporte
O inventário da Web pode ser usado com determinados parâmetros de intent das BIIs abaixo:
- [
actions.intent.CREATE_REVIEW
] - [
actions.intent.GET_NEWS_ARTICLE
] - [
actions.intent.GET_REVIEW
] - [
actions.intent.GET_THING
] - [
actions.intent.ORDER_MENU_ITEM
] - [
actions.intent.GET_EXERCISE_PLAN
] - [
actions.intent.GET_DIGITAL_DOCUMENT
] - [
actions.intent.GET_ITEM_LIST
] - [
actions.intent.GET_OFFER
] - [
actions.intent.CREATE_OFFER
] - [
actions.intent.GET_PRODUCT
] - [
actions.intent.UPDATE_CART
] - [
actions.intent.CREATE_SOCIAL_MEDIA_CONNECTION
] - [
actions.intent.GET_IMAGE_OBJECT
] - [
actions.intent.GET_SOCIAL_MEDIA_POSTING
] - [
actions.intent.GET_SOCIAL_MEDIA_PROFILE
] - [
actions.intent.CREATE_TAXI_RESERVATION
] - [
actions.intent.CREATE_FLIGHT_RESERVATION
] - [
actions.intent.CREATE_LODGING_RESERVATION
] - [
actions.intent.GET_LOCAL_BUSINESS
] - [
actions.intent.GET_RESERVATION
] - [
actions.intent.UPDATE_RESERVATION
]
Adicionar um inventário da Web
Depois de identificar uma BII que pode ser usada, ative-a para o inventário da Web atualizando
o shortcuts.xml
com detalhes sobre seu site. O arquivo shortcuts.xml
é um
recurso do projeto Android em que você define as BIIs que estão associadas à
funcionalidade do app e a forma como cada BII precisa gerar links diretos para o
app atender. Se quiser saber mais sobre o shortcuts.xml
, consulte Criar um arquivo shortcuts.xml.
Para usar o inventário da Web para uma BII com suporte, siga estas etapas:
No arquivo
shortcuts.xml
do seu app, adicione uma tag<capability>
com um atributoandroid:name
definido como o nome de uma BII que você está processando com o inventário da Web. Por exemplo:actions.intent.ORDER_MENU_ITEM
.Na tag
<capability>
, adicione uma tag<intent>
com um atributoandroid:action
definido como o nome da visualização que será ativada por essa intent.Na mesma tag
<intent>
, adicione uma tag<parameter>
e defina o atributoandroid:name
dela como o parâmetro de BII que melhor corresponde à entidade descrita por suas páginas da Web. Por exemplo, ao fornecer um inventário da Web paraORDER_MENU_ITEM
, você precisa vincular páginas de um cardápio amenuItem.name
.Na nova tag
<parameter>
, adicione uma tag<data>
e defina o atributoandroid:pathPattern
como o padrão do URL do caminho que você quer usar para o inventário da Web.
Quando você configura o shortcuts.xml
usando essas etapas, o Google Assistente consegue
recuperar o conteúdo da Web pelo índice da Pesquisa Google do padrão de URL que você
forneceu no atributo android:pathPattern
. Em seguida, o Google Assistente fornece um valor de URL
para o fulfillment usando os resultados que correspondem ao padrão de caminho do URL
definido. O app direciona o usuário a um local específico com base
nos dados de URL fornecidos pelo Google Assistente.
Por exemplo, seu site contém informações do produto que usam um caminho de URL
que começa com https://www.examplecafe.com/items/
. Se você usar o valor pathPattern
https://www.examplecafe.com/items/.*
, o Google Assistente vai usar esse padrão
de URL em uma pesquisa na Web para encontrar um URL de fulfillment, como
https://www.examplecafe.com/items/item123
.
Se o Google Assistente encontrar um URL de inventário da Web correspondente, ele vai fornecer esse URL no
campo <data>
da intent de fulfillment, como se fosse um link direto. Use o método
getData()
da intent para receber o URL como um objeto Uri
. A atividade no app que
recebe a intent é responsável por interpretar o URL e ativar
a interface do usuário adequada do app.
Exemplo de shortcuts.xml
O exemplo abaixo define uma BII ORDER_MENU_ITEM
que
fornece um inventário da Web para retornar resultados de URL de pedidos que contenham o
parâmetro de BII menuItem.name
:
<?xml version="1.0" encoding="utf-8"?>
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
<capability android:name="actions.intent.ORDER_MENU_ITEM">
<intent
android:action="android.intent.action.VIEW"
android:targetPackage="com.example.myapp"
android:targetClass="com.example.myapp.OrderMenuItemActivity">
<!-- Define URL match pattern in the pathPattern data field -->
<parameter android:name="menuItem.name">
<data android:pathPattern="https://www.examplecafe.com/items/.*"/>
</parameter>
</intent>
</capability>
</shortcuts>
No exemplo acima, um pathPattern
é especificado para menuItem.name
,
instruindo o Google Assistente a retornar apenas URLs que correspondem ao padrão de URL:
https://www.examplecafe.com/items/.*
Mais exemplos de shortcuts.xml
de BII que oferecem suporte ao inventário da Web estão
disponíveis na documentação de referência.
Processar um substituto para resultados ausentes
Nos casos em que os resultados do inventário da Web não são retornados para o fulfillment, o app precisa implementar uma lógica substituta para realizar a ação com a melhor experiência do usuário possível. Estas são algumas das situações que causam resultados ausentes:
- Parâmetro de intent ausente: o usuário omitiu um parâmetro esperado na consulta, ou o Google Assistente não entendeu o parâmetro no pedido do usuário.
- Resultado do URL ausente: o Google Assistente não encontrou uma entidade no site que corresponde à consulta do usuário.
Gerencie os valores de parâmetros ausentes definindo vários elementos <intent>
para um recurso. Se o Google Assistente não conseguir atender à primeira intent,
ele vai passar para a próxima e assim por diante.
As intents substitutas não precisam de parâmetros. Em vez disso, elas precisam atender ao recurso com um link direto mais genérico, como mostrar resultados da pesquisa para a consulta do usuário.
No exemplo de shortcuts.xml
a seguir, uma BII ORDER_MENU_ITEM
define dois fulfillments: o primeiro espera um URL do parâmetro
menuItem.name
. O segundo não exige parâmetros, levando o usuário a uma página que mostra
todos os itens do cardápio.
<capability android:name="actions.intent.ORDER_MENU_ITEM">
<intent
android:action="android.intent.action.VIEW"
android:targetPackage="com.example.myapp"
android:targetClass="com.example.myapp.OrderMenuItemActivity">
<parameter android:name="menuItem.name">
<data android:pathPattern="https://www.examplecafe.com/items/.*"/>
</parameter>
</intent>
<!-- Fallback intent with no required parameters -->
<intent
android:action="android.intent.action.VIEW"
android:targetPackage="com.example.myapp"
android:targetClass="com.example.myapp.ViewMenuActivity">
<url-template android:value="myapp://app.examplecafe.com/menu/all-items" />
</intent>
</capability>
Em situações em que um URL de inventário da Web não é retornado, o conteúdo da consulta do usuário ainda pode ser usado em intents substitutas, por exemplo, para mostrar resultados da pesquisa.
No exemplo de shortcuts.xml
a seguir, dois elementos de intent são definidos:
- O primeiro exige um link direto do inventário da Web do parâmetro
menuItem.name
. - Se um link direto não for retornado, a segunda intent vai mostrar os resultados
da pesquisa usando a consulta de usuário do
menuItem.name
, caso esteja presente.
<capability android:name="actions.intent.ORDER_MENU_ITEM">
<intent
android:action="android.intent.action.VIEW"
android:targetPackage="com.example.myapp"
android:targetClass="com.example.myapp.OrderMenuItemActivity">
<parameter android:name="menuItem.name">
<data android:pathPattern="https://www.examplecafe.com/items/.*" />
</parameter>
</intent>
<!-- Fallback intent displaying search results, using "menuItem.name" -->
<intent
android:action="android.intent.action.VIEW"
android:targetPackage="com.example.myapp"
android:targetClass="com.example.myapp.SearchMenuActivity">
<parameter-mapping android:name="menuItem.name" android:key="food" />
<url-template android:value="https://www.examplecafe.com/search?q={?food}" />
</intent>
</capability>
Adicionar a pesquisa no app ao inventário da Web
É possível permitir que os usuários pesquisem conteúdo da Web no seu app combinando
o inventário da Web com uma implementação da BII actions.intent.GET\_THING
.
Essa BII pesquisa conteúdo ou entidades usando o recurso de
pesquisa padrão no app, permitindo consultas como: "Ok Google, mostre trilhas com cachoeira
no SampleApp". Ao configurar o inventário da Web para o parâmetro de recurso thing.name
transmitido pela BII GET_THING
, os resultados de entidade correspondentes do seu
site são transmitidos para o fulfillment.
Para exemplos de shortcuts.xml
de inventário da Web, consulte a referência de BII GET\_THING
.
Como testar o inventário da Web
Quando você define um inventário da Web para um fulfillment de BII, o Google Assistente gera um
link direto usando resultados da Web correspondentes ao padrão urlTemplate
definido para
o parâmetro de BII especificado. Se não for possível encontrar um resultado de inventário da Web, o Google Assistente vai gerar um URL correspondente ao padrão urlTemplate
da sua intent substituta. Para
testar sua implementação de inventário da Web, verifique se os links que o Google Assistente
fornece têm URLs que correspondem aos padrões urlTemplate
do seu inventário da Web.
No exemplo de BII ORDER_MENU_ITEM
a seguir, o Google Assistente gera links de fulfillment do
inventário da Web que correspondem ao padrão urlFilter
especificado no
parâmetro menuItem.name
. Por exemplo:
https://www.examplecafe.com/items/nuggets
. A segunda intent vai usar o valor de
menuItem.name
e fazer uma pesquisa se a primeira intent não corresponder ao
padrão do URL.
<capability android:name="actions.intent.ORDER_MENU_ITEM">
<!-- web inventory fulfillment -->
<intent
android:action="android.intent.action.VIEW"
android:targetPackage="com.example.myapp"
android:targetClass="com.example.myapp.OrderMenuItemActivity">
<parameter name="menuItem.name">
<data android:pathPattern="https://www.examplecafe.com/items/.*" />
</parameter>
</intent>
<!-- search intent -->
<intent
android:action="android.intent.action.VIEW"
android:targetPackage="com.example.myapp"
android:targetClass="com.example.myapp.MenuSearchActivity">
<parameter-mapping android:name="menuItem.name" android:key="food" />
<url-template android:value="https://www.examplecafe.com/search?q={?food}" />
</intent>
</capability>
Use a Ferramenta de teste das Ações no app para testar o inventário da Web em um dispositivo físico ou virtual.
Para usar a ferramenta de teste, siga estas etapas:
- Conecte o dispositivo de teste em que o app está sendo executado.
- No Android Studio, acesse Tools > App Actions > App Actions Test Tool.
- Clique em Create preview.
- No Android Studio, execute o app no dispositivo de teste.
- Use o app Google Assistente no seu dispositivo para testar a ação no app. Por exemplo, você pode dizer algo como "Ok Google, pedir nuggets no ExampleCafe".
- Observe o comportamento do app ou use o depurador do Android Studio para verificar o resultado da ação desejada.