יצירת shortcuts.xml

אחרי שמזהים את הפונקציונליות באפליקציה ואת הכוונה המובנית (BII) התואמת שרוצים להטמיע, מגדירים את ה-BII שהפונקציונליות תומכת בהם על ידי הגדרת רכיב capability בקובץ המשאב shortcuts.xml. הכרזה על BII בתור capability מאפשרת לאפליקציה לתמוך בכוונה הסמנטית הזו, ומאפשרת להשתמש ב-Google Assistant כדי להשלים את הבקשה הקולית בהתאם לכוונה.

Assistant משתמשת בעיבוד שפה טבעית (NLP) כדי לחלץ פרמטרים משאילתת משתמש. בחומר העזר בנושא כוונות מובנות מפורטים השדות שכל BII יכול לחלץ משאילתת משתמש משויכת. לדוגמה, אם משתמש מפעיל את היכולת [actions.intent.GET_FOOD_OBSERVATION][] באפליקציה שלכם על ידי אמירת "Ok Google, Ask ExampleApp what did I eat for Lunch last Friday", Assistant מחלצת את הפרמטרים הבאים של BII מהבקשה של המשתמש:

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

Assistant מעביר את הפרמטרים של BII אל intent של מילוי ההזמנה שמוגדר ב-capability. אפשר להגדיר רכיב intent אחד או יותר ביכולת כדי להתאים את הדרכים השונות שבהן משתמש יכול להפעיל BII. לדוגמה, אפשר להגדיר מילוי בקשה intent שדורש את שני הפרמטרים של BII בדוגמה שלמעלה. לאחר מכן תוכלו להגדיר כוונה שנייה שדורשת פרמטר BII יחיד, foodObservation.forMeal, שמדווח על כל הארוחות ביום מסוים, כמו "Ok Google, Ask ExampleApp what did I eat for Lunch".

סקירה כללית

מגדירים את פעולות האפליקציה באמצעות קובץ shortcuts.xml שממוקם בתיקייה res/xml של פרויקט האפליקציה, ולאחר מכן יוצרים הפניה לקובץ shortcuts.xml במניפסט של האפליקציה. כדי להוסיף הפניה ל-shortcuts.xml במניפסט של האפליקציה:

1. בקובץ המניפסט של האפליקציה (AndroidManifest.xml), מחפשים פעילות שמסנני ה-Intent שלה מוגדרים לפעולה android.intent.action.MAIN ולקטגוריה android.intent.category.LAUNCHER.

2. מוסיפים הפניה אל shortcuts.xml ב-AndroidManifest.xml באמצעות תג <meta-data> ב-Activity שכולל מסנני כוונות גם ל-MAIN וגם ל-LAUNCHER, באופן הבא:

   <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 כדי להרחיב את הפונקציונליות של היכולת. Assistant מטמיעה קיצורי דרך סטטיים כשאתם מעלים גרסה ל-Google Play Console. אפשר ליצור ולעדכן קיצורי דרך סטטיים רק על ידי יצירת גרסאות חדשות, ולכן הם הכי שימושיים כדי להדגיש פעילויות ותוכן נפוצים באפליקציה.

אפשר להפעיל את הפונקציונליות הבאה של פעולות באפליקציות באמצעות קיצורי דרך סטטיים:

• מקשי קיצור ליכולות. יוצרים קיצורי דרך שמפעילים מופע של capability שמכיל ערכי פרמטרים מוגדרים מראש של intent. לדוגמה, אתם יכולים להצהיר על קיצור דרך לאפליקציה Start a run (התחלת הריצה), כדי להפעיל את יכולת ה-BII START_EXERCISE באפליקציית הכושר.

  קיצורי הדרך האלה מכילים את המאפיינים 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>

capability שמגדיר את ה-Intent 'פעולה באפליקציה' שהאפליקציה תומכת בו. כל רכיב <capability> בקובץ shortcuts.xml צריך לספק לפחות רכיב <intent> אחד כדי לטפל בביצוע הפעולה.

