Web inventory

With App Actions, users can jump directly into your app's content by saying things like, “Hey Google, show me the menu for Three Dot Cafe on ExampleApp.” This functionality is called deep linking which can make it easier for your users to get things done with your app.

To fulfill this type of request, Google Assistant generates a deep link to matching content in your app. If you actively maintain your web site with content or product information, and your in-app deep links are organized around this public web content, you can configure Assistant to fetch URLs for action fulfillment from your website, using a web inventory.

A web inventory is the website location of item URLs supported by your app. When a user invokes your App Action, Assistant matches the user query, like “Three Dot Cafe,” to corresponding URLs in the Google search index of the website you specify in the shortcuts.xml for your Android app.

Benefits

Web inventory offers advantages for apps with large, regularly updating item lists that users view or order in the app:

Web inventory data resides on your website, unlike inline inventory data, which stores item lists in your app. Letting Assistant access web data avoids the staleness risk of inline inventory data, which can only be updated by publishing a new version of the app.
Inline inventories are limited to 1,000 items. By contrast, a web inventory has no item limit, and can grow with your needs.
A web inventory can simplify app logic by allowing your fulfillment to only handle predictable content URLs retrieved from your website. By contrast, if an inventory is not configured, Assistant generates deep links for fulfillment by mapping intent parameters to variables in a URL template. Your fulfillment will then need to analyze this dynamically generated URL to determine if a user requested a supported entity in your app.

How it works

During an App Action, Assistant deep links into app content via the built-in intents (BII) you define in shortcuts.xml. Assistant uses natural language processing to identify the relevant items in a user’s request, and extracts them into BII parameters. Assistant then generates a deep link using the parameters, based on your fulfillment configuration in shortcuts.xml.

There are three methods available to generate deep links for fulfillment:

Parameter mapping: Maps intent parameters to placeholders in a fulfillment URL template.
Inline inventory: Matches intent parameters to a list of supported entities defined in the app.
Web inventory: Matches intent parameters to content found in a website’s Google search index.

A web inventory is a developer-defined website URL pattern, like https://www.exampleapp.com/restaurants/.*, representing an entity-set of entities supported by an app.

If a BII parameter is configured for a web inventory, Assistant will query the website to perform an entity match to the user query. Assistant then passes URL results matching the configured URL pattern, like https://www.exampleapp.com/restaurants/three-dot-cafe, to your fulfillment.

**Figure 1.** An example Assistant query using web inventory to retrieve a restaurant entity item.

Supported built-in intents

Web inventory is supported, for certain intent parameters, by the following BIIs:

Add web inventory

Once you identify a supported BII, you enable it for web inventory by updating shortcuts.xml with details about your website. The shortcuts.xml file is a resource in your Android project where you define the BIIs that map to your app's functionality, and how each BII should generate deep links for your app to fulfill. To learn more about shortcuts.xml, see Create shortcuts.xml.

To use web inventory for a supported BII, follow these steps:

In the shortcuts.xml file for your app, add a <capability> tag with an android:name attribute set to the name of a BII you are handling with web inventory, for example: actions.intent.ORDER_MENU_ITEM.
In the <capability> tag, add an <intent> tag with an android:action attribute set to the name of the view to be activated by this intent.
In the same <intent> tag, add a <parameter> tag and set its android:name attribute to the BII parameter that most closely corresponds to the entity described by your web pages. For example, when providing web inventory for ORDER_MENU_ITEM, you should link menu pages to menuItem.name.
In the new <parameter> tag, add a <data> tag and set its android:pathPattern attribute to the URL pattern of the path you want to use for web inventory.

When you configure shortcuts.xml using these steps, Assistant is able to retrieve web content from the Google search index of the URL pattern you provided in the android:pathPattern attribute. Assistant then supplies a URL value to your fulfillment using the results that match the URL path pattern you defined. Your app's then directs the user to a specific place in your app based on the URL data provided by Assistant.

