مقاصد سفارشی

هر برنامه متفاوت است، و همه عملکردهای برنامه با هدف داخلی (BII) در دسترس App Actions مطابقت ندارند. برای مواردی که BII برای عملکرد برنامه شما وجود ندارد، می‌توانید در عوض از یک هدف سفارشی برای گسترش برنامه خود با App Actions استفاده کنید.

مانند BII ها، مقاصد سفارشی از طرح shortcuts.xml پیروی می کنند و به عنوان نقاط اتصال بین Assistant و اجراهای تعریف شده شما عمل می کنند. مقاصد سفارشی همچنین دارای پارامترهای intent هستند که می‌توانید آن‌ها را به پارامترهایی در انجام مربوطه خود نگاشت کنید.

برخلاف BII ها، مقاصد سفارشی به الگوهای پرس و جو برای توصیف پرس و جوهای نمونه ای که کاربر ممکن است بگوید نیاز دارد. این رویکرد با مقاصد داخلی متفاوت است، که روش‌های رایجی را که کاربران آن قصد را بیان می‌کنند، مدل می‌کنند.

محدودیت ها

مقاصد سفارشی دارای محدودیت های زیر هستند:

• نام یک intent سفارشی نمی تواند با actions.intent شروع شود.
• نام یک هدف سفارشی باید در میان نام‌های هدف سفارشی برای برنامه شما منحصر به فرد باشد.
• فقط انواع داده های خاصی برای استخراج پارامتر توسط دستیار Google در دسترس هستند (به انواع پشتیبانی شده مراجعه کنید).
• مقاصد سفارشی باید حاوی نمونه هایی از الگوهای پرس و جو قابل استفاده باشد (به الگوهای پرس و جو مراجعه کنید).
• هر کوئری حداکثر از دو پارامتر متنی پشتیبانی می کند. این محدودیت برای سایر انواع داده اعمال نمی شود.
• مقاصد سفارشی فقط از محلی en-US پشتیبانی می کنند. همچنین، تنظیمات زبان دستگاه و دستیار باید مطابقت داشته باشند.

انواع پشتیبانی شده

Intent های سفارشی از انواع schema.org زیر برای استخراج پارامتر پشتیبانی می کنند:

• https://schema.org/Text
• https://schema.org/Date
• https://schema.org/Time
• https://schema.org/Number

Action های برنامه را با اهداف سفارشی تعریف کنید

مانند سایر App Actions که از BII استفاده می کنند، شما یک هدف سفارشی را در عنصر <capability> در shortcuts.xml تعریف می کنید.

قابلیت ها در عنصر ریشه <shortcuts> تعریف می شوند. هنگامی که عنصر <shortcuts> خود را تعریف می کنید، فضای نام ویژگی هایی را که می خواهید به آنها دسترسی داشته باشید، اضافه کنید، همانطور که در مثال زیر نشان داده شده است:

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  ...
</shortcuts>

نام intent سفارشی را در ویژگی android:name وارد کنید و به فایل منبع Query Patterns در ویژگی queryPatterns ارجاع دهید.

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.EXAMPLE_INTENT"
      app:queryPatterns="@array/ExampleQueries">
    <intent ...>
      <url-template
          android:value="http://custom.com{?number_of_items,item_name}" />
      <parameter
          android:name="number_of_items"
          android:key="number_of_items"
          android:mimeType="https://schema.org/Number" />
      <parameter
          android:name="item_name"
          android:key="item_name"
          android:mimeType="https://schema.org/Text" />
    </intent>
  </capability>
  ...
</shortcuts>

نام‌های هدف سفارشی نمی‌توانند با actions.intent شروع شوند، زیرا آن فضای نام برای BII رزرو شده است. در عوض، هنگام نام‌گذاری اهداف سفارشی خود، از پیشوند custom.actions.intent استفاده کنید تا مقاصد سفارشی خود را از هر دو BII و intent Android که عملکرد متفاوتی دارند، متمایز کنید.

برای هر پارامتر، نوع پشتیبانی شده schema.org را ارائه کنید که به بهترین وجه معنای پارامتر را توصیف می کند. برای مثال، می‌توانید از https://schema.org/Date برای توصیف تاریخی که انتظار دریافت آن را دارید استفاده کنید:

...
<intent>
  <url-template android:value="https://example.com/appt{?apptType,date,time}" />
  <parameter
      android:name="date"
      android:key="date"
      android:mimeType="https://schema.org/Date" />
  ...
</intent>
...

با استفاده از همان فرمت میانبرهای BII، میانبرهایی را برای مقاصد سفارشی در shortcuts.xml تعریف کنید.

