הרחבה של אפליקציה ל-Android ל-Google Assistant באמצעות פעולות באפליקציה (רמה 2)

1. סקירה כללית

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

ב-first App Actions Codelab, למדתם איך להרחיב את Google Assistant לאפליקציית כושר לדוגמה על ידי הטמעת Intents מובנים (BII) מקטגוריית Health and Fitness BII. יומני BII מאורגנים בקטגוריות שמייצגות את סוגי המשימות שמשתמשים מבקשים מ-Assistant לבצע בדרך כלל.

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

ב-Codelab הזה, נלמד איך להוסיף 'פעולות באפליקציה' לאפליקציה באמצעות BII ממודל משותף (Common)" קטגוריית BII, שמייצגת משימות נפוצות באפליקציה שכמעט כל אפליקציה ל-Android יכולה לבצע.

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

מה תפַתחו

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

• עוברים אל תכונות באפליקציה באמצעות ממשק BII של actions.intent.OPEN_APP_FEATURE.
• לחפש תוכן באמצעות חיפוש בתוך האפליקציה בעזרת actions.intent.GET_THING BII.

הערה: אפליקציות עם פונקציונליות חיפוש נדרשות כדי להטמיע את ה-BII של actions.intent.GET_THING. מידע נוסף על דרישות הפריסה של 'פעולות באפליקציה'

איור 1. שלושה מסכים הדרגתיים שבהם Google Assistant מציגה משימות פעילות באפליקציה.

מה תלמדו

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

דרישות מוקדמות

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

הערה: ניתן לבדוק את הפעולות באפליקציה שמתוארות ב-Codelab הזה באמצעות Google Assistant במספר מוגבל של לוקאלים. במסמכי העזר של Common BII תוכלו למצוא פירוט של הכוונות (Intent) הזמינות לפי לוקאל.

ב-Codelab הזה משתמשים במכשיר Android (פיזי או וירטואלי) כדי לבדוק את הפעולות. אם משתמשים במכשיר פיזי, צריך לוודא שהוא מחובר למכונת הפיתוח המקומית. אתם צריכים גם להיכנס לאפליקציית Google במכשיר ולהיכנס ל-Android Studio באמצעות אותו חשבון Google. בנוסף, אפליקציית Google Assistant צריכה להיות מותקנת במכשיר.

2. איך זה עובד

פעולות באפליקציה מחברות בין משתמשים מ-Google Assistant לאפליקציה ל-Android. אבל איך הם פועלים?

כשמשתמש מציין ל-Assistant שהוא רוצה להשתמש באפליקציה שלכם, Assistant מחפשת פעולות באפליקציה שנרשמו באפליקציה מקובץ shortcuts.xml. הקובץ הזה מכיל את היכולות של האפליקציה, שמקושרות בין כוונה מובנית של Assistant או בהתאמה אישית עם כוונת רכישה לבין כוונת רכישה או קישור עומק ב-Android.

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

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

בתרשים הבא מוצג התהליך הזה של Assistant:

איור 2. תהליך שמתאר איך Google Assistant מעבדת שאילתה קולית.

קובץ הפרויקט shortcuts.xml מכיל את הפרטים הבאים לגבי כל פעולה באפליקציה:

• המאפיינים המובנים של כוונת רכישה או קהלים בהתאמה אישית עם כוונת רכישה, במסגרת הפעולה באפליקציה
• איזה פעילות ב-Android או קישור עומק צריך לספק למשתמש
• איך פרמטרים של ה-Intent המובנה ממופים למידע שהמשתמש סיפק ל-Assistant

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

3. הכנת סביבת הפיתוח

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

הורדת הקבצים הבסיסיים

מריצים את הפקודה הבאה כדי לשכפל את מאגר GitHub של האפליקציה לדוגמה:

git clone --branch codelab-start https://github.com/actions-on-google/appactions-common-biis-kotlin.git

אחרי שמשכפלים את המאגר, פועלים לפי השלבים הבאים כדי לפתוח אותו ב-Android Studio:

1. בתיבת הדו-שיח תחילת העבודה ב-Android Studio לוחצים על ייבוא פרויקט.
2. מוצאים את התיקייה שבה שכפולם את המאגר ובוחרים בה.

כדי לראות גרסה של האפליקציה שמייצגת את ה-Codelab שהושלמה, צריך לשכפל את מאגר האפליקציה לדוגמה באמצעות הדגל --branch master.

