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

تگ Shortcuts.xml موجود در صفات
<capability> <shortcuts>

android:name

app:queryPatterns (فقط برای اهداف سفارشی قابل استفاده است)

<intent> <capability>

android:action (اختیاری)

android:targetClass (اختیاری)

android:targetPackage (اختیاری)

android:data (اختیاری)

<url-template> <intent>

android:value

<extra> <intent>

android:key

android:value

فقط برای فراخوانی برنامه پیش زمینه قابل اجرا است

<parameter> <intent>

android:name

android:key

android:mimeType (فقط برای اهداف سفارشی قابل استفاده است)

android:required (اختیاری)

app:shortcutMatchRequired (اختیاری)

<shortcut-fulfillment> <capability> فقط برای موجودی درون خطی قابل استفاده است
<parameter> <shortcut-fulfillment> android:name
<slice> <capability>

فقط برای Slices Android قابل اجراست

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

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

الگو ارزش ها ارزش گسترش یافته
https://example.com/test{?foo,bar} "foo": "123"

"bar": "456"

 https://example.com/test?foo=123&bar=456
https://example.com/test?utm_campaign=appactions{&foo,bar} "foo": "123"

"bar": "456"

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

تگ Shortcuts.xml موجود در صفات
<shortcut> <shortcuts>

android:shortcutId

android:shortcutShortLabel

android:shortcutLongLabel (اختیاری)

android:icon (اختیاری)

<intent> <shortcut>

android:action

android:targetClass (اختیاری)

android:targetPackage (اختیاری)

android:data (اختیاری)

<capability-binding> <shortcut>

android:key

<parameter-binding> <capability-binding>

android:key (اختیاری)

android:value

<extra> <shortcut>

android:name (اختیاری)

android:value

فقط برای تطبیق پارامتر 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.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, start my run»، برنامه یک intent دریافت می‌کند که مؤلفه را فراخوانی می‌کند: targetPackage ، targetClass . مؤلفه یک Extra با key = "exercise" ، value = "Running" دریافت می کند.

اگر برنامه شما در حال حاضر قادر به مدیریت 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, start my run»، برنامه 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 که نوع پارامتر آن مشخص است، لازم نیست. برای پارامترهای هدف سفارشی، یک نوع معنایی پشتیبانی شده باید اعلام شود.

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