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

هنگامی که عملکرد درون‌برنامه‌ای خود و هدف داخلی (BII) مربوطه را برای پیاده‌سازی شناسایی کردید، با تعریف یک عنصر capability در فایل منبع shortcuts.xml ، BII‌هایی را که عملکرد شما پشتیبانی می‌کنند، اعلام کنید. اعلام یک BII به‌عنوان یک capability ، پشتیبانی از آن هدف معنایی را در برنامه شما ثبت می‌کند و انجام درخواست صوتی هدف را با استفاده از Google Assistant فعال می‌کند.

دستیار از پردازش زبان طبیعی برای استخراج پارامترها از درخواست کاربر استفاده می کند. مرجع مقاصد داخلی، فیلدهایی را فهرست می کند که هر BII می تواند از یک درخواست کاربر مرتبط استخراج کند. برای مثال، اگر کاربری قابلیت [ actions.intent.GET_FOOD_OBSERVATION ][] را در برنامه شما با گفتن «Hey Google, Ask ExampleApp برای ناهار جمعه گذشته چه خوردم» فراخوانی کند، «دستیار» پارامترهای BII زیر را از درخواست کاربر استخراج می‌کند. :

• foodObservation.forMeal = "https://schema.googleapis.com/MealTypeLunch"
• foodObservation.startTime = "2024-09-06T00:00:00"
• foodObservation.endTime = "2024-09-06T23:59:59"

دستیار پارامترهای BII را به intent تحقق تعریف شده در capability ارسال می کند. یک یا چند عنصر intent را می توان در قابلیتی تعریف کرد که راه های مختلفی را که کاربر ممکن است یک BII را فراخوانی کند، تطبیق دهد. به عنوان مثال، می توانید یک intent تحقق را تعریف کنید که به هر دو پارامتر BII در مثال بالا نیاز دارد. سپس می‌توانید هدف دومی را تعریف کنید که به یک پارامتر BII نیاز دارد، foodObservation.forMeal .

نمای کلی

شما با استفاده از یک فایل 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.GET_FOOD_OBSERVATION ][]). برای فهرستی از اهداف داخلی پشتیبانی شده، به مرجع هدف داخلی مراجعه کنید.
• app:queryPatterns : یک منبع آرایه رشته ای از پرس و جوهایی که از کاربر برای این هدف انتظار می رود. این ویژگی فقط برای مقاصد سفارشی قابل استفاده است، زیرا BIIها قبلاً شامل مدل‌هایی از روش‌های رایجی است که کاربران وظایفی را که می‌خواهند انجام دهند یا اطلاعاتی را که به دنبال آن هستند بیان می‌کنند.

<قصد>

عنصر intent Android که نحوه انجام درخواست کاربر را با استفاده از عملکرد درون برنامه ای مشخص می کند. توسعه دهندگان ممکن است چندین تگ <intent> را در یک capability ارائه کنند. دستیار با استفاده از اولین <intent> در capability که تمام پارامترهای مورد نیاز برای آن ارائه شده است، تلاش می کند تا یک درخواست کاربر را انجام دهد.

ویژگی ها:

• android:action : نوع Action قصد. پیش‌فرض ACTION_VIEW است.
• android:targetClass : کلاس فعالیت هدف، به عنوان مثال: "com.example.exercise.ExerciseActivity"
• android:targetPackage : بسته حاوی کلاس Activity هدف، به عنوان مثال: "com.example.exercise
• android:data : اگر آن تگ در intent اعلان شده باشد، این فیلد توسط <url-template> بازنویسی می شود.

<url-template>

الگوی ساخت یک URI پیوند عمیق که در دستگاه باز می شود. اگر تمام پارامترهای لازم برای الگو در دسترس باشد، ممکن است الگو با پارامترهای هدف داخلی گسترش یابد. برای نمونه‌هایی از الگوی URL HTTP، به مقاله ویکی‌پدیا در مورد الگوهای URL مراجعه کنید. قالب الگو از مشخصات قالب RFC6570 URI پیروی می کند.

در زیر چند نمونه از مقادیر قالب URL آورده شده است:

برای اطلاعات بیشتر درباره پیکربندی الگوهای URL، به الگوهای URL در حال تکمیل مراجعه کنید.

<اضافی>

