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, 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 website 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 updated lists of items 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 risk of stale 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 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 (BIIs) 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
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.
![](https://developer.android.google.cn/static/guide/app-actions/images/web-inventory-flow.png?authuser=9)
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, 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 anandroid: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 anandroid: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 itsandroid: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 should link menu pages tomenuItem.name
.In the new
<parameter>
tag, add a<data>
tag and set itsandroid: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 can
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 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 were 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 match the URL pattern:
https://www.examplecafe.com/items/.*
More shortcuts.xml
examples of BII that support web inventory are
available in the reference documentation.
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 did not 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.
<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.
<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 that Assistant
provides are 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.
<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.