کد زیر یک Action Action را توصیف می‌کند که از الگوهای جستجوی ارجاع‌شده برای راه‌اندازی هدف سفارشی SCHEDULE_APPOINTMENT استفاده می‌کند و از مجموعه‌ای از مقادیر تعریف‌شده، DRIVERS_LICENSE و VEHICLE_REGISTRATION برای پارامتر apptType استفاده می‌کند.

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.SCHEDULE_APPOINTMENT"
      app:queryPatterns="@array/scheduleApptQueries">
    <intent ...>
     <url-template android:value="https://example.com/appt{?apptType,date,time}" />
       <parameter
          android:name="date"
          android:key="date"
          android:mimeType="https://schema.org/Date" />
       <parameter
          android:name="time"
          android:key="time"
          android:mimeType="https://schema.org/Time" />
       <!-- The following parameter has no type because the shortcuts are bound to it -->
       <parameter android:name="apptType" android:key="apptType" />
    </intent>
  </capability>

  <shortcut
      android:shortcutShortLabel="Driver's License"
      android:shortcutId="DRIVERS_LICENSE">
    <capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
      <parameter-binding
          android:key="apptType"
          android:value="@string/driversLicense" />
    </capability-binding>
  </shortcut>

  <shortcut
      android:shortcutsShortLabel="Vehicle Registration"
      android:shortcutId="VEHICLE_REGISTRATION">
    <capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
      <parameter-binding
          android:key="apptType"
          android:value="@string/vehicleRegistration" />
    </capability-binding>
  </shortcut>
</shortcuts>

شما می توانید پارامترهای هدف سفارشی را با موجودی درون خطی پیکربندی کنید، که می توانید از آنها برای هدایت استخراج موجودیت به مجموعه ای از موجودیت های پشتیبانی شده مشخص شده در shortcuts.xml استفاده کنید.

الگوهای پرس و جو

هر هدف سفارشی که استفاده می کنید به مجموعه ای از پرس و جوهای مورد انتظار از کاربر برای آن هدف نیاز دارد. این رویکرد بر خلاف BII ها است، که در آن پرس و جوها از قبل برای روش های رایجی که کاربران وظایفی را که می خواهند انجام دهند یا اطلاعاتی را که به دنبال آن هستند بیان می کنند، مدل سازی شده است.

در یک فایل منبع Android (معمولا /res/values/strings.xml )، الگوهای پرس و جو را به عنوان موارد در یک آرایه رشته ای مشخص کنید. وقتی App Action شما فراخوانی می‌شود، Google Assistant عبارت جستجوی کاربر را در برابر الگوهای پرس و جو شما به عنوان بخشی از مطابقت با هدف کاربر برای انجام بررسی می‌کند. هر الگوی درخواستی که ارائه می‌کنید بیانگر عبارتی است که شما آن را برای هدف سفارشی مربوطه معتبر می‌دانید.

هنگام ارائه الگوهای پرس و جو برای مقاصد سفارشی، انتظار داشته باشید که هر الگو از یک فراخوان صریح مانند «باز کردن برنامه مثال و» یا «شروع نمونه برنامه و» پیروی کند. به عنوان مثال، پرس و جوهای کاربر زیر را در نظر بگیرید:

• "Hey Google، Example Game App را باز کن و شروع به ساختن کیک کن."
• "Hey Google، Example Game App را باز کنید و شروع به تهیه پای سیب کنید."
• «Hey Google، Example Game App را شروع کنید و 5 مورد کیک درست کنید.»
• "Hey Google، از Example Game App برای تولید کیک 5 بار استفاده کنید."

برای مطابقت با پرس و جوهای کاربر، الگوهای پرس و جو را ارائه کنید که شامل بخشی از پرس و جو بعد از عبارت فراخوانی است. برای اطلاعاتی که می خواهید از پرس و جو استخراج کنید (مانند متن یا عددی که کاربر ارائه می کند)، مقادیری را به پارامتر intent مربوطه با متغیرهایی در الگوی پرس و جو اختصاص می دهید.

برای ارجاع به یک پارامتر در الگوی پرس و جو، $ به نام پارامتر در الگوی خود اضافه کنید. به عنوان مثال، برای ایجاد یک مقدار مکان نگهدار برای پارامتری مانند <parameter name="date1" ... (در actions.xml ) یا <parameter android:name="date1" ... (در shortcuts.xml )، شما از $date1 استفاده کنید.

کد زیر الگوهای پرس و جو را توصیف می کند که با پرس و جوهای کاربر قبلی مطابقت دارند و مقادیر نام اقلام و تعداد مواردی که باید ساخته شوند را استخراج می کند:

<resources>
  <string-array name="ExampleQueries">
    <item>start making a $text1</item>
    <item>start making an $text1</item>
    <item>craft $number1 $text1 items</item>
    <item>produce $text1 $number1 times</item>
  </string-array>
</resources>

الگوهای پرس و جو از شرطی ها پشتیبانی می کنند. به عنوان مثال، set (an)? appointment $date $time . در این مورد، هم «قرار امروز ظهر تعیین کنید» و هم «قرار امروز ظهر تعیین کنید» سؤالات معتبر هستند.