ارسال میان‌برهای پویا به «دستیار»

میان‌برهای Android روش‌های سریعی برای انجام کنش یا دسترسی به محتوا در برنامه به کاربران ارائه می‌دهد. «دستیار» می‌تواند میان‌برهای پویای Android شما را در زمان‌های مرتبط به‌طور فعال به کاربران پیشنهاد دهد و به کاربران امکان دهد به‌راحتی عملکرد فعال‌شده با صدای شما را کشف و بازپخش کنند.

برای مثال، می‌توانید برای هر یادداشتی که کاربر در برنامه یادداشت‌برداری شما ایجاد می‌کند، میان‌بری را ارسال کنید. با افزودن کتابخانه Google Shortcuts Integration Jetpack به پروژه‌تان، پیوندهای پویا را برای نمایش در سطوح Google، مثل «دستیار»، واجدشرایط می‌کنید. این کتابخانه به «دستیار» اجازه می‌دهد میان‌برهای پویایی را که بااستفاده از کلاس ShortcutManagerCompat ارسال می‌کنید دریافت کند، که یک پوشاننده Jetpack برای ShortcutManager API است.

وقتی از کتابخانه «ادغام میان‌برهای Google» در برنامه‌تان استفاده می‌کنید، میان‌برهای پویایی که به Google ارسال می‌کنید به‌عنوان پیشنهادهای میان‌بر گفتاری در برنامه «دستیار» برای کاربران قابل‌مشاهده است. می‌توانید بااستفاده از روش pushDynamicShortcut() کتابخانه ShortcutManagerCompat، تعداد نامحدودی میان‌بر پویا به «دستیار» ارسال کنید.

پیکربندی پروژه توسعه

افزودن عملکرد میان‌برهای پویا به برنامه شما به کتابخانه «ادغام میان‌برهای Google» نیاز دارد که یک کتابخانه Android Jetpack است. این بخش نحوه پیکربندی پروژه توسعه برنامه را برای گنجاندن این کتابخانه شرح می‌دهد.

برای افزودن این کتابخانه Jetpack و پیکربندی پروژه‌تان، این مراحل را دنبال کنید:

1. فایل gradle.properties خود را برای مدیریت کتابخانه‌های Jetpack به‌روز کنید:

   gradle.properties

   android.useAndroidX=true
   # Automatically convert third-party libraries to use AndroidX
   android.enableJetifier=true
   

2. وابستگی‌های کتابخانه Jetpack را به build.gradle اضافه کنید:

   app/build.gradle

   dependencies {
    implementation "androidx.core:core:1.6.0"
    implementation "androidx.core:core-google-shortcuts:1.0.1"
    ...
   }
   

   در کد نمونه قبلی، دو کتابخانه Jetpack را به‌عنوان وابستگی فهرست می‌کنید. کتابخانه androidx.core:core:1.6.0 حاوی کلاس ShortcutManagerCompat است که از آن برای ارسال میان‌برهای پویا به Google استفاده می‌کنید.

   ‫androidx.core:core-google-shortcuts:1.0.1 کتابخانه «ادغام میان‌برهای Google» است. این کتابخانه حاوی API توسعه‌دهنده نیست. با افزودن آن به‌عنوان وابستگی، به «دستیار» امکان می‌دهید میان‌برهای پویایی را که بااستفاده از کلاس ShortcutManagerCompat ارسال می‌کنید دریافت کند.

   توجه: برای پیدا کردن جدیدترین نسخه‌های کتابخانه‌های Core و Google Shortcuts Integration، به کاوشگر کتابخانه Jetpack مراجعه کنید.

ارسال میان‌برهای پویا

برای ارسال میان‌برهای پویایی که واجدشرایط نمایش در «دستیار» هستند، ابتدا میان‌بر را بااستفاده از کلاس ShortcutInfoCompat.Builder() ایجاد کنید.

سپس میان‌بر را بااستفاده از روش ShortcutManagerCompat.pushDynamicShortcut() ارسال می‌کنید. هرگاه کاربر کنش مربوطی را در برنامه‌تان تکمیل کند، میان‌برها ارسال می‌شوند. کد نمونه زیر هربار که کاربر فهرستی را در برنامه یادداشت‌ها و فهرست‌ها ایجاد می‌کند، میان‌بری را ارسال می‌کند.

ExampleOrderActivity

کاتلین

