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:
- In the
<action>
tag where you want to use web inventory, add a<fulfillment>
tag and set itsurlTemplate
attribute to{@url}
. - 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 forORDER_MENU_ITEM
, you link menu pages tomenuItem.name
. - In the new
<parameter>
tag, add a<entity-set-reference>
tag and set itsurlFilter
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:
- The first fulfillment requires a web inventory deep link from the
"menuItem.name"
parameter. - 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:
- 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 "Hey Google, order nuggets on Example App."
- Observe the behavior of your app, or use the Android Studio debugger, to verify the desired action result.