For example, your website contains product listings that use a URL path beginning with https://www.examplecafe.com/items/. You use the pathPattern value https://www.examplecafe.com/items/.*, and Assistant uses this URL pattern in a web search to find a fulfillment URL, like https://www.examplecafe.com/items/item123.

If Assistant finds a matching web inventory URL, it provides the URL in the <data> field of the fulfillment intent, as if it was a deep link. Use the getData() method of the intent to get the URL as a Uri object. The app activity that receives the intent is responsible for interpreting the URL and activating the appropriate app user interface.

Example shortcuts.xml

The following sample defines an ORDER_MENU_ITEM BII that provides a web inventory to return URL results for requests containing the menuItem.name BII parameter:

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

In the above sample, a pathPattern is specified for menuItem.name, instructing Assistant to only return URLs that matches the URL pattern: https://www.examplecafe.com/items/.*

More shortcuts.xml examples are available in the reference documentation of BII that support web inventory.

Handle fallback for missing results

In situations where web inventory results are not returned to your fulfillment, your app should implement fallback logic to fulfill the action with the best user experience possible. Situations causing missing results include:

Missing intent parameter: The user omitted an expected parameter in their query, or Assistant was not able to understand the parameter in the user request.
Missing URL result: Assistant was unable to find an entity on your website matching the user query.

You can handle missing parameter values by defining multiple intent elements for a capability. If Assistant cannot satisfy the first intent, it falls back to the next intent, and so on.

Fallback intents should not require parameters. Instead, they should fulfill the capability with a more generic deep link, such as displaying search results for the user query.

In the following sample shortcuts.xml, an ORDER_MENU_ITEM BII defines two fulfillments: the first expects a URL from the menuItem.name parameter. The second requires no parameters, routing the user to a page showing all menu items.

shortcuts.xml with fallback intent

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

In situations where a web inventory URL is not returned, the content of the user query may still be used in fallback intents, for example, to display search results.

In the following sample shortcuts.xml, two intent elements are defined:

The first requires a web inventory deep link from the menuItem.name parameter.
If a deep link is not returned, the second intent displays search results, using the user query from menuItem.name, if present.

shortcuts.xml with search fallback

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

Add in-app search with web inventory

You can enable users to search for web content on your app by combining web inventory with an implementation of the actions.intent.GET_THING BII.

This BII searches for content or entities using the default in-app search feature in an app, enabling queries like: “Hey Google, show me waterfall hikes on SampleApp.” By configuring web inventory for the thing.name capability parameter passed by the GET_THING BII, matching entity results from your website are passed for fulfillment.

For web inventory shortcuts.xml samples, see the GET_THING BII reference.

Testing web inventory

When you define a web inventory for a BII fulfillment, Assistant generates a deep link using web results matching the urlTemplate pattern you defined for the specified BII parameter. If a web inventory result can't be found, Assistant generates a URL matching the urlTemplate pattern of your fallback intent. You can test your web inventory implementation by verifying that the links Assistant provides URLs that match your web inventory urlTemplate patterns.

In the following sample ORDER_MENU_ITEM BII, Assistant generates web inventory fulfillment links matching the urlFilter pattern specified in the menuItem.name parameter, for example: https://www.examplecafe.com/items/nuggets. The second intent takes the value of menuItem.name and performs a search if the first intent fails to match the URL pattern.

shortcuts.xml with search intent

<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 the App Actions Test Tool to test web inventory on a physical or virtual device.

To use the test tool, follow these steps:

Connect your test device with your app running.
In Android Studio, go to Tools > App Actions > App Actions Test Tool.
Click Create preview.
In Android Studio, run your app on your test device.
Use the Assistant app on your test device to test your App Action. For example, you can say something like "Hey Google, order nuggets on ExampleCafe".
Observe the behavior of your app, or use the Android Studio debugger, to verify the desired action result.