עדכון המזהה של האפליקציה ל-Android

עדכון מזהה האפליקציה של האפליקציה משמש לזיהוי ייחודי של האפליקציה במכשיר הבדיקה ולמניעת 'שם חבילה כפול'. שגיאה אם האפליקציה הועלתה ל-Play Console. כדי לעדכן את מזהה האפליקציה, פותחים את app/build.gradle:

android {
...
  defaultConfig {
    applicationId "com.MYUNIQUENAME.android.fitactions"
    ...
  }
}

מחליפים את "MYUNIQUENAME" בשדה applicationId למשהו ייחודי לך.

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

בדיקת האפליקציה במכשיר

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

1. ב-Android Studio, בוחרים באפשרות הפעלה > אפשר להפעיל את האפליקציה או ללחוץ על הפעלה בסרגל הכלים.
2. בתיבת הדו-שיח Select Deployment Target בוחרים מכשיר ולוחצים על OK. הגרסה המומלצת של מערכת ההפעלה היא Android 10 (רמת API 30) ואילך, אבל הפעולות פועלות במכשירים בגרסת Android 5 (רמת API 21).
3. כדי להגדיר את Assistant ולאמת שהיא פועלת, לוחצים לחיצה ארוכה על הלחצן דף הבית. אם עדיין לא עשית זאת, יהיה עליך להיכנס אל Assistant במכשיר שלך.

מידע נוסף על מכשירים וירטואליים של Android זמין במאמר יצירה וניהול של מכשירים וירטואליים.

איור 3. אנימציה שמדגימה את האפליקציה לדוגמה של רשימת המשימות.

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

התקנת הפלאגין לבדיקה

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

1. עוברים אל קובץ > 'הגדרות' (Android Studio > העדפות ב-MacOS).
2. בקטע 'יישומי פלאגין', עוברים אל Marketplace ומחפשים את 'Google Assistant'. אפשר גם להוריד באופן ידני ולהתקין את כלי הבדיקה.
   • אם לא מוצאים את הפלאגין ב-Marketplace, מורידים את הפלאגין באופן ידני ופועלים לפי ההוראות במאמר התקנת הפלאגין מהדיסק.
3. מתקינים את הכלי ומפעילים מחדש את Android Studio.

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

4. הוספת היכולת של Get Thing BII

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

טיפ: ממשק BII של GET_THING משמש לחיפוש תוכן או ישויות באמצעות תכונת החיפוש בתוך האפליקציה שמוגדרת כברירת מחדל. מאכלסים את קריטריוני החיפוש עם שם התוכן או שם הישות באמצעות הפרמטר thing.name של Intent, ומציגים למשתמש את תוצאות החיפוש הרלוונטיות ביותר.

הגדרת היכולת של Get Thing

במהלך פעולה באפליקציה שקשורה לחיפוש, Assistant מחלצת מונחי חיפוש משאילתת המשתמש לפרמטר ה-BII thing.name ואז מעבירה את הערך הזה לאפליקציה ל-Android.

כדי להוסיף את ה-BII GET_THING לאפליקציה, צריך לעדכן את ה-shortcuts.xml, שנמצא בספריית הפרויקטים לדוגמה app/src/main/res/xml, עם הרכיב <capability> בתוך התג <shortcuts> ברמה העליונה:

shortcuts.xml

<shortcuts ....>
    <capability android:name="actions.intent.GET_THING">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.yourApplicationId.appaction"
            android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
            <parameter
                android:name="thing.name"
                android:key="q"/>
        </intent>
    </capability>
</shortcuts>

ההגדרות האישיות שלמעלה:

1. הצהרה שהאפליקציה מגיבה ל-BII של GET_THING.
2. מציינת איך לפתח Intent ב-Android שמפעיל את האפליקציה בתגובה לאותו BII.
   • הפעילות מזוהה באמצעות targetPackage ו-targetClass.
   • פרמטר ה-BII thing.name ממופה אל ה-Intent Extra בשם q.

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

אפליקציית Android שסופקה מכילה מטא-נתונים כך שה-AndroidManifest מודע לקובץ shortcuts.xml:

<meta-data
   android:name="android.app.shortcuts"
   android:resource="@xml/shortcuts" />

בדיקת הפעולה באפליקציה

