موجودی وب

با 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 را به شما ارسال می کند.

شکل 1. یک نمونه پرس و جو دستیار با استفاده از موجودی وب برای بازیابی یک مورد موجودیت رستوران.

اهداف داخلی پشتیبانی می شود

موجودی وب برای پارامترهای هدف خاص توسط 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 پشتیبانی شده، این مراحل را دنبال کنید:

  1. در فایل shortcuts.xml برای برنامه خود، یک تگ <capability> با مجموعه ویژگی android:name به نام BII که با موجودی وب مدیریت می‌کنید، اضافه کنید، برای مثال: actions.intent.ORDER_MENU_ITEM .

  2. در تگ <capability> ، یک تگ <intent> با مجموعه android:action به نام view اضافه کنید تا با این intent فعال شود.

  3. در همان تگ <intent> ، یک تگ <parameter> اضافه کنید و ویژگی android:name آن را روی پارامتر BII تنظیم کنید که بیشترین مطابقت را با موجودیت توصیف شده توسط صفحات وب شما دارد. برای مثال، هنگام ارائه فهرست وب برای ORDER_MENU_ITEM ، باید صفحات منو را به menuItem.name پیوند دهید.

  4. در تگ <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 تعریف شده است:

  1. اولین مورد نیاز به یک پیوند عمیق موجودی وب از پارامتر menuItem.name دارد.
  2. اگر پیوند عمیق برگردانده نشد، هدف دوم نتایج جستجو را با استفاده از درخواست کاربر از 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>

برای آزمایش موجودی وب در یک دستگاه فیزیکی یا مجازی از ابزار آزمایش اقدامات برنامه استفاده کنید.

برای استفاده از ابزار تست، مراحل زیر را دنبال کنید:

  1. دستگاه آزمایشی خود را با برنامه در حال اجرا وصل کنید.
  2. در Android Studio، به Tools > App Actions > App Actions Test Tool بروید.
  3. روی ایجاد پیش نمایش کلیک کنید.
  4. در Android Studio، برنامه خود را روی دستگاه آزمایشی خود اجرا کنید.
  5. از برنامه Assistant در دستگاه آزمایشی خود برای آزمایش App Action خود استفاده کنید. برای مثال، می‌توانید چیزی شبیه به «Hey Google, order nuggets on ExampleCafe» را بگویید.
  6. رفتار برنامه خود را مشاهده کنید یا از دیباگر Android Studio استفاده کنید تا نتیجه اقدام مورد نظر را تأیید کنید.