داده های اضافی را برای یک intent تعریف می کند. برای App Actions، این فیلد فقط برای فعال کردن [پیش‌زمینه برنامه فراخوانی[] برای یک 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 ، درخواست کاربر را برآورده کند.

<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.START_EXERCISE .

<parameter-binding>

ویژگی اختیاری که shortcut به یک پارامتر واحد از capability App Actions مرتبط می کند. اگر یک parameter-binding برای shortcut تعریف شده باشد، می توان از میانبر برای ارائه موجودی درون خطی به یک پارامتر BII استفاده کرد. برای جزئیات بیشتر، موجودی درون خطی برای اقدامات برنامه را ببینید.

ویژگی ها:

• android:key : نام پارامتر BII capability برای مرتبط کردن این میانبر به. برای مثال exercise.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.START_EXERCISE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

با توجه به نمونه بالا، برای یک درخواست کاربر مانند «Hey Google، یک latte از ExampleApp سفارش دهید»، برنامه یک intent دریافت می‌کند که مؤلفه را فراخوانی می‌کند: targetPackage ، targetClass . مؤلفه یک Extra با key = "exercise" ، value = "Running" دریافت می کند.

استفاده از قالب URL برای لینک های عمیق اندروید

اگر برنامه شما در حال حاضر قادر به مدیریت URL های مرتبط با برنامه است، با پارامترهای پویا، می توانید یک <url-template> را intent ایجاد پیوندهای عمیق اندروید برای تحقق تعریف کنید. نمونه زیر یک <url-template> را تعریف می کند:

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://start{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

با توجه به نمونه بالا، برای درخواست کاربر مانند «Hey Google، یک لاته از ExampleApp سفارش دهید»، برنامه URL تولید شده را دریافت می‌کند: «myapp://start?exercise=Running».

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

مقاصد سفارشی

اهداف سفارشی را می‌توان در shortcuts.xml اعلام کرد تا ویژگی‌هایی را در برنامه شما فعال کند که با BIIهای موجود مطابقت ندارند. در حالی که از نظر عملکرد شبیه به تعریف BII است، اهداف سفارشی به دو ویژگی اضافی در shortcuts.xml نیاز دارند:

• app:queryPatterns : منبع آرایه ای که الگوهای مختلف پرس و جو را برای یک هدف سفارشی اعلام می کند.

• android:mimeType : نوع پارامتر یک intent سفارشی. این فیلد برای BII که نوع پارامتر آن مشخص است، لازم نیست. برای پارامترهای هدف سفارشی، یک نوع معنایی پشتیبانی شده باید اعلام شود.

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

هنگامی که عملکرد درون‌برنامه‌ای خود و هدف داخلی (BII) مربوطه را برای پیاده‌سازی شناسایی کردید، با تعریف یک عنصر capability در فایل منبع shortcuts.xml ، BII‌هایی را که عملکرد شما پشتیبانی می‌کنند، اعلام کنید. اعلام یک BII به‌عنوان یک capability ، پشتیبانی از آن هدف معنایی را در برنامه شما ثبت می‌کند و انجام درخواست صوتی هدف را با استفاده از Google Assistant فعال می‌کند.

دستیار از پردازش زبان طبیعی برای استخراج پارامترها از درخواست کاربر استفاده می کند. مرجع مقاصد داخلی، فیلدهایی را فهرست می کند که هر BII می تواند از یک درخواست کاربر مرتبط استخراج کند. برای مثال، اگر کاربری قابلیت [ actions.intent.GET_FOOD_OBSERVATION ][] را در برنامه شما با گفتن «Hey Google, Ask ExampleApp برای ناهار جمعه گذشته چه خوردم» فراخوانی کند، «دستیار» پارامترهای BII زیر را از درخواست کاربر استخراج می‌کند. :

• foodObservation.forMeal = "https://schema.googleapis.com/MealTypeLunch"
• foodObservation.startTime = "2024-09-06T00:00:00"
• foodObservation.endTime = "2024-09-06T23:59:59"

دستیار پارامترهای BII را به intent تحقق تعریف شده در capability ارسال می کند. یک یا چند عنصر intent را می توان در قابلیتی تعریف کرد که راه های مختلفی را که کاربر ممکن است یک BII را فراخوانی کند، تطبیق دهد. به عنوان مثال، می توانید یک intent تحقق را تعریف کنید که به هر دو پارامتر BII در مثال بالا نیاز دارد. سپس می‌توانید هدف دومی را تعریف کنید که به یک پارامتر BII نیاز دارد، foodObservation.forMeal .

نمای کلی

شما با استفاده از یک فایل 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.GET_FOOD_OBSERVATION ][]). برای فهرستی از اهداف داخلی پشتیبانی شده، به مرجع هدف داخلی مراجعه کنید.
• app:queryPatterns : یک منبع آرایه رشته ای از پرس و جوهایی که از کاربر برای این هدف انتظار می رود. این ویژگی فقط برای مقاصد سفارشی قابل استفاده است، زیرا BIIها قبلاً شامل مدل‌هایی از روش‌های رایجی است که کاربران وظایفی را که می‌خواهند انجام دهند یا اطلاعاتی را که به دنبال آن هستند بیان می‌کنند.

<قصد>

عنصر intent Android که نحوه انجام درخواست کاربر را با استفاده از عملکرد درون برنامه ای مشخص می کند. توسعه دهندگان ممکن است چندین تگ <intent> را در یک capability ارائه کنند. دستیار با استفاده از اولین <intent> در capability که تمام پارامترهای مورد نیاز برای آن ارائه شده است، تلاش می کند تا یک درخواست کاربر را انجام دهد.

ویژگی ها:

• android:action : نوع Action قصد. پیش‌فرض ACTION_VIEW است.
• android:targetClass : کلاس فعالیت هدف، به عنوان مثال: "com.example.exercise.ExerciseActivity"
• android:targetPackage : بسته حاوی کلاس Activity هدف، به عنوان مثال: "com.example.exercise
• android:data : اگر آن تگ در intent اعلان شده باشد، این فیلد توسط <url-template> بازنویسی می شود.

<url-template>

الگوی ساخت یک URI پیوند عمیق که در دستگاه باز می شود. اگر تمام پارامترهای لازم برای الگو در دسترس باشد، ممکن است الگو با پارامترهای هدف داخلی گسترش یابد. برای نمونه‌هایی از الگوی URL HTTP، به مقاله ویکی‌پدیا در مورد الگوهای URL مراجعه کنید. قالب الگو از مشخصات قالب RFC6570 URI پیروی می کند.

در زیر چند نمونه از مقادیر قالب URL آورده شده است:

برای اطلاعات بیشتر درباره پیکربندی الگوهای URL، به الگوهای URL در حال تکمیل مراجعه کنید.

<اضافی>

