דף זה תורגם על ידי Cloud Translation API.

מלאי מוטבע

כשאתם מטמיעים פעולות באפליקציה באפליקציה ל-Android, אתם עשויים למצוא את עצמכם שצריך לטפל בבקשות שהן גרסאות שונות של נושא מסוים. לדוגמה, יש לומר מטמיעים את ה-Intent המובנה (BII) של START_EXERCISE כדי לאפשר משתמשים מתחילים מגוון רחב של אימוני כושר כששואלים את Assistant דברים כמו, "Ok Google, start a run on Example App"

כדי למלא את הכוונה הזו, צריך לוגיקה של התאמת הבקשה שתטפל בכל אחת מהן סוג של אימון, כולל וריאציות כמו "ריצה", "sprint," או 'מרוץ'. הלוגיקה הזו הופכת תוך זמן קצר למסורבלת ככל שאימוני הכושר הנתמכים גדלים.

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

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

מלאי שטחי פרסום מוטבע מאפשר ל-Google Assistant לפשט את פרמטר ה-BII שסופקו לאפליקציה במהלך ההפעלות של הפעולות באפליקציה.

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

תרשים זרימה של המשתמש במלאי שטחי פרסום מוטבע — **איור 1.** תרשים זרימה של יכולת `START_EXERCISE` שמשתמשת מלאי מוטבע כדי לפרש שמות של אימוני כושר שסופקו על ידי משתמשים עבור באפליקציה.

מגבלות וחלופות

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

מגבלת קיצורי דרך: עד 1,000 קיצורי דרך בתוך שורה של מלאי שטחי פרסום מוגדרות לכל אפליקציה.
מגבלת מילים נרדפות: כל קיצור דרך מוטבע של מלאי יכול להכיל 20 לכל היותר ערכים נרדפים.
הגדרה סטטית: מקשי קיצור מוטבעים של מלאי שטחי פרסום מוצהרים באופן סטטי בshortcuts.xml ואפשר לעדכן אותו רק למשתמשים שלך על ידי פרסום של האפליקציה.

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

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

יצירת מלאי מוטבע

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

Ok Google, start a run on Example App
Hey Google, start a jog on Example App.

במקש הקיצור של המלאי המוטבע, מגדירים את shortcutId ל-"CARDIO_RUN", מזהה האימון שנדרש על ידי האפליקציה. לאחר מכן מציינים 'run' וגם "ריצה" בתור מילים נרדפות המשויכות לshortcutId. לאחר מכן, כשמשתמש מפעיל הפעולה באפליקציה עם השאילתות הקודמות, Assistant משתמשת במזהה "CARDIO_RUN" לפרמטר ה-BII כשיוצרים Intent של מילוי הזמנה.

קטע הקוד הבא מקובץ app/res/shortcuts.xml לדוגמה מטמיע במקרה הזה:

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

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
    </capability-binding>
</shortcut>

בדוגמה שלמעלה, המלאי המוטבע shortcut כולל הצהרה <parameter-binding> בתוך רכיב <capability-binding>, שיקשר אותו לפרמטר exercise.name BII שמוגדר <capability>.

משאב המערך @array/run_names מציין רשימה של מילים נרדפות ב- res/values/arrays.xml ש-Assistant מזהה וממפה אל "CARDIO_RUN" מזהה פריט:

<!-- Synonym values for "CARDIO_RUN" inline inventory -->
<resources>
  <string-array name="run_names">
    <item>Run</item>
    <item>Jog</item>
    <item>Sprint</item>
  </string-array>
</resources>

כשיסופק <url-template> עבור היכולת, shortcutId עבור ערך תואם מוכנס לכתובת ה-URL שנוצרה placeholder של הפרמטר. הקוד הבא מתוך דוגמה הקובץ app/res/shortcuts.xml מטמיע את הפנייה הזו:

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://workout{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
  </capability-binding>
</shortcut>

בדוגמה שלמעלה, Assistant יוצרת את קישור העומק למילוי הזמנות myapp://workout?exercise=CARDIO_RUN

מילוי הזמנות באמצעות קיצורי דרך באמצעות Intent

כברירת מחדל, קיצור דרך מספק את המאפיין shortcutId של מלאי שטחי פרסום תואם בגוף ההודעה. לערך intent של capability שקיצור הדרך מקושר אליו, כפי שהוצהר בתג <capability-binding> של קיצור הדרך. אפשר לציין לחלופין שintent שמוגדר במקש הקיצור עצמו ישמש עבור על ידי הוספה של תג <shortcut-fulfillment> אל capability.

הקוד הבא מקובץ app/res/shortcuts.xml לדוגמה מטמיע מילוי קיצור דרך:

<capability android:name="actions.intent.START_EXERCISE">
  <shortcut-fulfillment>
    <parameter android:name="exercise.name"/>
  </shortcut-fulfillment>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
  </capability-binding>
  <intent android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</shortcut>

בדוגמה הקודמת, אם שאילתת המשתמש תואמת לערך מוטבע של מלאי לפרמטר exercise.name, התג <shortcut-fulfillment> מציין שה-intent של קיצור הדרך הקשור משמש למילוי הזמנות.

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

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

הקוד הבא מקובץ app/res/shortcuts.xml לדוגמה מטמיע את הקוד הזה BII עם קיצור דרך יחיד שמייצג את תכונת סטטוס ההזמנה של האפליקציה:

<capability android:name="actions.intent.OPEN_APP_FEATURE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MyClass">
    <parameter
       android:name="feature"
       android:key="featureParam" />
  </intent>
  <!-- Required fallback fulfillment to handle when parameters are missing from user query. -->
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MyClass">
    <parameter
       android:name="HOME_SCREEN"
       android:key="featureParam" />
  </intent>
</capability>

<!-- Inline inventory for OPEN_APP_FEATURE. -->

<shortcut android:shortcutId="ORDER_STATUS">
  <capability-binding android:key="actions.intent.OPEN_APP_FEATURE">
    <parameter-binding
      android:key="feature"
      android:value="@array/order_status_names" />
    </capability-binding>
</shortcut>

המשאבים של מערך המחרוזת ב-res/values/arrays.xml, @array/order_status_names, מציין רשימה של מילים נרדפות לתכונה הזו:

<resources>
  <string-array name="order_status_names">
    <item>Order status</item>
    <item>Orders</item>
    <item>Order history</item>
  </string-array>
</resources>

עם היכולת הקודמת, Assistant יכולה למלא מגוון רחב של ביטויים לאותה תכונה:

"Ok Google, show my order status on Example App"
"Ok Google, show my Orders on Example App"
"Ok Google, show my order history on Example App".

בדיקת מלאי מוטבע

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

עבור לדוגמה, יכולת של START_EXERCISE BII עשויה להשתמש במלאי מוטבע כדי תרגום "run" של פרמטר ה-BII שסופק על ידי המשתמש לתרגיל המתאים מזהה, "CARDIO_RUN".

הפלאגין של Google Assistant מאפשר תצוגה מקדימה של אפליקציית המלאי המוטבעת פעולות ב-Assistant במכשיר בדיקה. בדיקת המלאי באמצעות הפלאגין באמצעות השלבים הבאים:

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