יצירת shortcuts.xml

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

Assistant משתמשת בעיבוד שפה טבעית (NLP) כדי לחלץ פרמטרים מהמשתמש שאילתה. חומר העזר בנושא Intents מובנים מפרט את השדות שכל BII שיכול לחלץ משאילתת משתמש משויכת. לדוגמה, אם משתמש מפעילה את היכולת [actions.intent.GET_FOOD_OBSERVATION][] באפליקציה על ידי אמירת: "Ok Google, Ask ExampleApp what 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 שיש לו 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. כשכוללים תג, כל המאפיינים שלו נדרשים, אלא אם הם מסומנים כ'אופציונליים'.

תג Shortcuts.xml נמצא בתוך מאפיינים
<capability> <shortcuts>

android:name

app:queryPatterns (רלוונטי רק לקהלים בהתאמה אישית עם כוונת רכישה)

<intent> <capability>

android:action (אופציונלי)

android:targetClass (אופציונלי)

android:targetPackage (אופציונלי)

android:data (אופציונלי)

<url-template> <intent>

android:value

<extra> <intent>

android:key

android:value

רלוונטי רק להפעלת אפליקציה שפועלת בחזית

<parameter> <intent>

android:name

android:key

android:mimeType (רלוונטי רק לקהלים בהתאמה אישית עם כוונת רכישה)

android:required (אופציונלי)

app:shortcutMatchRequired (אופציונלי)

<shortcut-fulfillment> <capability> רלוונטי רק למלאי שטחי פרסום מוטבע
<parameter> <shortcut-fulfillment> android:name
<slice> <capability>

רלוונטי רק לפרוסות של Android

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

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

<capability>

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

מאפיינים:

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

<intent>

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

מאפיינים:

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

<url-template>

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

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

תבנית ערכים ערך מורחב
https://example.com/test{?foo,bar} "foo": "123"

"bar": "456"

https://example.com/test?foo=123&bar=456
https://example.com/test?utm_campaign=appactions{&foo,bar} "foo": "123"

"bar": "456"

https://example.com/test?utm_campaign=appactions&foo=123&bar=456
https://example.com/test?utm_campaign=appactions{#foo} "foo": "123" https://example.com/test?utm_campaign=appactions#foo=123
myapp://example/{foo} "foo": "123" myapp://example/123

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

<extra>

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

<parameter>

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

מאפיינים:

  • 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.

<short-fulfillment>

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

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

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

מאפיין:

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

<slice>

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

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

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

תג Shortcuts.xml נמצא בתוך מאפיינים
<shortcut> <shortcuts>

android:shortcutId

android:shortcutShortLabel

android:shortcutLongLabel (אופציונלי)

android:icon (אופציונלי)

<intent> <shortcut>

android:action

android:targetClass (אופציונלי)

android:targetPackage (אופציונלי)

android:data (אופציונלי)

<capability-binding> <shortcut>

android:key

<parameter-binding> <capability-binding>

android:key (אופציונלי)

android:value

<extra> <shortcut>

android:name (אופציונלי)

android:value

רלוונטי רק להתאמה לפרמטרים של Enum.

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

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

<shortcut>

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

מאפיינים:

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

<intent>

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

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

מגדירים רכיבי 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.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 from ExampleApp," האפליקציה מקבלת intent שמפעיל את הרכיב: targetPackage, targetClass. הרכיב מקבל תוספת עם key = "exercise", value = "Running".

אם האפליקציה שלכם כבר יכולה לטפל בכתובות 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 מ-ExampleApp," האפליקציה מקבלת את כתובת ה-URL שנוצרה: "myapp://start?exercise=sports".

כדי למפות את פרמטר ה-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, שנקראות בשם מלאי מוטבע. אפשר לקרוא פרטים נוספים במאמר בנושא מלאי מוטבע.

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

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

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

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

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