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

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

לדוגמה, ניתן להעביר ב-push קיצור דרך לכל הערה שמשתמש יצר את אפליקציית פתקים שלכם. הרווחת קישורים דינמיים שעומדים בדרישות להצגה בפלטפורמות של Google, כמו Assistant, על ידי הוספה של ספריית Jetpack לשילוב של Google קיצורי דרך לפרויקט שלכם. הספרייה הזו מאפשרת ל-Assistant להשתמש בקיצורי דרך דינמיים שמעבירים בדחיפה באמצעות ShortcutManagerCompat, שהיא wrapper של 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. יוצרים תצוגה מקדימה של פעולות האפליקציה ומכינים את מכשיר הבדיקה או את המהדמיה לבדיקה של הפעולות, לפי אותן דרישות הגדרה כמו לPlugin של Google Assistant.
2. פותחים את האפליקציה ומגדירים קיצור דרך דינמי להעברה. ואז משלימים את הפעולה. לדוגמה, אם תלחצו על מקש קיצור בכל פעם תיצרו פתק באפליקציה לכתיבת פתקים, ואז תיצרו הערה חדשה.
3. פותחים את קיצורי הדרך באפליקציה הגדרות Assistant במכשיר. שלך קיצור הדרך הדינמי יופיע ברשימה של האפליקציה.