هر برنامه متفاوت است، و همه عملکردهای برنامه با هدف داخلی (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
اقدامات برنامه را با اهداف سفارشی تعریف کنید
مانند سایر 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
. در این مورد، هم «قرار امروز ظهر تعیین کنید» و هم «قرار امروز ظهر تعیین کنید» سؤالات معتبر هستند.