داده های اضافی را برای یک intent تعریف می کند. برای App Actions، این فیلد فقط برای فعال کردن [پیش‌زمینه برنامه فراخوانی[] برای یک 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 ، درخواست کاربر را برآورده کند.

<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.START_EXERCISE .

<parameter-binding>

ویژگی اختیاری که shortcut به یک پارامتر واحد از capability App Actions مرتبط می کند. اگر یک parameter-binding برای shortcut تعریف شده باشد، می توان از میانبر برای ارائه موجودی درون خطی به یک پارامتر BII استفاده کرد. برای جزئیات بیشتر، موجودی درون خطی برای اقدامات برنامه را ببینید.

ویژگی ها:

• android:key : نام پارامتر BII capability برای مرتبط کردن این میانبر به. برای مثال exercise.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 ، مقصد برنامه را با استفاده از پیوندهای عمیق اندروید راه اندازی کنید. اگر ناوبری برنامه شما از قبل به پیوندهای عمیق متکی باشد ، این روش مفید است.

• داده های هدف : شما می توانید URI برآورده شده را در Android: intent android:data ارائه دهید. اگر این برچسب نیز در intent تعریف شود ، این قسمت توسط <url-template> داده می شود.

داده های پارامتر و تطبیق

به طور پیش فرض ، دستیار پارامترهای BII استخراج شده از پرس و جو کاربر را به عنوان داده های extra از intent اندرویدی که در capability تعریف شده است ، به برنامه شما ارسال می کند.

از طرف دیگر ، می توانید یک برچسب <url-template> را در capability که شامل متغیرها برای پارامترهای پویا است ، اعلام کنید. این الگوی با استفاده از URL Links Links ، یک طرح سفارشی یا یک URL مبتنی بر قصد ، به یکی از فعالیت های اندرویدی شما نقشه می کند.

با استفاده از موارد اضافی

مثال زیر یک هدف صریح تعریف شده برای تحقق capability را نشان می دهد:

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

با توجه به نمونه فوق ، برای یک پرس و جو کاربر مانند "سلام گوگل ، سفارش یک لاته از Exampleapp" ، این برنامه intent دریافت می کند که از این مؤلفه استفاده می کند: targetPackage ، targetClass . مؤلفه با key = "exercise" ، value = "Running" دریافت می کند.

با استفاده از یک الگوی URL برای پیوندهای عمیق اندرویدی

اگر برنامه شما از قبل قادر به اداره URL های مرتبط با برنامه ، با پارامترهای پویا است ، می توانید یک <url-template> را در intent تولید پیوندهای عمیق اندرویدی برای تحقق تعریف کنید. نمونه زیر یک <url-template> را تعریف می کند:

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://start{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

با توجه به نمونه فوق ، برای پرس و جو کاربر مانند ، "سلام گوگل ، یک لاته را از Exampleapp سفارش دهید" ، برنامه URL تولید شده را دریافت می کند: "MyApp: // شروع؟ ورزش = اجرا".

برای نقشه برداری از پارامتر BII به موقعیتی در URL خود ، از android:name Attribute برچسب <parameter> استفاده می کنید. این ویژگی مربوط به android:key در الگوی URL که می خواهید با اطلاعات کاربر جایگزین کنید. android:key باید در <url-template> شما موجود باشد و توسط بریس های فرفری ( {} ) محصور شود.

مقادیر پارامتر شمارش شده

برخی از پارامترهای BII مقادیر ذکر شده را به هدف تحقق شما ارائه می دهند ، به عنوان مثال ، مقادیر متن پشتیبانی شده از bii RECORD_FOOD_OBSERVATION . برای این پارامترها ، دستیار با پرس و جو کاربر ("صبحانه") با یک موجودی که ارزش sameAs با URL Schema 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"

ویژگی ها

ویژگی های اقدامات برنامه زیر در shortcuts.xml در دسترس است.

موجودی درون خطی برای اقدامات برنامه

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

اهداف سفارشی

اهداف سفارشی را می توان در shortcuts.xml برای فعال کردن ویژگی های برنامه در برنامه شما که با BII های موجود مطابقت ندارند ، اعلام کنند. در حالی که از نظر عملکردی با یک تعریف BII مشابه است ، اهداف سفارشی به دو ویژگی اضافی در shortcuts.xml نیاز دارند. xml:

• app:queryPatterns : منبع آرایه ای که الگوهای مختلف پرس و جو را برای یک هدف سفارشی اعلام می کند.

• android:mimeType : نوع پارامتر یک هدف سفارشی. این زمینه برای BIIS ، جایی که نوع پارامتر شناخته شده است ، لازم نیست. برای پارامترهای قصد سفارشی ، یک نوع معنایی پشتیبانی شده باید اعلام شود.

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

پس از شناسایی عملکرد درون برنامه و هدف داخلی (BII) برای پیاده سازی ، BII را با تعریف یک عنصر capability در یک پرونده منبع میانبر. shortcuts.xml پشتیبانی می کنید. اعلام BII به عنوان یک capability پشتیبانی از آن قصد معنایی در برنامه شما پشتیبانی می کند و امکان انجام پرس و جو صوتی را با استفاده از دستیار Google امکان پذیر می کند.

دستیار از پردازش زبان طبیعی برای استخراج پارامترها از پرس و جو کاربر استفاده می کند. Reference Intents Intents زمینه هایی را که هر BII قادر به استخراج از یک پرس و جو کاربر مرتبط است ، لیست می کند. به عنوان مثال ، اگر یک کاربر با گفتن " actions.intent.GET_FOOD_OBSERVATION ] [] در برنامه شما با گفتن " سلام گوگل ، از امتحان بپرسید که من جمعه گذشته برای ناهار چه خوردم " ، دستیار پارامترهای BII زیر را از درخواست کاربر استخراج می کند. :

• foodObservation.forMeal = "https://schema.googleapis.com/mealtypelunch"
• foodObservation.startTime = "2024-09-06T00: 00: 00"
• foodObservation.endTime = "2024-09-06T23: 59: 59"

دستیار پارامترهای BII را به intent تحقق تعریف شده در capability منتقل می کند. یک یا چند عنصر intent را می توان در یک قابلیت برای قرار دادن روش های مختلف یک کاربر که ممکن است از یک BII استفاده کند ، تعریف کند. به عنوان مثال ، شما می توانید یک intent تحقق را تعریف کنید که در مثال فوق به هر دو پارامتر BII نیاز دارد. سپس می توانید یک هدف دوم را تعریف کنید که به یک پارامتر BII منفرد ، foodObservation.forMeal نیاز داشته باشد ، که گزارش های مربوط به همه وعده های غذایی در یک روز خاص ، مانند "سلام گوگل ، از Exampleapp بپرسید که من برای ناهار چه خوردم."

نمای کلی

شما اقدامات برنامه را با استفاده از یک پرونده shortcuts.xml که در فهرست برنامه برنامه خود قرار داده شده است res/xml پیکربندی می کنید ، و سپس یک مرجع به shortcuts.xml در برنامه خود ایجاد می کنید. با دنبال کردن این مراحل ، به میانبر shortcuts.xml در برنامه خود مانیفست اضافه کنید:

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

2. با استفاده از یک <meta-data> shortcuts.xml Activity که فیلترهای قصد برای هر دو MAIN و LAUNCHER 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 شما لازم است تا هنگام تعریف قابلیت های اقدامات برنامه در shortcuts.xml از خطاهای تدوین جلوگیری کنید. برای جزئیات بیشتر ، شروع به کار با Android Jetpack کنید.

میانبرهای استاتیک

هنگام تعریف capability خود ، می توانید عناصر shortcut استاتیک را در shortcuts.xml اعلام کنید تا عملکرد توانایی را گسترش دهید. هنگام بارگذاری نسخه ای در کنسول Google Play ، میانبرهای استاتیک توسط دستیار مصرف می شوند. از آنجا که میانبرهای استاتیک فقط با ایجاد نسخه های جدید می توانند ایجاد و به روز شوند ، آنها برای برجسته کردن فعالیت ها و محتوای مشترک در برنامه شما مفید هستند.

شما می توانید عملکرد برنامه های زیر را با میانبرهای استاتیک فعال کنید:

• میانبرهای قابلیت . میانبرهایی ایجاد کنید که نمونه ای از capability شما را شامل می شود که حاوی مقادیر پارامتر intent از پیش تعریف شده است. به عنوان مثال ، شما می توانید میانبر برنامه "Start A Run" را اعلام کنید که از قابلیت BII START_EXERCISE در برنامه تناسب اندام شما فراخوانی می کند.

  این میانبرها حاوی ویژگی های intent ، shortLabel بلند و longLabel هستند و باعث می شوند که آنها به عنوان تراشه در سطوح فعال مانند دستیار یا هنگام فشار طولانی یک نماد برنامه در پرتاب های اندرویدی ، به عنوان تراشه ها پیشنهاد و تحقق بخشند. یک میانبر اکشن همچنین می تواند به عنوان یک میانبر موجودیت ، که در زیر شرح داده شده است ، با پیوند آن با یک capability با استفاده از یک برچسب <capability-binding> ارائه شود.

• میانبرهای موجودیت . میانبرهای موجودی لیستی از مقادیر پارامتر پشتیبانی شده برای تحقق پرس و جو از یک capability را ارائه می دهند. به عنوان مثال ، یک میانبر موجودیت با لیستی از انواع تمرینات ("پیاده روی" ، "اجرا" ، و غیره) که به exercise.name است. پارامتر BII از قابلیت START_EXERCISE . اگر یک گفتار کاربر با یک نهاد مطابقت داشته باشد ، شناسه shortcutId به جای مقدار پرس و جو کاربر خام به قصد منتقل می شود.

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

طرح

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

توصیف طرحواره

در این بخش عناصر طرحواره ای capability توضیح داده شده است.

<Suitability>

capability که برنامه برنامه را تعیین می کند ، برنامه شما را پشتیبانی می کند. هر عنصر <capability> در پرونده shortcuts.xml شما. xml باید حداقل یک <intent> را برای انجام تحقق عمل فراهم کند.

ویژگی ها:

• android:name : شناسه اکشن قصد داخلی (به عنوان مثال ، [ actions.intent.GET_FOOD_OBSERVATION ] []). برای لیستی از اهداف داخلی پشتیبانی شده ، به مرجع داخلی داخلی مراجعه کنید.
• app:queryPatterns : یک منبع آرایه رشته ای از نمایش داده شدگان انتظار می رود از کاربر برای این هدف. این ویژگی فقط در مورد اهداف سفارشی کاربرد دارد ، زیرا BII در حال حاضر شامل مدل هایی از روش های متداول است که کاربران وظایفی را که می خواهند انجام دهند یا اطلاعات مورد نظر خود را بیان می کنند.

<tatent>

Android intent Element تعریف می کند که چگونه یک پرس و جو کاربر باید با استفاده از قابلیت های درون برنامه ای انجام شود. توسعه دهندگان ممکن است برچسب های چندگانه <intent> را در یک capability ارائه دهند. دستیار تلاش می کند تا با استفاده از اولین <intent> در یک capability استفاده از اولین پارامترهای مورد نیاز ، پرس و جو کاربر را انجام دهد.

ویژگی ها:

• android:action : نوع Action هدف. پیش فرض به ACTION_VIEW .
• android:targetClass : کلاس فعالیت هدف ، به عنوان مثال: "com.example.exercise.ExerciseActivity"
• android:targetPackage : بسته حاوی کلاس فعالیت هدف ، به عنوان مثال: "com.example.exercise
• android:data : اگر این برچسب در intent اعلام شود ، این قسمت توسط <url-template> رونویسی می شود.

<url-template>

الگوی ساخت URI پیوند عمیق برای باز شدن بر روی دستگاه. اگر تمام پارامترهای مورد نیاز برای الگوی موجود باشد ، این الگوی ممکن است با پارامترهای داخلی داخلی گسترش یابد. برای نمونه هایی از الگوی URL HTTP ، به مقاله ویکی پدیا در مورد الگوهای URL مراجعه کنید. قالب الگوی از مشخصات الگوی URI RFC6570 پیروی می کند.

موارد زیر چند نمونه از مقادیر الگوی URL است:

برای اطلاعات بیشتر در مورد پیکربندی الگوهای URL ، به الگوهای URL در تحقق مراجعه کنید.

<اضافی>

داده های اضافی را برای یک intent تعریف می کند. برای اقدامات برنامه ، از این قسمت فقط برای فعال کردن [فراخوانی برنامه پیش زمینه] [] برای capability استفاده می شود.

<Parameter>

یک پارامتر BII را به مقادیر پارامتر قصد نقشه می کند. برای اطلاعات بیشتر ، به داده های پارامتر و تطبیق مراجعه کنید.

ویژگی ها:

• android:name : نام پارامتر BII برای ارتباط با این پارامتر intent . این نام باید یک میدان سطح برگ از پارامتر BII باشد (به عنوان مثال ، foodObservation.aboutFood.name ).
• android:key : کلید تعریف شده توسط توسعه دهنده از یک مقدار پارامتر BII. به عنوان مثال ، ممکن است contact_name برای message.recipient.name bii تعریف کنید.
• android:mimeType : Mimetype از پارامتر ، مانند text/* . این قسمت فقط برای پارامترهای اهداف سفارشی مورد نیاز است.
• android:required : اعلام می کند که آیا پرس و جو کاربر برای استفاده از این هدف برای تحقق نیاز به این پارامتر دارد یا خیر. اگر پارامتر در دسترس نباشد ، دستیار تلاش می کند تا با استفاده از intent بعدی که برای capability تعریف شده است ، پرس و جو کاربر را انجام دهد.

<میانبر-تحقق>

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

<Parameter> (برای <shortcut-fulfillment> >)

ویژگی اختیاری که یک پارامتر BII منفرد را برای تحقق میانبر موجودی درون خطی نقشه می کند. برای جزئیات بیشتر ، با استفاده از اهداف میانبر به تحقق مراجعه کنید.

صفت:

• android:name : نام پارامتر BII برای همبستگی با تحقق میانبر موجودی درون خطی. این نام باید یک میدان سطح برگ از پارامتر BII باشد (به عنوان مثال ، menuItem.name ).

<slice>

دستیار را قادر می سازد تا نتیجه یک پرس و جو را مطابق با این capability به عنوان یک برش اندرویدی تعبیه کند. برای جزئیات بیشتر ، به ادغام اقدامات برنامه با برش های اندرویدی مراجعه کنید.

طرح میانبر

در جدول زیر ویژگی های عناصر shortcut که برای فعال کردن عملکرد برنامه های برنامه استفاده می شود ، شرح می دهد. در هنگام شامل یک برچسب ، تمام ویژگی های آن مورد نیاز است مگر اینکه "اختیاری" مشخص شود.

توضیحات طرحواره میانبر

در این بخش عناصر شمای shortcut توضیح داده شده است.

<میانبر>

Android <shortcut> در shortcuts.xml تعریف شده است. xml با ویژگی های خاصی که برای اقدامات برنامه مرتبط هستند. مقادیر رشته ای برای زمینه های shortcutShortLabel و shortcutLongLabel از طریق منابع رشته APK ارجاع می شوند.

ویژگی ها:

• android:shortcutId : شناسه این میانبر.
• android:shortcutShortLabel : منبع رشته ای که یک عبارت میانبر مختصر را نشان می دهد. به عنوان مثال ، "@string/callDavidShort" نشان دهنده ارزش "تماس با دیوید" است.
• android:shortcutLongLabel : منبع رشته ای که یک عبارت میانبر بلند را نشان می دهد. به عنوان مثال ، "@string/callDavidLong" نشان دهنده مقدار "تماس صوتی به دیوید" است.

<tatent>

هدف اندرویدی مرتبط با این میانبر. این intent هنگامی اجرا می شود که کاربر این میانبر را با استفاده از Voice یا Touch راه اندازی کند.

ویژگی های هدف shortcut با ویژگی های intent capability یکسان هستند.

<tobility-binding>

میانبر با capability اقدامات برنامه را به هم shortcut است. اضافه کردن این عنصر به shortcut آن را برای تحقق صدا با استفاده از Assistant امکان پذیر می کند.

ویژگی ها:

• android:key : android:name ویژگی capability این shortcut به آن محدود شده است. به عنوان مثال ، actions.intent.START_EXERCISE .

<-parameter-binding>

ویژگی اختیاری که shortcut به یک پارامتر واحد از capability اقدامات برنامه مرتبط می کند. اگر یک parameter-binding برای shortcut تعریف شده باشد ، می توان از میانبر برای تهیه یک موجودی موجودی درون خطی به یک پارامتر BII استفاده کرد. برای اطلاعات بیشتر ، برای اقدامات برنامه به موجودی Inline مراجعه کنید.

ویژگی ها:

• android:key : نام پارامتر capability BII برای مرتبط کردن این میانبر به. به عنوان مثال ، exercise.name .
• android:value : مقدار entity . این می تواند یک entity واحد یا یک لیست منابع باشد.

<اضافی>

داده های بسته نرم افزاری extra برای میانبر. SAMEAS تنها داده های مربوط به عناصر shortcut App Actions Action است. URL SAMEAS به یک صفحه وب مرجع اشاره دارد که به طور واضح موجودیت را مشخص می کند. برای مشخص کردن مقدار enum در صورتی که و فقط اگر نوع پارامتر هدف زیر گروه schema.org/enumeration باشد استفاده می شود. برای زمینه های پارامتر مورد نیاز است که انواع آنها زیرگروه های schema.org/Enumeration است (برای مثال: MealTypeBreakfast ).

ویژگی ها:

• android:key : مقدار پشتیبانی شده برای اقدامات برنامه: sameAs
• android:value : مقدار URL sameAs

برای اطلاعات بیشتر ، به مقادیر پارامتر شمارش شده مطابق مراجعه کنید.

گزینه های تحقق قصد

شما عناصر intent در یک <capability> تعریف می کنید تا اعلام کنید که چگونه دستیار به دستورات صوتی کاربر پاسخ می دهد یا با این توانایی مطابقت دارد. روش های مختلفی برای پیکربندی نحوه راه intent یک مقصد تحقق در برنامه شما وجود دارد ، بسته به نحوه ساخت ناوبری برنامه شما.

گزینه های تحقق زیر در دسترس است:

• اهداف صریح : با تعریف ویژگی های targetClass و targetPackage برای intent یک مؤلفه برنامه خاص را راه اندازی کنید. این روش تحقق اقدامات برنامه پیشنهادی است.

• پیوندهای عمیق : با تعریف یک برچسب <url-template> در عنصر intent ، مقصد برنامه را با استفاده از پیوندهای عمیق اندروید راه اندازی کنید. اگر ناوبری برنامه شما از قبل به پیوندهای عمیق متکی باشد ، این روش مفید است.

• داده های هدف : شما می توانید URI برآورده شده را در Android: intent android:data ارائه دهید. اگر این برچسب نیز در intent تعریف شود ، این قسمت توسط <url-template> داده می شود.

داده های پارامتر و تطبیق

به طور پیش فرض ، دستیار پارامترهای BII استخراج شده از پرس و جو کاربر را به عنوان داده های extra از intent اندرویدی که در capability تعریف شده است ، به برنامه شما ارسال می کند.

از طرف دیگر ، می توانید یک برچسب <url-template> را در capability که شامل متغیرها برای پارامترهای پویا است ، اعلام کنید. این الگوی با استفاده از URL Links Links ، یک طرح سفارشی یا یک URL مبتنی بر قصد ، به یکی از فعالیت های اندرویدی شما نقشه می کند.

با استفاده از موارد اضافی

مثال زیر یک هدف صریح تعریف شده برای تحقق capability را نشان می دهد:

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

با توجه به نمونه فوق ، برای یک پرس و جو کاربر مانند "سلام گوگل ، سفارش یک لاته از Exampleapp" ، این برنامه intent دریافت می کند که از این مؤلفه استفاده می کند: targetPackage ، targetClass . مؤلفه با key = "exercise" ، value = "Running" دریافت می کند.

با استفاده از یک الگوی URL برای پیوندهای عمیق اندرویدی

اگر برنامه شما از قبل قادر به اداره URL های مرتبط با برنامه ، با پارامترهای پویا است ، می توانید یک <url-template> را در intent تولید پیوندهای عمیق اندرویدی برای تحقق تعریف کنید. نمونه زیر یک <url-template> را تعریف می کند:

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://start{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

با توجه به نمونه فوق ، برای پرس و جو کاربر مانند ، "سلام گوگل ، یک لاته را از Exampleapp سفارش دهید" ، برنامه URL تولید شده را دریافت می کند: "MyApp: // شروع؟ ورزش = اجرا".

برای نقشه برداری از پارامتر BII به موقعیتی در URL خود ، از android:name Attribute برچسب <parameter> استفاده می کنید. این ویژگی مربوط به android:key در الگوی URL که می خواهید با اطلاعات کاربر جایگزین کنید. android:key باید در <url-template> شما موجود باشد و توسط بریس های فرفری ( {} ) محصور شود.

مقادیر پارامتر شمارش شده

برخی از پارامترهای BII مقادیر ذکر شده را به هدف تحقق شما ارائه می دهند ، به عنوان مثال ، مقادیر متن پشتیبانی شده از bii RECORD_FOOD_OBSERVATION . برای این پارامترها ، دستیار با پرس و جو کاربر ("صبحانه") با یک موجودی که ارزش sameAs با URL Schema 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"

ویژگی ها

ویژگی های اقدامات برنامه زیر در shortcuts.xml در دسترس است.

موجودی درون خطی برای اقدامات برنامه

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

اهداف سفارشی

اهداف سفارشی را می توان در shortcuts.xml برای فعال کردن ویژگی های برنامه در برنامه شما که با BII های موجود مطابقت ندارند ، اعلام کنند. در حالی که از نظر عملکردی با یک تعریف BII مشابه است ، اهداف سفارشی به دو ویژگی اضافی در shortcuts.xml نیاز دارند. xml:

• app:queryPatterns : منبع آرایه ای که الگوهای مختلف پرس و جو را برای یک هدف سفارشی اعلام می کند.

• android:mimeType : نوع پارامتر یک هدف سفارشی. این زمینه برای BIIS ، جایی که نوع پارامتر شناخته شده است ، لازم نیست. برای پارامترهای قصد سفارشی ، یک نوع معنایی پشتیبانی شده باید اعلام شود.

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

پس از شناسایی عملکرد درون برنامه و هدف داخلی (BII) برای پیاده سازی ، BII را با تعریف یک عنصر capability در یک پرونده منبع میانبر. shortcuts.xml پشتیبانی می کنید. اعلام BII به عنوان یک capability پشتیبانی از آن قصد معنایی در برنامه شما پشتیبانی می کند و امکان انجام پرس و جو صوتی را با استفاده از دستیار Google امکان پذیر می کند.

دستیار از پردازش زبان طبیعی برای استخراج پارامترها از پرس و جو کاربر استفاده می کند. Reference Intents Intents زمینه هایی را که هر BII قادر به استخراج از یک پرس و جو کاربر مرتبط است ، لیست می کند. به عنوان مثال ، اگر یک کاربر با گفتن " actions.intent.GET_FOOD_OBSERVATION ] [] در برنامه شما با گفتن " سلام گوگل ، از امتحان بپرسید که من جمعه گذشته برای ناهار چه خوردم " ، دستیار پارامترهای BII زیر را از درخواست کاربر استخراج می کند. :

• foodObservation.forMeal = "https://schema.googleapis.com/mealtypelunch"
• foodObservation.startTime = "2024-09-06T00: 00: 00"
• foodObservation.endTime = "2024-09-06T23: 59: 59"

دستیار پارامترهای BII را به intent تحقق تعریف شده در capability منتقل می کند. یک یا چند عنصر intent را می توان در یک قابلیت برای قرار دادن روش های مختلف یک کاربر که ممکن است از یک BII استفاده کند ، تعریف کند. به عنوان مثال ، شما می توانید یک intent تحقق را تعریف کنید که در مثال فوق به هر دو پارامتر BII نیاز دارد. سپس می توانید یک هدف دوم را تعریف کنید که به یک پارامتر BII منفرد ، foodObservation.forMeal نیاز داشته باشد ، که گزارش های مربوط به همه وعده های غذایی در یک روز خاص ، مانند "سلام گوگل ، از Exampleapp بپرسید که من برای ناهار چه خوردم."

نمای کلی

شما اقدامات برنامه را با استفاده از یک پرونده shortcuts.xml که در فهرست برنامه برنامه خود قرار داده شده است res/xml پیکربندی می کنید ، و سپس یک مرجع به shortcuts.xml در برنامه خود ایجاد می کنید. با دنبال کردن این مراحل ، به میانبر shortcuts.xml در برنامه خود مانیفست اضافه کنید:

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

2. با استفاده از یک <meta-data> shortcuts.xml Activity که فیلترهای قصد برای هر دو MAIN و LAUNCHER 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 شما لازم است تا هنگام تعریف قابلیت های اقدامات برنامه در shortcuts.xml از خطاهای تدوین جلوگیری کنید. برای جزئیات بیشتر ، شروع به کار با Android Jetpack کنید.

میانبرهای استاتیک

هنگام تعریف capability خود ، می توانید عناصر shortcut استاتیک را در shortcuts.xml اعلام کنید تا عملکرد توانایی را گسترش دهید. هنگام بارگذاری نسخه ای در کنسول Google Play ، میانبرهای استاتیک توسط دستیار مصرف می شوند. از آنجا که میانبرهای استاتیک فقط با ایجاد نسخه های جدید می توانند ایجاد و به روز شوند ، آنها برای برجسته کردن فعالیت ها و محتوای مشترک در برنامه شما مفید هستند.

شما می توانید عملکرد برنامه های زیر را با میانبرهای استاتیک فعال کنید:

• میانبرهای قابلیت . میانبرهایی ایجاد کنید که نمونه ای از capability شما را شامل می شود که حاوی مقادیر پارامتر intent از پیش تعریف شده است. به عنوان مثال ، شما می توانید میانبر برنامه "Start A Run" را اعلام کنید که از قابلیت BII START_EXERCISE در برنامه تناسب اندام شما فراخوانی می کند.

  این میانبرها حاوی ویژگی های intent ، shortLabel بلند و longLabel هستند و باعث می شوند که آنها به عنوان تراشه در سطوح فعال مانند دستیار یا هنگام فشار طولانی یک نماد برنامه در پرتاب های اندرویدی ، به عنوان تراشه ها پیشنهاد و تحقق بخشند. یک میانبر اکشن همچنین می تواند به عنوان یک میانبر موجودیت ، که در زیر شرح داده شده است ، با پیوند آن با یک capability با استفاده از یک برچسب <capability-binding> ارائه شود.

• میانبرهای موجودیت . میانبرهای موجودی لیستی از مقادیر پارامتر پشتیبانی شده برای تحقق پرس و جو از یک capability را ارائه می دهند. به عنوان مثال ، یک میانبر موجودیت با لیستی از انواع تمرینات ("پیاده روی" ، "اجرا" ، و غیره) که به exercise.name است. پارامتر BII از قابلیت START_EXERCISE . اگر یک گفتار کاربر با یک نهاد مطابقت داشته باشد ، شناسه shortcutId به جای مقدار پرس و جو کاربر خام به قصد منتقل می شود.

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

طرح

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

توصیف طرحواره

در این بخش عناصر طرحواره ای capability توضیح داده شده است.

<Suitability>

capability که برنامه برنامه را تعیین می کند ، برنامه شما را پشتیبانی می کند. هر عنصر <capability> در پرونده shortcuts.xml شما. xml باید حداقل یک <intent> را برای انجام تحقق عمل فراهم کند.

ویژگی ها:

• android:name : شناسه اکشن قصد داخلی (به عنوان مثال ، [ actions.intent.GET_FOOD_OBSERVATION ] []). برای لیستی از اهداف داخلی پشتیبانی شده ، به مرجع داخلی داخلی مراجعه کنید.
• app:queryPatterns : یک منبع آرایه رشته ای از نمایش داده شدگان انتظار می رود از کاربر برای این هدف. این ویژگی فقط در مورد اهداف سفارشی کاربرد دارد ، زیرا BII در حال حاضر شامل مدل هایی از روش های متداول است که کاربران وظایفی را که می خواهند انجام دهند یا اطلاعات مورد نظر خود را بیان می کنند.

<tatent>

Android intent Element تعریف می کند که چگونه یک پرس و جو کاربر باید با استفاده از قابلیت های درون برنامه ای انجام شود. توسعه دهندگان ممکن است برچسب های چندگانه <intent> را در یک capability ارائه دهند. دستیار تلاش می کند تا با استفاده از اولین <intent> در یک capability استفاده از اولین پارامترهای مورد نیاز ، پرس و جو کاربر را انجام دهد.

ویژگی ها:

• android:action : نوع Action هدف. پیش فرض به ACTION_VIEW .
• android:targetClass : کلاس فعالیت هدف ، به عنوان مثال: "com.example.exercise.ExerciseActivity"
• android:targetPackage : بسته حاوی کلاس فعالیت هدف ، به عنوان مثال: "com.example.exercise
• android:data : اگر این برچسب در intent اعلام شود ، این قسمت توسط <url-template> رونویسی می شود.

<url-template>

الگوی ساخت URI پیوند عمیق برای باز شدن بر روی دستگاه. اگر تمام پارامترهای مورد نیاز برای الگوی موجود باشد ، این الگوی ممکن است با پارامترهای داخلی داخلی گسترش یابد. برای نمونه هایی از الگوی URL HTTP ، به مقاله ویکی پدیا در مورد الگوهای URL مراجعه کنید. قالب الگوی از مشخصات الگوی URI RFC6570 پیروی می کند.

موارد زیر چند نمونه از مقادیر الگوی URL است:

برای اطلاعات بیشتر در مورد پیکربندی الگوهای URL ، به الگوهای URL در تحقق مراجعه کنید.

<اضافی>

داده های اضافی را برای یک intent تعریف می کند. برای اقدامات برنامه ، از این قسمت فقط برای فعال کردن [فراخوانی برنامه پیش زمینه] [] برای capability استفاده می شود.

<Parameter>

یک پارامتر BII را به مقادیر پارامتر قصد نقشه می کند. برای اطلاعات بیشتر ، به داده های پارامتر و تطبیق مراجعه کنید.

ویژگی ها:

• android:name : نام پارامتر BII برای ارتباط با این پارامتر intent . این نام باید یک میدان سطح برگ از پارامتر BII باشد (به عنوان مثال ، foodObservation.aboutFood.name ).
• android:key : کلید تعریف شده توسط توسعه دهنده از یک مقدار پارامتر BII. به عنوان مثال ، ممکن است contact_name برای message.recipient.name bii تعریف کنید.
• android:mimeType : Mimetype از پارامتر ، مانند text/* . این قسمت فقط برای پارامترهای اهداف سفارشی مورد نیاز است.
• android:required : اعلام می کند که آیا پرس و جو کاربر برای استفاده از این هدف برای تحقق نیاز به این پارامتر دارد یا خیر. اگر پارامتر در دسترس نباشد ، دستیار تلاش می کند تا با استفاده از intent بعدی که برای capability تعریف شده است ، پرس و جو کاربر را انجام دهد.

<میانبر-تحقق>

Specifies that an intent defined in an inline inventory shortcut for a specified parameter be used for fulfillment. For details, see Fulfillment using shortcut intents .

<parameter> (for <shortcut-fulfillment> )

Optional attribute that maps a single BII parameter to inline inventory shortcut fulfillment. For details, see Fulfillment using shortcut intents .

صفت:

• android:name : Name of the BII parameter to associate to inline inventory shortcut fulfillment. The name should be a leaf-level field of the BII parameter (for example, menuItem.name ).

<slice>

Enables Assistant to embed the result of a query matching this capability as an Android Slice. For details, see Integrate App Actions with Android Slices .

Shortcut schema

The following table describes attributes of shortcut elements that are used to enable App Actions functionality. When including a tag, all of its attributes are required unless marked "optional".

Shortcut schema description

This section describes the shortcut schema elements.

<shortcut>

An Android <shortcut> defined in shortcuts.xml with certain attributes that are relevant for App Actions. String values for the shortcutShortLabel and shortcutLongLabel fields are referenced via the APK's string resources .

ویژگی ها:

• android:shortcutId : Identifier for this shortcut.
• android:shortcutShortLabel : String resource representing a brief shortcut phrase. For example, "@string/callDavidShort" representing the value "Call David."
• android:shortcutLongLabel : String resource representing a long shortcut phrase. For example, "@string/callDavidLong" representing the value "Make an audio call to David."

<intent>

Android intent associated to this shortcut. This intent is executed when a user launches this shortcut using voice or touch.

shortcut intent attributes are identical to capability intent attributes.

<capability-binding>

Associates a shortcut to an App Actions capability . Adding this element to a shortcut enables it for voice fulfillment using Assistant .

ویژگی ها:

• android:key : The android:name attribute of the capability this shortcut is bound to. For example, actions.intent.START_EXERCISE .

<parameter-binding>

Optional attribute that associates a shortcut to a single parameter of an App Actions capability . If a parameter-binding is defined for a shortcut , the shortcut can be used to provide an inline inventory entity to a BII parameter. For more details, see Inline inventory for App Actions .

ویژگی ها:

• android:key : The name of the capability BII parameter to associate this shortcut to. For example, exercise.name .
• android:value : the entity value. This can be a single entity or a resource list.

<extra>

The extra bundle data for the shortcut. sameAs is the only data relevant to App Actions shortcut elements. The sameAs URL refers to a reference web page that unambiguously identifies the entity. Used to specify an enum value if and only if the intent parameter type is a subtype of schema.org/Enumeration . It is required for parameter fields whose types are subtypes of schema.org/Enumeration (for example: MealTypeBreakfast ).

ویژگی ها:

• android:key : The supported value for App Actions is: sameAs
• android:value : The sameAs URL value

For more details, see Matching enumerated parameter values .

Intent fulfillment options

You define intent elements within a <capability> to declare how Assistant responds to, or fulfills, user voice commands that match that capability. There are several ways to configure how an intent launches a fulfillment destination in your app, depending on how your app navigation is structured.

The following fulfillment options are available:

• Explicit intents : Launch a specific app component by defining the targetClass and targetPackage attributes for the intent . This is the recommended App Actions fulfillment method.

• Deep links : Launch app destinations using Android deep links by defining a <url-template> tag within the intent element. This method is useful if your app navigation already relies on deep links.

• Intent data : You can provide a fulfillment URI in the intent android:data attribute. This field is overwritten by <url-template> data if that tag is also defined within the intent .

Parameter data and matching

By default, Assistant sends BII parameters extracted from the user query to your app as extra data of the Android intent defined in the capability .

Alternately, you can declare a <url-template> tag in the capability that contains placeholders for dynamic parameters. This template maps to one of your Android activities, using an App Links URL , a custom scheme, or an Intent-based URL .

Using intent Extras

The following example demonstrates an explicit intent defined for a capability fulfillment:

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

Given the above sample, for a user query like, "Hey Google, order a latte from ExampleApp," the app receives an intent that invokes the component: targetPackage , targetClass . The component receives an Extra with key = "exercise" , value = "Running" .

Using a URL template for Android deep links

If your app is already able to handle app-linked URLs, with dynamic parameters, you can define a <url-template> in the intent to generate Android deep links for fulfillment. The following sample defines a <url-template> :

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://start{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

Given the above sample, for a user query like, “Hey Google, order a latte from ExampleApp," the app receives the generated URL: "myapp://start?exercise=Running".

To map the BII parameter to a position in your URL, you use the android:name attribute of the <parameter> tag. This attribute corresponds to the android:key value in the URL template that you want to substitute with information from the user. The android:key value must be present in your <url-template> and enclosed by curly braces ( {} ).

Match enumerated parameter values

Some BII parameters provide enumerated values to your fulfillment intent, for example, the supported text values of the RECORD_FOOD_OBSERVATION BII. For these parameters, Assistant matches the user's query ("Breakfast") to an entity whose sameAs value matches the enum schema URL ( https://schema.googleapis.com/MealTypeBreakfast ). To associate enum values for a supported entity , you declare a sameAs association in your shortcut . The following sample demonstrates a sameAs association for an inline entity shortcut:

<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>

In the above example, if the RECORD_FOOD_OBSERVATION capability triggers a match for the "breakfast" meal type, the following Extra is sent with the fulfillment intent :

• key = "for_meal"
• value = "meal_breakfast"

ویژگی ها

The following App Actions features are available in shortcuts.xml .

Inline inventory for App Actions

For some BII parameters, shortcuts can be used to guide entity extraction to a set of supported entities specified in shortcuts.xml , known as inline inventory. For details, see Inline inventory .

Custom intents

Custom intents can be declared in shortcuts.xml to voice enable features in your app that don't match available BIIs. While similar in functionality to a BII definition, custom intents require two additional attributes in shortcuts.xml :

• app:queryPatterns : Array resource that declares the different query patterns for a custom intent.

• android:mimeType : Parameter type of a custom intent. This field is not required for BIIs, where the parameter type is known. For custom intent parameters, a supported semantic type must be declared.

For more details, see Custom intents .