Web inventory (deprecated)

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 Example App.” This functionality is called deep linking, and it 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 letting your fulfillment 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 needs to analyze this dynamically generated URL to determine whether 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 ways 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 queries 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 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:

• 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

Add web inventory

Once you identify a supported BII, 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 generates 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 as follows:

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

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, suppose 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 uses 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 preceding 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 for BII that support web inventory.

In-app search with web inventory

Let users 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 Sample App.” By configuring web inventory for the thing.name intent parameter passed by the GET_THING BII, matching entity results from your website are 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, 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 don't require parameters. Instead, they fulfill the action with a more generic deep link, such as displaying search results for the user query.

In the following sample actions.xml file, a 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 can be used in fallback fulfillments, for example, to display search results.

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

1. The first fulfillment 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>

Test 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 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 looks 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 "Hey Google, order nuggets on Example App."
5. Observe the behavior of your app, or use the Android Studio debugger, to verify the desired action result.