با App Actions، کاربران میتوانند مستقیماً با گفتن جملاتی مانند «Hey Google, منوی Three Dot Cafe را در ExampleApp به من نشان بده» وارد محتوای برنامه شما شوند. این قابلیت پیوند عمیق نامیده میشود و میتواند انجام کارها با برنامه شما را برای کاربران شما آسانتر کند.
برای انجام این نوع درخواست، دستیار Google یک پیوند عمیق به محتوای منطبق در برنامه شما ایجاد می کند. اگر به طور فعال وبسایت خود را با محتوا یا اطلاعات محصول نگهداری میکنید و پیوندهای عمیق درونبرنامه شما حول این محتوای وب عمومی سازماندهی شدهاند، میتوانید «دستیار» را پیکربندی کنید تا با استفاده از فهرست وب، نشانیهای وب برای انجام عملیات از وبسایت شما واکشی کند.
فهرست وب، مکان وبسایت نشانیهای وب مورد پشتیبانی شده توسط برنامه شما است. هنگامی که کاربر اقدام برنامه شما را فراخوانی میکند، «دستیار» عبارت جستجوی کاربر، مانند «Three Dot Cafe» را با نشانیهای وب مربوطه در فهرست جستجوی Google وبسایتی که در shortcuts.xml
برای برنامه Android خود مشخص کردهاید، مطابقت میدهد.
مزایا
موجودی وب مزایایی را برای برنامههایی با فهرستهای بزرگ و مرتباً بهروز شده از مواردی که کاربران در برنامه مشاهده یا سفارش میدهند، ارائه میدهد:
اطلاعات موجودی وب در وب سایت شما قرار دارد، بر خلاف داده های موجودی درون خطی ، که لیست اقلام را در برنامه شما ذخیره می کند. اجازه دسترسی دستیار به دادههای وب از خطر موجودی موجودی قدیمی کهنه میشود، که فقط با انتشار نسخه جدید برنامه بهروزرسانی میشود.
موجودی های درون خطی به 1000 مورد محدود شده است. در مقابل، موجودی وب هیچ محدودیتی برای آیتم ندارد و می تواند با نیازهای شما رشد کند.
موجودی وب میتواند منطق برنامه را سادهتر کند و به شما اجازه میدهد فقط URLهای محتوای قابل پیشبینی بازیابی شده از وبسایت شما را مدیریت کند. در مقابل، اگر موجودی پیکربندی نشده باشد، Assistant با نگاشت پارامترهای هدف به متغیرها در یک الگوی URL، پیوندهای عمیق را برای تکمیل ایجاد می کند. سپس تکمیل شما باید این URL ایجاد شده به صورت پویا را تجزیه و تحلیل کند تا مشخص شود آیا یک کاربر یک موجودیت پشتیبانی شده را در برنامه شما درخواست کرده است یا خیر.
چگونه کار می کند
در طول یک اقدام برنامه، دستیار از طریق مقاصد داخلی (BII) که در shortcuts.xml
تعریف میکنید، به محتوای برنامه پیوند میدهد. Assistant از پردازش زبان طبیعی برای شناسایی موارد مرتبط در درخواست کاربر و استخراج آنها در پارامترهای BII استفاده می کند. سپس Assistant یک پیوند عمیق را با استفاده از پارامترها بر اساس پیکربندی انجام شما در shortcuts.xml.
سه روش برای ایجاد پیوندهای عمیق برای تحقق وجود دارد:
- نگاشت پارامتر : پارامترهای هدف را به جایبانها در یک الگوی تکمیل URL نشان میدهد.
- موجودی درون خطی : پارامترهای هدف را با لیستی از
entities
پشتیبانی شده تعریف شده در برنامه مطابقت می دهد. - موجودی وب: پارامترهای هدف را با محتوای یافت شده در فهرست جستجوی گوگل یک وب سایت مطابقت می دهد.
فهرست وب یک الگوی URL وبسایت تعریفشده توسط توسعهدهنده است، مانند https://www.exampleapp.com/restaurants/.*
، که مجموعهای از موجودیتها را نشان میدهد که توسط یک برنامه پشتیبانی میشوند.
اگر یک پارامتر BII برای موجودی وب پیکربندی شده باشد، Assistant وب سایت را پرس و جو می کند تا یک موجودیت را با پرس و جو کاربر انجام دهد. سپس دستیار نتایج URL منطبق با الگوی URL پیکربندی شده، مانند https://www.exampleapp.com/restaurants/three-dot-cafe
را به شما ارسال می کند.
![](https://developer.android.com/static/guide/app-actions/images/web-inventory-flow.png?hl=fa)
اهداف داخلی پشتیبانی می شود
موجودی وب برای پارامترهای هدف خاص توسط BII های زیر پشتیبانی می شود:
- [
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
]
موجودی وب را اضافه کنید
هنگامی که یک BII پشتیبانی شده را شناسایی کردید، با به روز رسانی shortcuts.xml
با جزئیات مربوط به وب سایت خود، آن را برای موجودی وب فعال می کنید. فایل shortcuts.xml
منبعی در پروژه Android شما است که در آن BII هایی را که به عملکرد برنامه شما نشان می دهد و اینکه چگونه هر BII باید پیوندهای عمیق ایجاد کند تا برنامه شما انجام شود را تعریف می کنید. برای کسب اطلاعات بیشتر در مورد shortcuts.xml
، به ایجاد shortcuts.xml مراجعه کنید.
برای استفاده از موجودی وب برای یک BII پشتیبانی شده، این مراحل را دنبال کنید:
در فایل
shortcuts.xml
برای برنامه خود، یک تگ<capability>
با مجموعه ویژگیandroid:name
به نام BII که با موجودی وب مدیریت میکنید، اضافه کنید، برای مثال:actions.intent.ORDER_MENU_ITEM
.در تگ
<capability>
، یک تگ<intent>
با مجموعهandroid:action
به نام view اضافه کنید تا با این intent فعال شود.در همان تگ
<intent>
، یک تگ<parameter>
اضافه کنید و ویژگیandroid:name
آن را روی پارامتر BII تنظیم کنید که بیشترین مطابقت را با موجودیت توصیف شده توسط صفحات وب شما دارد. برای مثال، هنگام ارائه فهرست وب برایORDER_MENU_ITEM
، باید صفحات منو را بهmenuItem.name
پیوند دهید.در تگ
<parameter>
جدید، یک تگ<data>
اضافه کنید و ویژگیandroid:pathPattern
آن را روی الگوی URL مسیری که می خواهید برای موجودی وب استفاده کنید، تنظیم کنید.
وقتی shortcuts.xml
را با استفاده از این مراحل پیکربندی میکنید، «دستیار» میتواند محتوای وب را از فهرست جستجوی Google الگوی URL که در ویژگی android:pathPattern
ارائه کردهاید بازیابی کند. سپس Assistant با استفاده از نتایجی که با الگوی مسیر URL که تعریف کردهاید مطابقت دارد، مقدار URL را برای تحقق شما ارائه میکند. سپس برنامه شما کاربر را به مکان خاصی در برنامه شما بر اساس داده های URL ارائه شده توسط Assistant هدایت می کند.
برای مثال، وبسایت شما حاوی فهرستهای محصولاتی است که از مسیر URL استفاده میکنند که با https://www.examplecafe.com/items/
شروع میشود. شما از مقدار pathPattern
https://www.examplecafe.com/items/.*
استفاده می کنید و Assistant از این الگوی URL در جستجوی وب برای یافتن یک URL تکمیلی مانند https://www.examplecafe.com/items/item123
استفاده می کند. .
اگر Assistant URL موجودی وب منطبق را بیابد، URL را در قسمت <data>
هدف تحقق ارائه میکند، گویی یک پیوند عمیق است. از متد getData()
intent برای دریافت URL به عنوان یک شی Uri
استفاده کنید. فعالیت برنامه ای که هدف را دریافت می کند، مسئول تفسیر URL و فعال کردن رابط کاربری مناسب برنامه است.
نمونه shortcuts.xml
نمونه زیر یک ORDER_MENU_ITEM
BII را تعریف میکند که یک فهرست وب برای برگرداندن نتایج URL برای درخواستهای حاوی پارامتر menuItem.name
BII فراهم میکند:
<?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>
در نمونه بالا، یک pathPattern
برای menuItem.name
مشخص شده است که به Assistant دستور می دهد فقط URL هایی را برگرداند که با الگوی URL مطابقت دارند: https://www.examplecafe.com/items/.*
نمونههای shortcuts.xml
بیشتری از BII که از فهرست وب پشتیبانی میکنند در مستندات مرجع موجود هستند.
کنترل مجدد برای نتایج از دست رفته
در شرایطی که نتایج موجودی وب به انجام شما بازگردانده نمی شود، برنامه شما باید منطق بازگشتی را پیاده سازی کند تا عملکرد را با بهترین تجربه کاربری ممکن انجام دهد. موقعیت هایی که باعث از دست رفتن نتایج می شوند عبارتند از:
- پارامتر هدف گمشده : کاربر یک پارامتر مورد انتظار را در جستار خود حذف کرده یا دستیار پارامتر را در درخواست کاربر درک نکرده است.
- نتیجه URL گم شده : دستیار نتوانست موجودیتی را در وب سایت شما پیدا کند که با درخواست کاربر مطابقت داشته باشد.
شما می توانید با تعریف چندین عنصر <intent>
برای یک قابلیت، مقادیر پارامتر از دست رفته را مدیریت کنید. اگر Assistant نتواند قصد اول را برآورده کند، به قصد بعدی برمی گردد و به همین ترتیب.
مقاصد بازگشتی نباید به پارامترها نیاز داشته باشند. در عوض، آنها باید این قابلیت را با یک پیوند عمیق عمومی تر، مانند نمایش نتایج جستجو برای درخواست کاربر، انجام دهند.
در نمونه shortcuts.xml
زیر، یک ORDER_MENU_ITEM
BII دو تحقق را تعریف میکند: اولی یک URL از پارامتر menuItem.name
انتظار دارد. مورد دوم به هیچ پارامتری نیاز ندارد و کاربر را به صفحه ای هدایت می کند که همه آیتم های منو را نشان می دهد.
<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>
در شرایطی که URL موجودی وب برگردانده نمی شود، محتوای درخواست کاربر ممکن است همچنان در مقاصد بازگشتی استفاده شود، به عنوان مثال، برای نمایش نتایج جستجو.
در نمونه shortcuts.xml
زیر، دو عنصر intent تعریف شده است:
- اولین مورد نیاز به یک پیوند عمیق موجودی وب از پارامتر
menuItem.name
دارد. - اگر پیوند عمیق برگردانده نشد، هدف دوم نتایج جستجو را با استفاده از درخواست کاربر از
menuItem.name
، در صورت وجود، نمایش میدهد.
<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>
جستجوی درون برنامه ای را با موجودی وب اضافه کنید
میتوانید با ترکیب موجودی وب با اجرای actions.intent.GET\_THING
BII، کاربران را قادر به جستجوی محتوای وب در برنامه خود کنید.
این BII با استفاده از ویژگی جستجوی درونبرنامه پیشفرض در یک برنامه، محتوا یا موجودیتها را جستجو میکند و پرسشهایی مانند: «Hey Google, hikes waterfall on SampleApp را به من نشان بده». با پیکربندی موجودی وب برای پارامتر قابلیت thing.name
ارائه شده توسط GET_THING
BII، نتایج موجودیت منطبق از وب سایت شما برای تکمیل ارسال می شود.
برای نمونههای shortcuts.xml
موجودی وب، به مرجع GET\_THING
BII مراجعه کنید.
تست موجودی وب
وقتی یک موجودی وب را برای تکمیل BII تعریف میکنید، Assistant با استفاده از نتایج وب مطابق با الگوی urlTemplate
که برای پارامتر BII مشخص شده تعریف کردهاید، یک پیوند عمیق ایجاد میکند. اگر نتیجه موجودی وب پیدا نشد، Assistant یک URL مطابق با الگوی urlTemplate
هدف بازگشتی شما ایجاد میکند. میتوانید پیادهسازی موجودی وب خود را با تأیید اینکه پیوندهایی که «دستیار» ارائه میدهد، نشانیهای وب هستند که با الگوهای urlTemplate
موجودی وب شما مطابقت دارند، آزمایش کنید.
در نمونه زیر ORDER_MENU_ITEM
BII، Assistant پیوندهای تکمیل موجودی وب مطابق با الگوی urlFilter
مشخص شده در پارامتر menuItem.name
ایجاد میکند، برای مثال: https://www.examplecafe.com/items/nuggets
. قصد دوم مقدار menuItem.name
را می گیرد و اگر هدف اول با الگوی URL مطابقت نداشته باشد، جستجو را انجام می دهد.
<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>
برای آزمایش موجودی وب در یک دستگاه فیزیکی یا مجازی از ابزار آزمایش اقدامات برنامه استفاده کنید.
برای استفاده از ابزار تست، مراحل زیر را دنبال کنید:
- دستگاه آزمایشی خود را با برنامه در حال اجرا وصل کنید.
- در Android Studio، به Tools > App Actions > App Actions Test Tool بروید.
- روی ایجاد پیش نمایش کلیک کنید.
- در Android Studio، برنامه خود را روی دستگاه آزمایشی خود اجرا کنید.
- از برنامه Assistant در دستگاه آزمایشی خود برای آزمایش App Action خود استفاده کنید. برای مثال، میتوانید چیزی شبیه به «Hey Google, order nuggets on ExampleCafe» را بگویید.
- رفتار برنامه خود را مشاهده کنید یا از دیباگر Android Studio استفاده کنید تا نتیجه اقدام مورد نظر را تأیید کنید.