هنگامی که عملکرد درونبرنامهای خود و هدف داخلی (BII) مربوطه را برای پیادهسازی شناسایی کردید، با تعریف یک عنصر capability
در فایل منبع shortcuts.xml
، BIIهایی را که عملکرد شما پشتیبانی میکنند، اعلام کنید. اعلام یک BII بهعنوان یک capability
، پشتیبانی از آن هدف معنایی را در برنامه شما ثبت میکند و انجام درخواست صوتی هدف را با استفاده از Google Assistant فعال میکند.
دستیار از پردازش زبان طبیعی برای استخراج پارامترها از درخواست کاربر استفاده می کند. مرجع مقاصد داخلی، فیلدهایی را فهرست می کند که هر BII می تواند از یک درخواست کاربر مرتبط استخراج کند. برای مثال، اگر کاربری قابلیت actions.intent.ORDER_MENU_ITEM
را در برنامه شما با گفتن «Hey Google, order a pizza from ExampleCafe in ExampleApp» فراخوانی کند، Assistant پارامترهای BII زیر را از درخواست کاربر استخراج میکند:
-
menuItem.name
= "پیتزا" -
menuItem.inMenuSection.inMenu.forRestaurant.name
= "ExampleCafe"
دستیار پارامترهای BII را به intent
تحقق تعریف شده در capability
ارسال می کند. یک یا چند عنصر intent
را می توان در قابلیتی تعریف کرد که راه های مختلفی را که کاربر ممکن است یک BII را فراخوانی کند، تطبیق دهد. به عنوان مثال، می توانید یک intent
تحقق را تعریف کنید که به هر دو پارامتر BII در مثال بالا نیاز دارد. سپس میتوانید هدف دومی را تعریف کنید که به یک پارامتر BII نیاز دارد، menuItem.name
، که اگر کاربر درخواست سادهتری ارائه کند، گزینههای رستوران اطراف را نشان میدهد، مانند «Hey Google, order a pizza on ExampleApp».
نمای کلی
شما با استفاده از یک فایل shortcuts.xml
که در دایرکتوری res/xml
پروژه برنامه خود قرار داده شده است، تنظیمات برنامه را پیکربندی میکنید و سپس یک مرجع به shortcuts.xml
در مانیفست برنامه خود ایجاد میکنید. با دنبال کردن این مراحل، یک مرجع به shortcuts.xml
در مانیفست برنامه خود اضافه کنید:
در فایل مانیفست برنامه خود (
AndroidManifest.xml
)، فعالیتی را بیابید که فیلترهای هدف آن روی عملکردandroid.intent.action.MAIN
و دستهandroid.intent.category.LAUNCHER
تنظیم شده است.با استفاده از یک تگ
<meta-data>
درActivity
که دارای فیلترهای هدف برایMAIN
وLAUNCHER
است، یک مرجع بهshortcuts.xml
درAndroidManifest.xml
اضافه کنید، به شرح زیر:<meta-data android:name="android.app.shortcuts" android:resource="@xml/shortcuts" />
مثال بالا یک منبع XML را برای فایل xml/shortcuts.xml
در APK اعلام می کند. برای جزئیات بیشتر در مورد پیکربندی میانبرها، به ایجاد میانبرهای ایستا در مستندات برنامه نویس Android مراجعه کنید.
کتابخانه Jetpack androidx.core:core:1.6.0
(یا بالاتر) در پروژه Android شما مورد نیاز است تا هنگام تعریف قابلیتهای App Actions در shortcuts.xml
از خطاهای جمعآوری جلوگیری شود. برای جزئیات، شروع به کار با Android Jetpack را ببینید.
میانبرهای ثابت
هنگام تعریف capability
خود، می توانید عناصر shortcut
استاتیک را در shortcuts.xml
اعلام کنید تا عملکرد قابلیت را گسترش دهید. هنگامی که نسخه ای را در کنسول Google Play آپلود می کنید، میانبرهای ایستا توسط دستیار دریافت می شود. از آنجایی که میانبرهای ایستا را می توان تنها با ایجاد نسخه های جدید ایجاد و به روز کرد، آنها برای برجسته کردن فعالیت ها و محتوای رایج در برنامه شما بسیار مفید هستند.
می توانید عملکرد App Actions زیر را با میانبرهای ثابت فعال کنید:
میانبرهای قابلیت میانبرهایی ایجاد کنید که نمونه ای از
capability
شما حاوی مقادیر پارامترintent
از پیش تعریف شده را راه اندازی کند. برای مثال، میتوانید میانبر برنامه را «شروع یک اجرا» اعلام کنید که قابلیتSTART_EXERCISE
BII را در برنامه تناسب اندام شما فراخوانی میکند.این میانبرها حاوی ویژگیهای
intent
،shortLabel
وlongLabel
هستند، که آنها را واجد شرایط میکند تا بهعنوان تراشه در سطوح فعال، مانند Assistant یا هنگام فشار طولانی یک نماد برنامه در راهاندازهای Android، پیشنهاد و اجرا شوند. یک میانبر اقدام همچنین می تواند به عنوان یک میانبر موجودیت، با مرتبط کردن آن با یکcapability
با استفاده از یک برچسب<capability-binding>
، عمل کند.میانبرهای موجودیت میانبرهای موجودیت فهرستی از مقادیر پارامترهای پشتیبانی شده را برای انجام درخواست صوتی یک
capability
ارائه میکنند. به عنوان مثال، یک میانبر موجودیت با فهرستی از انواع تمرین ("Hike"، "Run"، و غیره) که به پارامتر BIIexercise.name
از قابلیتSTART_EXERCISE
متصل شده است. اگر یک گفته کاربر با یک موجود مطابقت داشته باشد، شناسهshortcutId
به جای مقدار درخواست خام کاربر به intent ارسال می شود.میانبرهای
Entity
، ویژگیهایintent
،shortLabel
یاlongLabel
را تعریف نمیکنند و به این ترتیب در سطوح فعال پیشنهاد نمیشوند. برای جزئیات، موجودی درون خطی برای اقدامات برنامه را ببینید.
طرح واره قابلیت
جدول زیر طرح اقدامات برنامه را برای عناصر capability
در shortcuts.xml
توضیح می دهد. هنگام گنجاندن یک برچسب، تمام ویژگی های آن مورد نیاز است مگر اینکه "اختیاری" علامت گذاری شود.
تگ Shortcuts.xml | موجود در | صفات |
---|---|---|
<capability> | <shortcuts> | |
<intent> | <capability> | |
<url-template> | <intent> | |
<extra> | <intent> | فقط برای فراخوانی برنامه پیش زمینه قابل اجرا است |
<parameter> | <intent> | |
<data> | <parameter> | android:pathPattern (فقط برای موجودی وب قابل استفاده است) |
<shortcut-fulfillment> | <capability> | فقط برای موجودی درون خطی قابل استفاده است |
<parameter> | <shortcut-fulfillment> | android:name |
<slice> | <capability> | فقط برای Slices Android قابل اجراست |
شرح طرحواره قابلیت
این بخش عناصر طرحواره capability
را توضیح می دهد.
<قابلیت>
capability
که هدف App Action را که برنامه شما پشتیبانی می کند را مشخص می کند. هر عنصر <capability>
در فایل shortcuts.xml
شما باید حداقل یک <intent>
را برای انجام عملیات انجام دهد.
ویژگی ها:
-
android:name
: شناسه اقدام داخلی (به عنوان مثالactions.intent.CREATE_TAXI_RESERVATION
). برای لیستی از اهداف داخلی پشتیبانی شده، به مرجع هدف داخلی مراجعه کنید. -
app:queryPatterns
: یک منبع آرایه رشته ای از پرس و جوهایی که از کاربر برای این هدف انتظار می رود. این ویژگی فقط برای مقاصد سفارشی قابل استفاده است، زیرا BIIها قبلاً شامل مدلهایی از روشهای رایجی است که کاربران وظایفی را که میخواهند انجام دهند یا اطلاعاتی را که به دنبال آن هستند بیان میکنند.
<قصد>
عنصر intent
Android که نحوه انجام درخواست کاربر را با استفاده از عملکرد درون برنامه ای مشخص می کند. توسعه دهندگان ممکن است چندین تگ <intent>
را در یک capability
ارائه کنند. دستیار با استفاده از اولین <intent>
در capability
که تمام پارامترهای مورد نیاز برای آن ارائه شده است، تلاش می کند تا یک درخواست کاربر را انجام دهد.
ویژگی ها:
-
android:action
: نوعAction
قصد. پیشفرضACTION_VIEW
است. -
android:targetClass
: کلاس فعالیت هدف، به عنوان مثال:"com.example.food.OrderActivity"
-
android:targetPackage
: بسته حاوی کلاس Activity هدف، به عنوان مثال:"com.example.food"
-
android:data
: اگر آن تگ درintent
اعلان شده باشد، این فیلد توسط<url-template>
بازنویسی می شود.
<url-template>
الگوی ساخت یک URI پیوند عمیق که در دستگاه باز می شود. اگر تمام پارامترهای لازم برای الگو در دسترس باشد، ممکن است الگو با پارامترهای هدف داخلی گسترش یابد. برای نمونههایی از الگوی URL HTTP، به مقاله ویکیپدیا در مورد الگوهای URL مراجعه کنید. قالب الگو از مشخصات قالب RFC6570 URI پیروی می کند.
در زیر چند نمونه از مقادیر قالب URL آورده شده است:
الگو | ارزش ها | ارزش گسترش یافته |
---|---|---|
https://example.com/test{?foo,bar} | "foo": "123" | https://example.com/test?foo=123&bar=456 |
https://example.com/test?utm_campaign=appactions{&foo,bar} | "foo": "123" | https://example.com/test?utm_campaign=appactions&foo=123&bar=456 |
https://example.com/test?utm_campaign=appactions{#foo} | "foo": "123" | https://example.com/test?utm_campaign=appactions#foo=123 |
myapp://example/{foo} | "foo": "123" | myapp://example/123 |
برای اطلاعات بیشتر درباره پیکربندی الگوهای URL، به الگوهای URL در حال تکمیل مراجعه کنید.
<اضافی>
داده های اضافی را برای یک intent
تعریف می کند. برای اقدامات برنامه، این فیلد فقط برای فعال کردن فراخوانی برنامه پیشزمینه برای یک capability
استفاده میشود.
<پارامتر>
یک پارامتر BII را به مقادیر پارامتر intent نگاشت می کند. برای اطلاعات بیشتر، دادههای پارامتر و تطبیق را ببینید.
ویژگی ها:
-
android:name
: نام پارامتر BII برای ارتباط با این پارامترintent
. نام باید یک فیلد سطح برگ از پارامتر BII باشد (به عنوان مثالfoodObservation.aboutFood.name
). -
android:key
: کلید تعریف شده توسط توسعه دهنده با مقدار پارامتر BII. برای مثال، ممکن استcontact_name
برای پارامترmessage.recipient.name
BII تعریف کنید. -
android:mimeType
: mimeType پارامتر، مانندtext/*
. این فیلد فقط برای پارامترهای intent های سفارشی مورد نیاز است. -
android:required
: اعلام می کند که آیا درخواست کاربر باید این پارامتر را شامل شود تا این هدف برای تحقق استفاده شود. اگر پارامتر در دسترس نباشد، دستیار تلاش میکند تا درخواست کاربر را با استفاده ازintent
بعدی تعریفشده برایcapability
انجام دهد.
<داده>
موجودی وب را به یک parameter
مرتبط می کند.
صفت:
android:pathPattern
: الگوی URL برای نشانیهای اینترنتیentity
که با استفاده از فهرست وب بازگردانده میشوند. این ویژگی از دو عام پشتیبانی می کند:*
: یک ستاره با دنباله ای از صفر یا بیشتر از نویسه بلافاصله قبل مطابقت دارد..*
: نقطه به دنبال ستاره با هر دنباله ای از نویسه های صفر یا بیشتر مطابقت دارد.کاراکترهای Escape فقط برای
*
و\
لفظی مورد نیاز هستند که می توانید به ترتیب به صورت\\*
و\\\\
از آنها فرار کنید.
<shortcut-fulfillment>
مشخص می کند که یک intent
تعریف شده در میانبر موجودی درون خطی برای یک پارامتر مشخص، برای تکمیل استفاده شود. برای جزئیات، به تکمیل با استفاده از اهداف میانبر مراجعه کنید.
<parameter> (برای <shortcut-fulfillment>
)
ویژگی اختیاری که یک پارامتر BII را برای تکمیل میانبر موجودی درون خطی ترسیم می کند. برای جزئیات، به تکمیل با استفاده از اهداف میانبر مراجعه کنید.
صفت:
-
android:name
: نام پارامتر BII برای ارتباط با تکمیل میانبر موجودی درون خطی. نام باید یک فیلد سطح برگ از پارامتر BII باشد (برای مثالmenuItem.name
).
<برش>
دستیار را قادر میسازد تا نتیجه جستجوی مطابق با این capability
بهعنوان یک Android Slice جاسازی کند. برای جزئیات، به ادغام اقدامات برنامه با برش های Android مراجعه کنید.
طرح میانبر
جدول زیر ویژگی های عناصر shortcut
را توضیح می دهد که برای فعال کردن عملکرد App Actions استفاده می شود. هنگام گنجاندن یک برچسب، تمام ویژگی های آن مورد نیاز است مگر اینکه "اختیاری" علامت گذاری شود.
تگ Shortcuts.xml | موجود در | صفات |
---|---|---|
<shortcut> | <shortcuts> | |
<intent> | <shortcut> | |
<capability-binding> |
| |
<parameter-binding> | <capability-binding> | |
<extra> | <shortcut> | فقط برای تطبیق پارامتر Enum قابل استفاده است. |
شرح طرح میانبر
این بخش عناصر طرح shortcut
را توضیح می دهد.
<میانبر>
یک <shortcut>
Android که در shortcuts.xml
با ویژگیهای خاص مرتبط با App Actions تعریف شده است. مقادیر رشته برای فیلدهای shortcutShortLabel
و shortcutLongLabel
از طریق منابع رشته APK ارجاع میشوند.
ویژگی ها:
-
android:shortcutId
: شناسه این میانبر. -
android:shortcutShortLabel
: منبع رشته ای که یک عبارت میانبر کوتاه را نشان می دهد. به عنوان مثال،"@string/callDavidShort"
نشان دهنده مقدار "Call David." -
android:shortcutLongLabel
: منبع رشته ای که یک عبارت میانبر طولانی را نشان می دهد. به عنوان مثال،"@string/callDavidLong"
نشان دهنده مقدار "Make an audio call to David."
<قصد>
هدف Android مرتبط با این میانبر است. این intent
زمانی اجرا می شود که کاربر این میانبر را با استفاده از صدا یا لمس راه اندازی کند.
ویژگیهای intent shortcut
با ویژگیهای intent
capability
یکسان هستند.
<capability-binding>
shortcut
را به capability
App Actions مرتبط می کند. افزودن این عنصر به shortcut
آن را قادر میسازد تا با استفاده از Assistant
، صدا را انجام دهد.
ویژگی ها:
-
android:key
: ویژگیandroid:name
capability
که اینshortcut
به آن محدود شده است. برای مثالactions.intent.CREATE_TAXI_RESERVATION
.
<parameter-binding>
ویژگی اختیاری که shortcut
به یک پارامتر واحد از capability
App Actions مرتبط می کند. اگر یک parameter-binding
برای یک shortcut
تعریف شده باشد، از میانبر می توان برای ارائه موجودی درون خطی به یک پارامتر BII استفاده کرد. برای جزئیات بیشتر، به فهرست موجودی Inline Actions App مراجعه کنید.
ویژگی ها:
-
android:key
: نام پارامتر BIIcapability
برای مرتبط کردن این میانبر به. برای مثال،foodObservation.aboutFood.name
. -
android:value
: مقدارentity
. این می تواند یکentity
واحد یا یک لیست منبع باشد.
<اضافی>
داده های بسته extra
برای میانبر. sameAs تنها داده مربوط به عناصر shortcut
App Actions است. URL sameAs به یک صفحه وب مرجع اشاره دارد که به طور واضح موجودیت را شناسایی می کند. برای تعیین مقدار enum استفاده میشود اگر و تنها در صورتی که نوع پارامتر intent زیرنوع schema.org/Enumeration باشد. برای فیلدهای پارامتری که انواع آنها زیرشاخههای schema.org/Enumeration
هستند (به عنوان مثال: MealTypeBreakfast
) لازم است.
ویژگی ها:
-
android:key
: مقدار پشتیبانی شده برای App Actions:sameAs
است -
android:value
:sameAs
مقدار URL
برای جزئیات بیشتر، مطابقت مقادیر پارامتر شمارش شده را ببینید.
گزینه های تحقق هدف
شما عناصر intent
را در یک <capability>
تعریف میکنید تا نحوه پاسخ یا اجرای دستورات صوتی کاربر را که دستیار با آن قابلیت مطابقت دارد، اعلام کند. بسته به ساختار ناوبری برنامه شما، چندین راه برای پیکربندی نحوه راه اندازی یک intent
در برنامه شما وجود دارد.
گزینه های تکمیل زیر در دسترس هستند:
اهداف صریح : با تعریف ویژگی های
targetClass
وtargetPackage
برایintent
، یک جزء برنامه خاص را راه اندازی کنید. این روش اجرای App Actions توصیه شده است.پیوندهای عمیق : با تعریف یک برچسب
<url-template>
در عنصرintent
، مقصد برنامه را با استفاده از پیوندهای عمیق Android راه اندازی کنید. این روش در صورتی مفید است که پیمایش برنامه شما قبلاً به پیوندهای عمیق متکی باشد.دادههای هدف : میتوانید یک URI تکمیلی در ویژگی
intent
android:data
ارائه کنید. این فیلد توسط دادههای<url-template>
بازنویسی میشود اگر آن تگ نیز درintent
تعریف شده باشد.
داده های پارامتر و تطبیق
بهطور پیشفرض، «دستیار» پارامترهای BII استخراجشده از درخواست کاربر را بهعنوان دادههای extra
از intent
Android تعریفشده در capability
به برنامه شما ارسال میکند.
متناوبا، میتوانید یک تگ <url-template>
را در capability
که حاوی متغیرهایی برای پارامترهای پویا است، اعلام کنید. این الگو با استفاده از نشانی اینترنتی پیوندهای برنامه ، طرح سفارشی یا نشانی اینترنتی مبتنی بر هدف، به یکی از فعالیتهای Android شما نگاشت میشود.
استفاده از Intent Extras
مثال زیر یک هدف صریح تعریف شده برای تحقق capability
را نشان می دهد:
<capability android:name="actions.intent.ORDER_MENU_ITEM">
<intent
android:targetPackage="com.example.myapp"
android:targetClass="com.example.myapp.OrderMenuItemActivity">
<parameter android:name="menuItem.name" android:key="menu" />
</intent>
</capability>
با توجه به نمونه بالا، برای یک درخواست کاربر مانند «Hey Google، یک latte از ExampleApp سفارش دهید»، برنامه یک intent
دریافت میکند که مؤلفه را فراخوانی میکند: targetPackage
، targetClass
. کامپوننت یک Extra با key = ”menu”
، value = ”latte”
دریافت می کند.
استفاده از قالب URL برای لینک های عمیق اندروید
اگر برنامه شما در حال حاضر قادر به مدیریت URL های مرتبط با برنامه است، با پارامترهای پویا، می توانید یک <url-template>
را intent
ایجاد پیوندهای عمیق اندروید برای تحقق تعریف کنید. نمونه زیر یک <url-template>
را تعریف می کند:
<capability android:name="actions.intent.ORDER_MENU_ITEM">
<intent>
<url-template android:value="myapp://order{?menu}" />
<parameter android:name="menuItem.name" android:key="menu" />
</intent>
</capability>
با توجه به نمونه بالا، برای درخواست کاربر مانند «Hey Google، یک لاته از ExampleApp سفارش دهید»، برنامه URL تولید شده را دریافت می کند: «myapp://order?menu=latte».
برای نگاشت پارامتر BII به یک موقعیت در URL خود، از ویژگی android:name
تگ <parameter>
استفاده می کنید. این ویژگی مربوط به مقدار android:key
در قالب URL است که میخواهید با اطلاعات کاربر جایگزین کنید. مقدار android:key
باید در <url-template>
شما وجود داشته باشد و با پرانتزهای فرفری ( {}
) محصور شود.
مقادیر پارامتر شمارش شده را مطابقت دهید
برخی از پارامترهای BII مقادیر برشماری شده ای را برای هدف تحقق شما ارائه می دهند، به عنوان مثال، مقادیر متنی پشتیبانی شده RECORD_FOOD_OBSERVATION
BII. برای این پارامترها، Assistant عبارت جستجوی کاربر ("Breakfast") را با موجودی مطابقت می دهد که مقدار sameAs
آن با URL طرح enum مطابقت دارد ( https://schema.googleapis.com/MealTypeBreakfast
). برای مرتبط کردن مقادیر enum برای یک entity
پشتیبانی شده، یک ارتباط sameAs
را در shortcut
خود اعلام می کنید. نمونه زیر یک ارتباط sameAs
را برای میانبر موجودیت درون خطی نشان می دهد:
<shortcut android:shortcutId="meal_breakfast" >
<capability-binding android:key="actions.intent.RECORD_FOOD_OBSERVATION">
<parameter-binding android:key="foodObservation.forMeal" />
</capability-binding>
<extra
android:key="sameAs"
android:value="http://schema.googleapis.com/MealTypeBreakfast" />
</shortcut>
<capability android:name="actions.intent.RECORD_FOOD_OBSERVATION">
<intent targetPackage="com.example.app" targetClass="com.example.app.Class">
<parameter android:name="foodObservation.forMeal" android:key="for_meal" />
</intent>
</capability>
در مثال بالا، اگر قابلیت RECORD_FOOD_OBSERVATION
مطابقت با نوع وعده غذایی "صبحانه" را ایجاد کند، موارد اضافی زیر با intent
تحقق ارسال می شود:
-
key = "for_meal"
-
value = "meal_breakfast"
ویژگی ها
ویژگیهای App Actions زیر در shortcuts.xml
موجود است.
موجودی درون خطی برای App Actions
برای برخی از پارامترهای BII، میانبرها را می توان برای هدایت استخراج موجودیت به مجموعه ای از موجودیت های پشتیبانی شده مشخص شده در shortcuts.xml
، که به عنوان موجودی درون خطی شناخته می شود، استفاده کرد. برای جزئیات، موجودی درون خطی را ببینید.
موجودی وب برای اقدامات برنامه
برای برخی از BII ها، می توانید از موجودی وب به عنوان روشی برای تولید URL برای تکمیل استفاده کنید. موجودی وب از وبسایت شما برای کشف نشانیهای وب برای انجام عملیات برنامه استفاده میکند. این ویژگی زمانی بسیار مفید است که شما یک حضور قوی در وب داشته باشید و پیوندهای عمیق درون برنامه شما حول محتوای وب در دسترس عموم سازماندهی شده باشند.
برای جزئیات، به موجودی وب مراجعه کنید.
مقاصد سفارشی
اهداف سفارشی را میتوان در shortcuts.xml
اعلام کرد تا ویژگیهایی را در برنامه شما فعال کند که با BIIهای موجود مطابقت ندارند. در حالی که از نظر عملکرد شبیه به تعریف BII است، اهداف سفارشی به دو ویژگی اضافی در shortcuts.xml
نیاز دارند:
app:queryPatterns
: منبع آرایه ای که الگوهای مختلف پرس و جو را برای یک هدف سفارشی اعلام می کند.android:mimeType
: نوع پارامتر یک intent سفارشی. این فیلد برای BII که نوع پارامتر آن مشخص است، لازم نیست. برای پارامترهای هدف سفارشی، یک نوع معنایی پشتیبانی شده باید اعلام شود.
برای جزئیات بیشتر، به اهداف سفارشی مراجعه کنید.