כדי לבדוק את החיפוש מתוך האפליקציה באמצעות Assistant, יש לפעול לפי השלבים הבאים:

1. מוודאים שמכשיר Android מחובר.
2. עוברים אל כלים > Google Assistant > כלי הבדיקה של פעולות באפליקציה.
3. לוחצים על יצירת תצוגה מקדימה כדי לאשר את ערכי ברירת המחדל של שם האפליקציה והלוקאל. אם מופיעה בקשה, קוראים את המדיניות ואת התנאים וההגבלות של 'פעולות באפליקציה' ומאשרים אותם.
4. בשלב הראשון, שבו הכלי יבקש מכם לבחור ולהגדיר את ה-BII, צריך לבחור באפשרות actions.intent.GET_THING. משנים את הערך של המאפיין name מ-running shoes ל-milk.
5. לוחצים על Run App Action (הפעלת פעולה באפליקציה).

בבדיקה הזו, ה-BII GET_THING משתמש במאפיין name כדי לחפש באפליקציה משימות שמכילות 'חלב'. בדומה לפעולה הקודמת באפליקציה, אתם יכולים לבדוק את הפעולה באמצעות כלי הבדיקה או פשוט לומר במכשיר הבדיקה "Ok Google, search for chocolate music in Task List" (חיפוש מיקס עוגה ברשימת המשימות).

טיפ: אם נתקלתם בבעיות בהפעלת כלי הבדיקה, כדאי לעיין במדריך לפתרון בעיות.

5. הוספת יכולת ה-BII של התכונה 'פתיחת האפליקציה'

בשלב הזה אתם מטמיעים את ה-BII של התכונה 'פתיחת האפליקציה', וכך המשתמשים יוכלו לראות באמצעות Assistant את המשימות הפעילות והמשימות שלהם. כדי לעשות זאת, צריך להשלים את היכולת ב-shortcuts.xml שמכילה מידע על אופן ההפעלה של היכולת, איך פרמטרים מועברים ואילו Intents של Android להפעיל. ב-Codelab הזה משתמשים ב-BII של OPEN_APP_FEATURE. לאחר הטמעת ה-BII הזה, עליכם לבדוק את הפעולה במכשיר.

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

הוספת היכולת של 'פתיחת האפליקציה'

מוסיפים יכולת שנייה לתכונה 'פתיחת האפליקציה' ב-shortcuts.xml מתחת לרכיב Get Thing Capability:

shortcuts.xml

<capability android:name="actions.intent.OPEN_APP_FEATURE">
   <intent
       android:action="android.intent.action.VIEW"
       android:targetPackage="yourApplicationId"
       android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
       <parameter
           android:name="feature"
           android:key="feature"/>
   </intent>
</capability>

היכולת הזו ממפה את התכונה BII של פתיחת האפליקציה ו-Intent של Android יחד, כך שכאשר התכונה 'פתיחת האפליקציה' מופעלת, תופעל Intent ב-Android.

לפני שמפעילים את ה-Intent ב-Android, הפרמטרים הנתמכים נשלפים מהקלט של המשתמש. ה-BII OPEN_APP_FEATURE תומך בפרמטר אחד, feature, שמייצג את תכונת האפליקציה שחולצה משאילתת המשתמש. האפליקציה הזו תתמוך בשני סוגים של תכונות: Active Task ו-Complete Task. התכונות האלה מאפשרות למשתמשים לפתוח את האפליקציה באמצעות תצוגה מסוננת של רשימת המשימות שלהם. כדי לתמוך בתכונות האלה צריך להשתמש במלאי שטחי פרסום מוטבע.

מונח מפתח: מלאי שטחי פרסום מוטבע מנחה את תהליך החילוץ של ישויות מ-BII באמצעות קבוצת ישויות שהאפליקציה מבינה לפרמטר BII שתומך במלאי שטחי פרסום מוטבע. לפרטים נוספים אפשר לעיין במאמר בנושא מלאי שטחי פרסום מוטבע עבור פעולות באפליקציה.

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

פרמטרים של Intent מייצגים את הרכיבים שחולצו משאילתת משתמש. לדוגמה, אם משתמש אומר משהו כמו "Ok Google, order a פיצה מ-ExampleApp", Assistant מחלצת את המילה 'פיצה'. לפרמטר Intent מסוג food.item schema.org, ומעביר את הפרמטר לפעולה שלכם כדי לטפל בה.

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

