יצירת shortcuts.xml

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

Assistant משתמשת בעיבוד שפה טבעית (NLP) כדי לחלץ פרמטרים מהמשתמש שאילתה. חומר העזר בנושא Intents מובנים מפרט את השדות שכל BII שיכול לחלץ משאילתת משתמש משויכת. לדוגמה, אם משתמש מפעילה את היכולת actions.intent.ORDER_MENU_ITEM באפליקציה באמצעות ואומרים, "Ok Google, order a פיצה from ExampleCafe in ExampleApp", Assistant מחלץ את פרמטרי ה-BII הבאים מבקשת המשתמש:

• menuItem.name = "פיצה"
• menuItem.inMenuSection.inMenu.forRestaurant.name = "ExampleCafe"

Assistant מעבירה פרמטרים של BII למילוי ההזמנות intent שמוגדר capability. ניתן להגדיר רכיב intent אחד או יותר ביכולת להתאים לדרכים השונות שבהן משתמש עשוי להפעיל BII. לדוגמה, אתם יכול להגדיר intent של מילוי בקשה שמחייב את שני הפרמטרים של BII בדוגמה שלמעלה. לאחר מכן אפשר להגדיר Intent שני שדורש BII יחיד פרמטר, menuItem.name, שמציג אפשרויות של מסעדות בקרבת מקום אם המשתמש מאפשרת בקשה פשוטה יותר, למשל "Hey Google, order a פיצה on ExampleApp".

סקירה כללית

הגדרת את הפעולות באפליקציה באמצעות קובץ 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 שיש לו Intent מסננים גם ל-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 כדי להימנע משגיאות הידור כשמגדירים יכולות של פעולות באפליקציה בshortcuts.xml. פרטים נוספים זמינים במאמר תחילת העבודה עם Android Jetpack.

קיצורי דרך סטטיים

כשמגדירים את capability, אפשר להצהיר על רכיבי shortcut סטטיים ב: shortcuts.xml כדי להרחיב את הפונקציונליות של היכולת. קיצורי דרך סטטיים Assistant מטמיעה את הנתונים של הגרסה כשמעלים גרסה ל-Google Play Console. מכיוון שניתן ליצור ולעדכן קיצורי דרך סטטיים רק על ידי יצירת גרסאות חדשות, הם השימושיים ביותר להדגשת פעילויות ותוכן נפוצים באפליקציה.

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

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

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

• מקשי קיצור לישויות. מקשי הקיצור לישויות מספקים רשימה של פרמטרים נתמכים למילוי הזמנות של שאילתה קולית של capability. לדוגמה, ישות קיצור דרך עם רשימה של סוגי תרגילים ('טיול', 'לרוץ' וכו') שקשורים פרמטר BII אחד של exercise.name START_EXERCISE ליכולות של בינה מלאכותית גנרטיבית. אם הביטוי של המשתמש תואם לישות, המזהה של shortcutId הוא מועבר ל-Intent במקום לערך הגולמי של השאילתה.

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

סכימת יכולות

בטבלה הבאה מתוארת הסכימה של פעולות באפליקציה לרכיבי capability. ב-shortcuts.xml. כשמוסיפים תג, כל המאפיינים שלו נדרשים אלא אם הוא מסומן כ'אופציונלי'.

תיאור של סכימת היכולות

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

<capability>

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

מאפיינים:

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

<intent>

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

מאפיינים:

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

<url-template>

תבנית ליצירת URI של קישור עומק אל תיפתח במכשיר. אפשר להרחיב את התבנית עם Intent מובנה פרמטרים אם כל הפרמטרים הנדרשים לתבנית זמינים. עבור של תבנית כתובת האתר מסוג 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: הצהרה אם שאילתת המשתמש צריכה לכלול את המאפיין הזה של Intent זה, שישמש למילוי הזמנות. אם הפרמטר לא זמינה, Assistant מנסה למלא את השאילתה של המשתמש באמצעות intent הוגדר ל-capability.

<data>

משייך מלאי באינטרנט אל parameter.

מאפיין:

• android:pathPattern: תבנית URL של entity כתובות URL להחזרה באמצעות מלאי באינטרנט. במאפיין הזה יש תמיכה בשני תווים כלליים לחיפוש:

  • *: כוכבית תואמת לרצף של אפס מופעים או יותר של התו הקודם.

  • .*: נקודה ואחריה כוכבית תואמת לכל רצף של אפס או יותר תווים.

  • תווי בריחה נדרשים רק עבור * ו-\ באופן מילולי, יכול בתו בריחה (escape) בתור \\* ו-\\\\, בהתאמה.

<short-fulfillment>

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

<parameter> (במשך <shortcut-fulfillment>)

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

מאפיין:

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

<slice>

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

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

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

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

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

<short>

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

מאפיינים:

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

<intent>

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

מאפייני Intent של shortcut זהים ל-capability intent .

<capability-binding>

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

מאפיינים:

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

<parameter-binding>

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

מאפיינים:

• android:key: שם הפרמטר capability של ה-BII לשיוך את קיצור הדרך הזה אל. לדוגמה: foodObservation.aboutFood.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

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

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

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

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

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

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

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

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

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

הדוגמה הבאה ממחישה כוונה מפורשת שהוגדרה עבור capability

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name" android:key="menu" />
  </intent>
</capability>

בהינתן הדוגמה שלמעלה, לשאילתה של משתמש כמו "Ok Google, order a latte from ExampleApp," האפליקציה מקבלת intent שמפעיל את הרכיב: targetPackage, targetClass. הרכיב מקבל תוספת עם key = ”menu”, value = ”latte”.

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

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

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent>
    <url-template android:value="myapp://order{?menu}" />
    <parameter android:name="menuItem.name" android:key="menu" />
  </intent>
</capability>

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

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

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

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

תכונות

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

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

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

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

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

אפשר לקרוא פרטים נוספים במאמר בנושא מלאי באינטרנט.

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

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

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

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

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