דחיפת קיצורי דרך דינמיים ל-Assistant

מקשי הקיצור ב-Android מספקים למשתמשים שיטות לביצוע פעולה או גישה לתוכן באפליקציה. Assistant יכולה להציע באופן יזום את קיצורי הדרך הדינמיים ב-Android למשתמשים ב- מועדים רלוונטיים, כך שמשתמשים יוכלו לגלות מחדש בקלות את המודעות שלך פונקציונליות שמופעלת באמצעות פקודות קוליות.

לדוגמה, אפשר להעביר קיצור דרך לכל הערה שמשתמש יוצר באפליקציית העריכה. כדי לאפשר הצגה של קישורים דינמיים בממשקים של Google, כמו Assistant, צריך להוסיף לפרויקט את ספריית Jetpack לשילוב קיצורי דרך של Google. הספרייה הזו מאפשרת ל-Assistant לקבל קיצורי דרך דינמיים שאתם מקישים עליהם באמצעות הכיתה ShortcutManagerCompat, שהיא מעטפת של Jetpack לממשק ה-API ShortcutManager.

כשמשתמשים בספריית השילוב של קיצורי הדרך של Google באפליקציה, התהליך דינמי קיצורי דרך שמועברים בדחיפה ל-Google גלויים למשתמשים כהצעות לקיצורי דרך קוליים באפליקציית Assistant. ניתן להעביר מספר בלתי מוגבל של קיצורי דרך דינמיים Assistant באמצעות השיטה pushDynamicShortcut() של הספרייה ShortcutManagerCompat.

הגדרת פרויקט הפיתוח

כדי להוסיף לאפליקציה פונקציונליות של קיצורי דרך דינמיים, צריך את ספריית השילוב של Google Shortcuts, שהיא ספריית 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. על ידי הוספת התלות הזאת, Assistant תוכל לקבל קיצורי דרך דינמיים שלוחצים עליהם באמצעות המחלקה ShortcutManagerCompat.

העברת קיצורי דרך דינמיים

כדי לדחוף קיצורי דרך דינמיים שעומדים בדרישות להצגה ב-Assistant, קודם צריך ליצור את קיצור הדרך באמצעות הכיתה 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. השיטה הזו מאפשרת לשייך את קיצור הדרך פרמטר סמנטי של Intent מובנה (BII).

לפעמים קיצורי הדרך הדינמיים נדחפים ללא פרמטר BII מסוים עם שיוך. כשמשתמש מפעיל את Assistant, היא מפעילה את ה-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);

בדיקה של מקשי הקיצור הדינמיים באמצעות Assistant

כש-Google Assistant מקבלת קיצור דרך דינמי מהאפליקציה שלכם, הוא עומד בדרישות להצגה כצעד ראשון להפעלה קולית באפליקציית Assistant ל-Android. באפליקציית Assistant מוצגים קיצורי הדרך האחרונים שהאפליקציה שלכם שלחה.

כדי לבדוק את מקשי הקיצור הדינמיים באמצעות Assistant:

1. ליצור תצוגה מקדימה של הפעולות באפליקציה ולהכין את מכשיר הבדיקה, או אמולטור לפעולות בדיקה על ידי ביצוע של אותה הגדרה דרישות הגדרה כמו עבור הפלאגין של Google Assistant.
2. פותחים את האפליקציה ומגדירים קיצור דרך דינמי לדחיפה. ואז משלימים את הפעולה. לדוגמה, אם תלחצו על מקש קיצור בכל פעם תיצרו פתק באפליקציה לכתיבת פתקים, ואז תיצרו הערה חדשה.
3. פותחים את קיצורי הדרך באפליקציה הגדרות Assistant במכשיר. הקיצור הדרך הדינמי יופיע ברשימה של האפליקציה.