// Define the dynamic shortcut for an item
var intent = Intent(context, DisplayOrderActivity::class.java)
intent.action = Intent.ACTION_VIEW
var shortcutInfo = ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Running")
    .setLongLabel("Start running")
    .addCapabilityBinding(
        "actions.intent.CREATE_ITEM_LIST", "itemList.name", Arrays.asList("My First List")
    )
    .setIntent(intent) // Push the shortcut
    .build()

// Push the shortcut
ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo)

جاوا

// Define the dynamic shortcut for an item
Intent intent = new Intent(context, DisplayOrderActivity.class);
intent.setAction(Intent.ACTION_VIEW);

ShortcutInfoCompat.Builder shortcutInfo = new ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Running")
    .setLongLabel("Start running")
    .addCapabilityBinding(
      "actions.intent.CREATE_ITEM_LIST", "itemList.name", Arrays.asList("My First List"))
    .setIntent(intent)
    .build();

// Push the shortcut
ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

id ارجاع‌داده‌شده در روش ShortcutInfoCompat.Builder در کد نمونه قبلی، shortcutId شیء میان‌بر حاصل را تعریف می‌کند. این id باید یک رشته ثابت منحصربه‌فرد باشد. برای جزئیات، اسناد میان‌برهای Android را ببینید.

در مثال قبلی، روش addCapabilityBinding میان‌بر پویا را به capability با همان android:name تعریف‌شده در shortcuts.xml مقید می‌کند. این روش به شما امکان می‌دهد میان‌بر را به یک پارامتر معنایی قصد ازپیش‌تعریف‌شده (BII) مرتبط کنید.

میان‌برهای پویا گاهی بدون هیچ‌گونه ارتباط خاصی با پارامتر «هدف داخلی برنامه» ارسال می‌شوند. وقتی کاربر «دستیار» را فرامی‌خواند، «دستیار» intent تعریف‌شده در میان‌بر را برای انجام کنش راه‌اندازی می‌کند. مثال زیر میان‌بر پویایی را نشان می‌دهد که هیچ پارامتری به آن مرتبط نشده است:

کاتلین

var intent: Intent = Intent(context, DisplayOrderActivity::class.java)
intent.setPackage(this, "com.sample.app")
intent.setAction(Intent.ACTION_VIEW)

var shortcutInfo: ShortcutInfoCompat = ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Create a list")
    .setLongLabel("Create a list")
    .addCapabilityBinding("actions.intent.CREATE_ITEM_LIST")
    .setIntent(intent)
    .build()

ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

جاوا

Intent intent = new Intent(context, DisplayOrderActivity.class);
intent.setPackage(this, "com.sample.app");
intent.setAction(Intent.ACTION_VIEW);

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(context, id)
  .setShortLabel("Create a list")
  .setLongLabel("Create a list")
  .addCapabilityBinding("actions.intent.CREATE_ITEM_LIST")
  .setIntent(intent)
  .build();

ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

آزمایش میان‌برهای پویا با «دستیار»

وقتی «دستیار Google» میان‌بر پویایی را از برنامه شما با موفقیت دریافت می‌کند، میان‌بر واجدشرایط می‌شود تا به‌عنوان پیشنهاد «میان‌بر صوتی» در برنامه Android «دستیار» نشان داده شود. برنامه «دستیار» جدیدترین میان‌برهای ارسال‌شده توسط برنامه شما را پیشنهاد می‌دهد.

برای آزمایش میان‌برهای پویا با «دستیار»، این مراحل را دنبال کنید:

1. پیش‌نمایشی از «کنش‌های برنامه» خود ایجاد کنید و دستگاه آزمایشی یا شبیه‌ساز خود را برای آزمایش کنش‌ها با دنبال کردن همان الزامات راه‌اندازی افزونه «دستیار Google» آماده کنید.
2. برنامه را باز کنید و میان‌بر پویایی را برای ارسال تعریف کنید. سپس کنشی را تکمیل کنید. برای مثال، اگر هربار که یادداشتی در برنامه یادداشت‌برداری‌تان ایجاد می‌شود، میان‌بری را ارسال کنید، سپس یادداشت جدیدی ایجاد کنید.
3. میان‌برها را در برنامه تنظیمات دستیار در دستگاهتان باز کنید. میان‌بر پویای شما در فهرست برنامه‌تان نشان داده می‌شود.