כדי לטפל בפרמטר feature של Intent, צריך להוסיף קיצור דרך אל shortcuts.xml עם הקוד הבא מעל היכולת של התכונה 'פתיחת האפליקציה':

shortcuts.xml

<shortcut
   android:shortcutId="active_tasks"
   android:shortcutShortLabel="@string/label_active"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/active_tasks_synonyms" />
   </capability-binding>
</shortcut>

<shortcut
   android:shortcutId="completed_tasks"
   android:shortcutShortLabel="@string/label_completed"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/completed_tasks_synonyms" />
   </capability-binding>
</shortcut>

בקוד שלמעלה הגדרת מלאי מוטבע, שמיוצג כרכיבי shortcut עם קישורי יכולות ופרמטרים. ניתן להשתמש בקיצורי דרך כמלאי לפרמטרים של BII. Google Assistant מתאימה את שאילתת המשתמש לערכים שבקישור הפרמטרים של קיצורי הדרך. אם הערך של הפרמטר תואם, הערך shortcutId יתווסף ל-Intent של מילוי הבקשות. כשמשתמש מפעיל את ה-BII של OPEN_APP_FEATURE באמצעות בקשה, Assistant מתאימה את ערך הפרמטר של התכונה למאפיין הערך של קיצור הדרך, ומעבירה את הערך ל-targetClass כ-parameter ב-Extra.

לדוגמה, אם משתמש אומר משהו כמו "Ok Google, show my completed tasks in ExampleApp", Assistant תתאים לערך הפרמטר של Intent התכונה, "משימות שהושלמו", לקיצור הדרך התואם של מלאי שטחי הפרסום, שמעביר את הערך הזה ליכולת OPEN_APP_FEATURE. לאחר מכן Assistant מפעילה את ה-Intent ב-Android.

בדיקת הפעולה באפליקציה

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

כדי לבדוק את הפעולה באפליקציה באמצעות כלי הבדיקה, פועלים לפי השלבים הבאים:

1. מחברים את מכשיר הבדיקה הפיזי של Android או מפעילים אמולטור של Android
2. אם כלי הבדיקה לא מוצג, פותחים אותו דרך כלים > Google Assistant > כלי הבדיקה של פעולות באפליקציה.
3. לוחצים על הלחצן עדכון כדי לרענן את התצוגה המקדימה.
4. בשלב הראשון, שבו הכלי יבקש מכם לבחור ולהגדיר את ה-BII, צריך לבחור באפשרות actions.intent.OPEN_APP_FEATURE.
5. בתיבה התכונה, מעדכנים את ערך ברירת המחדל של History באמצעות Completed tasks.
6. לוחצים על Run App Action (הפעלת פעולה באפליקציה).

טיפ: אם נתקלתם בבעיות בהפעלת כלי הבדיקה, כדאי לעיין במדריך לפתרון בעיות.

לחלופין, אפשר להשתמש בשם ההפעלה ישירות באפליקציית Assistant במכשיר כדי לנסות את הפעולה באפליקציה. לדוגמה, אפשר לבקש "Hey Google, show completed tasks in Task List".

6. השלבים הבאים

מזל טוב!

עכשיו יש לכם את היכולת לאפשר כמעט לכל אפליקציה ל-Android לעבוד עם Google Assistant באמצעות ממשקי BII נפוצים.

אילו נושאים דיברנו?

ב-Codelab הזה למדת:

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

מה השלב הבא?

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

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

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

כדי להמשיך בתהליך שלך ב-Actions on Google, כדאי לעיין במקורות המידע הבאים:

• developers.google.com/assistant: אתר המסמכים הרשמי של Actions on Google.
• אינדקס לדוגמה של פעולות באפליקציה: אפליקציות וקוד לדוגמה לצורך התנסות ביכולות של 'פעולות באפליקציה'.
• פעולות במאגר GitHub של Google: קוד וספריות לדוגמה.
• r/GoogleAssistantDev: הקהילה הרשמית של Reddit למפתחים שעובדים עם Google Assistant.

אפשר לעקוב אחרינו ב- Twitter @ActionsOnGoogle כדי להתעדכן בהכרזות האחרונות, ולשלוח ציוץ אל #AoGDevs כדי לשתף את מה שיצרתם!

סקר משוב

לסיום, נמלא את הסקר הזה כדי לשלוח משוב על החוויה שלך עם Codelab.