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 actions.xml.

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

An illustration of Assistant using web inventory Figure 1. An example Assistant query leveraging 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 actions.xml with details about your website. actions.xml 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 actions.xml, see Create Actions.xml.

To use web inventory for a supported BII, update actions.xml:

  1. In the <action> tag where you want to use web inventory, add a <fulfillment> tag and set its urlTemplate attribute to {@url}.
  2. In the same <action> tag, add a <parameter> tag and set its 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.
  3. In the new <parameter> tag, add a <entity-set-reference> tag and set its urlFilter attribute to the URL path you want to use for web inventory.

By performing the above steps, Assistant retrieves web content from the Google search index of the URL path you provided in the urlFilter attribute. Assistant then supplies a {@url} value to your fulfillment using the results. Your app's deep link handler can then direct the user to a specific place in your app based on the deep link provided by Assistant.

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

After the Assistant returns the fulfillment URL, your deep link handler is responsible for translating the URL into an appropriate UI in your app.

Example actions.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"?>
<actions>
  <action intentName="actions.intent.ORDER_MENU_ITEM">

    <!-- Define parameters with web inventories using urlFilter -->
    <parameter name="menuItem.name">
      <entity-set-reference urlFilter="https://www.mywebsite.com/link1/.*" />"/>
    </parameter>

    <!-- Use URL from entity match for deep link fulfillment -->
    <!-- Example: url = 'https://www.mywebsite.com/link1/item1' -->
    <fulfillment urlTemplate="{@url}" />

  </action>
</actions>

In the above sample, a urlFilter is specified for menuItem.name, instructing Assistant to only return URLs that conform to the URL pattern: https://www.mywebsite.com/link1/.*

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

In-app search with web inventory

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 intent parameter passed by the GET_THING BII, matching entity results from your website will be passed for fulfillment.

Visit the GET_THING BII reference for web inventory actions.xml samples.

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 fulfillment elements for an action. If Assistant cannot satisfy the first fulfillment, it falls back to the next fulfillment, and so on.

Fallback fulfillments should not require parameters. Instead, they should fulfill the action with a more generic deeplink, such as displaying search results for the user query.

In the following sample actions.xml, an FOOD_ORDERING 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.

Actions.xml

<?xml version="1.0" encoding="utf-8"?>
<actions>
  <action intentName="actions.intent.ORDER_MENU_ITEM">
    <parameter name="menuItem.name">
      <entity-set-reference urlFilter="https://www.examplecafe.com/link1/.*" />"/>
    </parameter>

    <fulfillment urlTemplate="{@url}" />

    <!-- Fallback fulfillment with no required parameters -->
    <fulfillment urlTemplate="myapp://app.examplecafe.com/menu/all-items" />

  </action>
</actions>

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

In the following sample actions.xml, two fulfillment elements are defined:

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

Actions.xml

<?xml version="1.0" encoding="utf-8"?>
<actions>
  <action intentName="actions.intent.ORDER_MENU_ITEM">

    <parameter name="menuItem.name">
      <entity-set-reference urlFilter="https://www.examplecafe.com/link1/.*" />"/>
    </parameter>

    <!-- Primary fulfillment expecting an entity from the "menuItem.name" parameter -->
    <fulfillment urlTemplate="{@url}" />

    <!-- Fallback fulfillment displaying search results, using "menuItem.name" if present -->

    <fulfillment urlTemplate="exampleCafeApp://browse{?food}">
         <parameter-mapping intentParameter="menuItem.name" urlParameter="food" />
    </fulfillment>

  </action>
</actions>

Testing web inventory

When you define a web inventory for a BII fulfillment, Assistant generates a deep link using web results matching the urlFilter pattern you defined for the specified BII parameter. If a web inventory result can't be found, Assistant generates a deep link matching the urlTemplate pattern of your fallback fulfillment method. You can test your web inventory implementation, then, by verifying that the links Assistant passes to your deep link handler match your web inventory urlFilter pattern.

In the following sample ORDER_MENU_ITEM BII, Assistant generates web inventory fulfillment links matching the urlFilter pattern specified in the menuItem.name parameter, which will look something like: https://www.example.com/menu/nuggets. Fallback deep links match the fallback fulfillment urlTemplate, looking something like: https://www.example.com/menu/search-results?q={query}.

Actions.xml

<?xml version="1.0" encoding="utf-8"?>
<actions>
    <action intentName="actions.intent.ORDER_MENU_ITEM">
        <!-- web inventory fulfillment -->
        <parameter name="menuItem.name">
            <entity-set-reference urlFilter="https://www.example.com/menu/.*" />
        </parameter>
        <fulfillment urlTemplate="{@url}">
        </fulfillment>
        <!-- fallback fulfillment -->
        <fulfillment urlTemplate="https://www.example.com/menu/search-results?q={query}">
            <parameter-mapping
                intentParameter="menuItem.name"
                urlParameter="query" />
        </fulfillment>
    </action>
</actions>

Use the App Actions Test Tool to test web inventory on a physical device or emulator. To use the test tool, connect your test device and follow these steps:

  1. In Android Studio, go to Tools > App Actions > App Actions Test Tool.
  2. Click Create preview.
  3. In Android Studio, run your app on your test device.
  4. 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 ExampleApp".
  5. Observe the behavior of your app, or use the Android Studio debugger, to verify the desired action result.