מאפיינים:

• android:name: מזהה הפעולה של הכוונה המובנית (לדוגמה, [actions.intent.GET_FOOD_OBSERVATION][]). רשימה של כוונות מובנות נתמכות מופיעה במאמר הפנייה בנושא כוונות מובנות.
• app:queryPatterns: משאב של מערך מחרוזות של שאילתות שצפויות מהמשתמש לצורך הכוונה הזו. המאפיין הזה רלוונטי רק לכוונות מותאמות אישית, כי מודלים של BIIs כבר כוללים דרכים נפוצות שבהן משתמשים מבטאים את המשימות שהם מנסים לבצע או את המידע שהם מחפשים.

<intent>

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

מאפיינים:

• android:action: סוג הכוונה Action. ברירת המחדל היא ACTION_VIEW.
• android:targetClass: סוג הפעילות היעד, לדוגמה: "com.example.exercise.ExerciseActivity"
• android:targetPackage: החבילה שמכילה את מחלקת ה-Activity היעד, לדוגמה: "com.example.exercise
• android:data: השדה הזה מתווסף על ידי <url-template> אם התג הזה מוגדר ב-intent.

<url-template>

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

ריכזנו כאן כמה דוגמאות לערכים של תבניות של כתובות URL:

למידע נוסף על הגדרת תבניות של כתובות URL, ראו תבניות של כתובות URL במילוי הזמנה.

<extra>

הגדרת נתונים נוספים ל-intent. בפעולות באפליקציה, השדה הזה משמש רק להפעלת [הפעלת אפליקציה בחזית][] עבור capability.

<parameter>

מיפוי פרמטר BII לערכי פרמטרים של Intent. תוכלו לקרוא מידע נוסף במאמר נתונים והתאמה של פרמטרים.

מאפיינים:

