Inventário da Web

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.

**Figura 1**. Um exemplo de consulta do Google Assistente usando inventário da Web para recuperar um item de entidade de restaurante.

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 atributo android: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 atributo android: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 atributo android: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 para ORDER_MENU_ITEM, você precisa vincular páginas de um cardápio a menuItem.name.
Na nova tag <parameter>, adicione uma tag <data> e defina o atributo android: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.