יצירת shortcuts.xml

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

Assistant משתמשת בעיבוד שפה טבעית כדי לחלץ פרמטרים משאילתה של משתמש. בחומר העזר בנושא כוונות מובנות מפורטים השדות שכל 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. לדוגמה, אפשר להצהיר על קיצור דרך לאפליקציה 'התחלת ריצה' שמפעיל את יכולת ה-BII‏ START_EXERCISE באפליקציית הכושר.

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

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

    קיצורי הדרך של 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 Slices

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

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

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

<shortcut-fulfillment>

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

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

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

מאפיין:

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

<slice>

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

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

בטבלה הבאה מתוארים המאפיינים של רכיבי 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 מופיעים באמצעות משאבי המחרוזות של ה-APK.

מאפיינים:

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

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

שימוש בתוספים של כוונת רכישה

הדוגמה הבאה ממחישה כוונה מפורשת שמוגדרת להשלמה של 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, start my run", האפליקציה מקבלת 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, start my run", האפליקציה מקבלת את כתובת ה-URL שנוצרה: ‎"myapp://start?exercise=Running"‎.

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

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

תכונות

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

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

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

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

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

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

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

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