• android:name: שם הפרמטר BII לשיוך לפרמטר intent. השם צריך להיות שדה ברמת עלה של הפרמטר BII (לדוגמה, foodObservation.aboutFood.name).
• android:key: מפתח שהוגדר על ידי המפתח לערך פרמטר BII. לדוגמה, אפשר להגדיר את הערך contact_name לפרמטר BII‏ message.recipient.name.
• android:mimeType: ה-mimeType של הפרמטר, למשל text/*. השדה הזה נדרש רק לפרמטרים של כוונות מותאמות אישית.
• android:required: מציין אם שאילתה של משתמש צריכה לכלול את הפרמטר הזה כדי שאפשר יהיה להשתמש בכוונה הזו לצורך מילוי. אם הפרמטר לא זמין, Assistant מנסה למלא את שאילתת המשתמש באמצעות intent הבא שמוגדר ל-capability.

<shortcut-fulfillment>

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

<parameter> (עבור <shortcut-fulfillment>)

מאפיין אופציונלי שממפה פרמטר BII יחיד למילוי קיצור דרך של מלאי שטחי פרסום בקוד. מידע נוסף זמין במאמר ביצוע באמצעות כוונות של קיצורי דרך.

מאפיין:

• android:name: השם של פרמטר ה-BII שצריך לשייך למילוי בקשת קיצור של מלאי שטחי פרסום מוטבע. השם צריך להיות שדה ברמת עלה של הפרמטר BII (לדוגמה, menuItem.name).

<slice>

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

הסכימה של קיצור הדרך

בטבלה הבאה מתוארים המאפיינים של רכיבי shortcut שמשמשים להפעלת הפונקציונליות של פעולות באפליקציה. כשכוללים תג, חובה לציין את כל המאפיינים שלו, אלא אם הם מסומנים כ'אופציונליים'.

תיאור הסכימה של קיצור הדרך

בקטע הזה מתוארים רכיבי הסכימה של shortcut.

<shortcut>

<shortcut> של Android שמוגדר ב-shortcuts.xml עם מאפיינים מסוימים שרלוונטיים לפעולות באפליקציה. ערכי המחרוזות של השדות shortcutShortLabel ו-shortcutLongLabel מופיעים באמצעות משאבי המחרוזות של ה-APK.

מאפיינים:

• android:shortcutId: המזהה של קיצור הדרך הזה.
• android:shortcutShortLabel: משאב מחרוזת שמייצג ביטוי קיצור דרך קצר. לדוגמה, "@string/callDavidShort" מייצג את הערך Call David.
• android:shortcutLongLabel: משאב מחרוזת שמייצג ביטוי קיצור ארוך. לדוגמה, "@string/callDavidLong" מייצג את הערך 'שיחה קולית אל דוד'.

<intent>

Intent של Android משויך לקיצור הדרך הזה. intent זה מבוצע כשמשתמש מפעיל את קיצור הדרך הזה באמצעות קול או מגע.

מאפייני הכוונה של shortcut זהים למאפייני capability intent.

<capability-binding>

שיוך של shortcut ל-capability של קמפיין לעידוד הפעולות באפליקציה. הוספת הרכיב הזה ל-shortcut מאפשרת לבצע השלמה קולית באמצעות Assistant.

מאפיינים:

• android:key: המאפיין android:name של ה-capability ש-shortcut מקושר אליו. לדוגמה actions.intent.START_EXERCISE.

<parameter-binding>

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

מאפיינים:

• android:key: השם של פרמטר ה-BII capability שרוצים לשייך אליו את קיצור הדרך. לדוגמה, exercise.name.
• android:value: הערך של entity. הוא יכול להיות entity בודד או רשימת משאבים.

<extra>

נתוני החבילה extra של קיצור הדרך. sameAs הוא הנתון היחיד שרלוונטי לאלמנטי shortcut של פעולות באפליקציה. כתובת ה-URL של sameAs מתייחסת לדף אינטרנט של עזרה שמזהה את הישות באופן חד-משמעי. משמש לציון ערך enum רק אם סוג הפרמטר של Intent הוא סוג משנה של schema.org/Enumeration. הוא נדרש בשדות של פרמטרים שהסוגים שלהם הם תת-סוגים של schema.org/Enumeration (לדוגמה: MealTypeBreakfast).

מאפיינים:

• android:key: הערך הנתמך לפעולות באפליקציה הוא: sameAs
• android:value: ערך כתובת ה-URL sameAs

פרטים נוספים זמינים במאמר התאמה של ערכי פרמטרים שמפורטים ברשימה.

אפשרויות למתן מענה לכוונה

מגדירים רכיבי intent בתוך <capability> כדי להצהיר איך Assistant מגיבה לפקודות קוליות של משתמשים שתואמות ליכולת הזו, או איך היא מבצעת אותן. יש כמה דרכים להגדיר איך intent יפעיל יעד השלמה באפליקציה, בהתאם למבנה הניווט באפליקציה.

האפשרויות הבאות זמינות:

• כוונות מפורשות: כדי להפעיל רכיב ספציפי של אפליקציה, מגדירים את המאפיינים targetClass ו-targetPackage ל-intent. זו שיטת המילוי המומלצת של פעולות באפליקציות.

• קישורי עומק: כדי להפעיל יעדים של אפליקציות באמצעות קישורי עומק ל-Android, מגדירים תג <url-template> בתוך הרכיב intent. השיטה הזו שימושית אם הניווט באפליקציה כבר מבוסס על קישורי עומק.

• נתוני כוונת הרכישה: אפשר לספק מזהה URI של השלמה במאפיין intent android:data. אם התג הזה מוגדר גם ב-intent, הנתונים של <url-template> מחליפים את הנתונים בשדה הזה.

נתוני פרמטרים והתאמה

כברירת מחדל, Assistant שולחת לאפליקציה שלכם פרמטרים של BII שנשלפו משאילתת המשתמש בתור נתוני extra של intent של Android שמוגדרים ב-capability.

לחלופין, אפשר להצהיר על תג <url-template> ב-capability שמכיל placeholders לפרמטרים דינמיים. התבנית הזו ממופה לאחת מהפעילויות שלכם ב-Android באמצעות כתובת URL של קישורי אפליקציות, סכימה מותאמת אישית או כתובת URL מבוססת-כוונה.

שימוש בתוספות Intent

הדוגמה הבאה ממחישה כוונה מפורשת שהוגדרה למילוי הזמנות ב-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>

בהתאם לדוגמה שלמעלה, לשאילתה של משתמש כמו: "Ok Google, order a latte ", האפליקציה מקבלת intent שמפעילה את הרכיב: targetPackage, targetClass. הרכיב מקבל Extra עם key = "exercise", value = "Running".

שימוש בתבנית של כתובת URL לקישורי עומק ל-Android

אם האפליקציה שלכם כבר יכולה לטפל בכתובות URL שמקושרות לאפליקציה, עם פרמטרים דינמיים, תוכלו להגדיר <url-template> ב-intent כדי ליצור קישורי עומק ל-Android לצורך מילוי. בדוגמה הבאה מוגדר <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>

בהתאם לדוגמה שלמעלה, לשאילתת משתמש כמו "Ok Google, order a latte from ExampleApp", האפליקציה מקבלת את כתובת ה-URL שנוצרה: ‎"myapp://start?exercise=Running"‎.

כדי למפות את פרמטר ה-BII למיקום בכתובת ה-URL, צריך להשתמש במאפיין android:name של התג <parameter>. המאפיין הזה תואם לערך android:key בתבנית כתובת ה-URL שרוצים להחליף בפרטי המשתמש. הערך android:key צריך להופיע ב-<url-template> ומוקף בסוגריים מסולסלים ({}).

התאמה לערכי פרמטרים מספריים

חלק מהפרמטרים של BII מספקים ערכים ממוספרים לכוונה למלא את ההזמנה, למשל ערכי הטקסט הנתמכים של BII‏ RECORD_FOOD_OBSERVATION. לגבי הפרמטרים האלה, 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 מפעילה התאמה לסוג הארוחה 'ארוחת בוקר', הפריט הנוסף הבא נשלח עם ה-fulfillment‏ intent:

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

תכונות

התכונות הבאות של 'פעולות באפליקציה' זמינות ב-shortcuts.xml.

מלאי שטחי פרסום מוטבע לפעולות באפליקציה

עבור חלק מהפרמטרים של BII, אפשר להשתמש במקשי קיצור כדי להנחות את תהליך החילוץ של ישויות לקבוצת ישויות נתמכות שצוינו ב-shortcuts.xml, שנקראות 'מלאי מוטבע'. פרטים נוספים זמינים במאמר מלאי שטחי פרסום בקוד.

קהלים בהתאמה אישית לפי העדפות תוכן

אפשר להצהיר על כוונות בהתאמה אישית ב-shortcuts.xml כדי להפעיל באמצעות קול תכונות באפליקציה שלא תואמות ל-BIIs הזמינים. למרות שהפונקציונליות שלהם דומה להגדרה של BII, כדי להשתמש בכוונות בהתאמה אישית נדרשים שני מאפיינים נוספים ב-shortcuts.xml:

• app:queryPatterns: משאב מערך שמצהיר על דפוסי השאילתות השונים של כוונת רכישה בהתאמה אישית.

• android:mimeType: סוג הפרמטר של קהל בהתאמה אישית עם כוונת רכישה. השדה הזה לא נדרש ב-BIIs, שבהם סוג הפרמטר ידוע. לפרמטר כוונה מותאם אישית, צריך להצהיר על סוג סמנטי נתמך.

פרטים נוספים זמינים במאמר כוונות מותאמות אישית.