אחרי שמזהים את הפונקציונליות בתוך האפליקציה ואת הכוונה המובנית המתאימה
(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
במניפסט של האפליקציה:
בקובץ המניפסט של האפליקציה (
AndroidManifest.xml
), מחפשים פעילות מסנני Intent מוגדרים לפעולהandroid.intent.action.MAIN
קטגוריהandroid.intent.category.LAUNCHER
.הוספת הפניה אל
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> |
|
<intent> |
<capability> |
|
<url-template> |
<intent> |
|
<extra> |
<intent> |
רלוונטי רק להפעלת אפליקציה שפועלת בחזית |
<parameter> |
<intent> |
|
<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
: סוג IntentAction
. ברירת המחדל היא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"
|
https://example.com/test?foo=123&bar=456 |
https://example.com/test?utm_campaign=appactions{&foo,bar} |
"foo": "123"
|
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> |
|
<intent> |
<shortcut> |
|
<capability-binding> |
|
|
<parameter-binding> |
<capability-binding> |
|
<extra> |
<shortcut> |
רלוונטי רק להתאמה לפרמטרים של 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
: ערך כתובת ה-URLsameAs
פרטים נוספים זמינים במאמר התאמת ערכי פרמטרים שמפורטים ברשימה.
אפשרויות לאספקה של 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 לקישורי עומק ל-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 מ-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, שבהם סוג הפרמטר ידוע. לפרמטר כוונה מותאם אישית, צריך להצהיר על סוג סמנטי נתמך.
פרטים נוספים זמינים במאמר קהלים בהתאמה אישית לפי העדפות תוכן.