Shortcuts.xml را ایجاد کنید

هنگامی که عملکرد درون‌برنامه‌ای خود و هدف داخلی (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 در مانیفست برنامه خود اضافه کنید:

1. در فایل مانیفست برنامه خود ( AndroidManifest.xml )، فعالیتی را بیابید که فیلترهای هدف آن روی عملکرد android.intent.action.MAIN و دسته android.intent.category.LAUNCHER تنظیم شده است.

2. با استفاده از یک تگ <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"، و غیره) که به پارامتر BII exercise.name از قابلیت START_EXERCISE متصل شده است. اگر یک گفته کاربر با یک موجود مطابقت داشته باشد، شناسه shortcutId به جای مقدار درخواست خام کاربر به intent ارسال می شود.

  میانبرهای Entity ، ویژگی‌های intent ، shortLabel یا longLabel را تعریف نمی‌کنند و به این ترتیب در سطوح فعال پیشنهاد نمی‌شوند. برای جزئیات، موجودی درون خطی برای اقدامات برنامه را ببینید.

طرح واره قابلیت

جدول زیر طرح اقدامات برنامه را برای عناصر capability در shortcuts.xml توضیح می دهد. هنگام گنجاندن یک برچسب، تمام ویژگی های آن مورد نیاز است مگر اینکه "اختیاری" علامت گذاری شود.

شرح طرحواره قابلیت

این بخش عناصر طرحواره 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 آورده شده است:

برای اطلاعات بیشتر درباره پیکربندی الگوهای 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 استفاده می شود. هنگام گنجاندن یک برچسب، تمام ویژگی های آن مورد نیاز است مگر اینکه "اختیاری" علامت گذاری شود.

شرح طرح میانبر

این بخش عناصر طرح 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 : نام پارامتر BII capability برای مرتبط کردن این میانبر به. برای مثال، 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 که نوع پارامتر آن مشخص است، لازم نیست. برای پارامترهای هدف سفارشی، یک نوع معنایی پشتیبانی شده باید اعلام شود.

برای جزئیات بیشتر، به اهداف سفارشی مراجعه کنید.