שילוב ווידג'טים של Android עם Google Assistant

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

בCodelab הראשון בנושא פעולות באפליקציות למדתם איך להרחיב את היכולות של Google Assistant לאפליקציית כושר לדוגמה באמצעות הטמעה של כוונות מובנות (BII) מהקטגוריה 'בריאות וכושר'.

פעולות באפליקציות מאפשרות למשתמשים להפעיל ישירות תכונות ספציפיות באפליקציה מ-Assistant, באמצעות פקודות כמו Ok Google, start a run on ExampleApp (Ok Google, תתחיל ריצה באפליקציה ExampleApp). בנוסף להפעלת אפליקציות, Assistant יכול להציג למשתמש ווידג'ט אינטראקטיבי של Android כדי למלא בקשות ל-BII שעומד בדרישות.

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

מה תפַתחו

ב-codelab הזה תלמדו איך להחזיר ווידג'טים של Android כדי למלא בקשות של משתמשי Assistant. בנוסף, תלמדו:

שימוש בפרמטרים של BII של משתמשים כדי להתאים אישית ווידג'טים.
הוספת הקדמות באמצעות המרת טקסט לדיבור (TTS) לווידג'טים שלכם ב-Assistant.
אפשר להשתמש בהפניה מובנית ל-Intent כדי לקבוע אילו ממשקי BII תומכים במילוי בקשות בווידג'ט.

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

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

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

אם אתם משתמשים במכשיר פיזי, אתם צריכים לחבר אותו למכונת הפיתוח המקומית.

2. איך זה עובד

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

ב-Codelab הזה תגדירו יכולת שרושמת תמיכה ב-BII‏ GET_EXERCISE_OBSERVATION. במסגרת היכולת הזו, אתם נותנים ל-Assistant הוראה ליצור intent של Android למחלקת הווידג'ט FitActions כדי למלא בקשות ל-BII הזה. מעדכנים את המחלקה הזו כדי ליצור ווידג'ט בהתאמה אישית בשביל Assistant שיוצג למשתמש, וגם הקדמה ב-TTS בשביל Assistant שתכריז עליה.

התרשים הבא מדגים את התהליך הזה:

אפליקציית הדוגמה FitActions מכילה ווידג'ט עם מידע על אימון, שמשתמשים יכולים להוסיף למסך הבית שלהם. הווידג'ט הזה מתאים מאוד למילוי שאילתות משתמשים שמפעילות את ה-BII‏ GET_EXERCISE_OBSERVATION.

כשמשתמש מוסיף ווידג'ט למסך הבית, הווידג'ט שולח פינג ל-Broadcast Receiver במכשיר. השירות הזה מאחזר מידע על הווידג'ט מהגדרת המקלט של הווידג'ט במשאב AndroidManifest.xml של האפליקציה. הוא משתמש במידע הזה כדי ליצור אובייקט RemoteViews שמייצג את הווידג'ט.

אפליקציית הדוגמה מגדירה את ה-receiver‏ widgets.StatsWidgetProvider, שמתאים למחלקה StatsWidgetProvider:

<!-- app/src/main/AndroidManifest.xml -->

<receiver
  android:name=".widgets.StatsWidgetProvider"
  android:exported="false">
  <intent-filter>
    <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
  </intent-filter>
  <meta-data
    android:name="android.appwidget.provider"
    android:resource="@xml/stats_widget" />
</receiver>

המחלקות StatsWidgetProvider ו-StatsWidgetProvider.kt מנהלות את תהליכי יצירת האובייקטים StatsWidget. הוא מטפל באחריות הבאה:

יצירת מופעים של ווידג'טים ואכלוס שלהם בנתוני פעילות גופנית ממסד הנתונים של האפליקציה.
עיצוב נתוני האימון כדי שיהיו קלים לקריאה באמצעות formatDataAndSetWidget().
הגדרת ערכי ברירת מחדל למקרה שנתוני האימון לא זמינים, באמצעות setNoActivityDataWidget().

הוספת תמיכה ב-Assistant

ב-Codelab הזה תעדכנו את האפליקציה לדוגמה כדי לטפל בפונקציונליות של פעולות באפליקציה. מה כלול בשינויים?

הגדרת היכולת GET_EXERCISE_OBSERVATION BII להחזרת מופע של האובייקט StatsWidget.
עדכון הכיתה StatsWidget כדי להשתמש בתכונות של פעולות באפליקציה, כמו:
- שימוש בפרמטרים של BII, שמאפשרים למשתמשים לראות נתונים סטטיסטיים ספציפיים של אימון כושר על ידי אמירת פקודות כמו "Ok Google, show my run stats on ExampleApp" (אוקיי Google, הצגת נתוני הריצה שלי ב-ExampleApp).
- מספקים מחרוזות מבוא ל-TTS.
- ניהול מקרים מיוחדים, כמו כששאילתת המשתמש לא כוללת פרמטר של סוג אימון.

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

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

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

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

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

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

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

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

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

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

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

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

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

עוברים אל File > Settings (Android Studio > Preferences ב-MacOS).
בקטע Plugins (פלאגינים), עוברים אל Marketplace (חנות) ומחפשים את Google Assistant. אפשר גם להוריד ולהתקין את כלי הבדיקה באופן ידני.
מתקינים את הכלי ומפעילים מחדש את Android Studio.

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

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

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

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

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

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

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

4. הוספת פעולה באפליקציה

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

מוסיפים אלמנט capability חדש למשאב shortcuts.xml של פרויקט הדוגמה עם ההגדרה הזו:

<!-- fitnessactions/app/src/main/res/xml/shortcuts.xml -->

<capability android:name="actions.intent.GET_EXERCISE_OBSERVATION">
  <app-widget
    android:identifier="GET_EXERCISE_OBSERVATION"
    android:targetClass="com.devrel.android.fitactions.widgets.StatsWidgetProvider"
    android:targetPackage="PUT_YOUR_APPLICATION_ID_HERE">
    <parameter
      android:name="exerciseObservation.aboutExercise.name"
      android:key="aboutExerciseName"
      android:required="true">
    </parameter>
    <extra android:name="hasTts" android:value="true"/>
  </app-widget>
  <!-- Add Fallback Intent-->
</capability>

מחליפים את הערך android:targetPackage, ‏ PUT_YOUR_APPLICATION_ID_HERE, בערך הייחודי שלכם applicationId.

היכולת הזו ממפה את ה-BII‏ GET_EXERCISE_OBSERVATION אל כוונת app-widget, כך שכאשר מופעל ה-BII, הווידג'ט מופעל ומוצג למשתמש.

לפני הפעלת הווידג'ט, Assistant מחלץ פרמטרים נתמכים של BII משאילתת המשתמש. ב-codelab הזה נדרש הפרמטר exerciseObservation.aboutExercise.name של BII, שמייצג את סוג התרגיל שהמשתמש ביקש. האפליקציה תומכת בשלושה סוגי פעילות גופנית: ריצה, הליכה ורכיבה על אופניים. כדי להודיע ל-Assistant על הערכים הנתמכים האלה, אתם צריכים לספק מלאי שטחי פרסום מוטמע.

כדי להגדיר את רכיבי המלאי האלה, מוסיפים את ההגדרה הבאה מעל היכולת GET_EXERCISE_OBSERVATION אל shortcuts.xml:

<!-- shortcuts.xml -->

<!-- shortcuts are bound to the GET_EXERCISE_OBSERVATION capability and
     represent the types of exercises supported by the app. -->

<shortcut
  android:shortcutId="running"
  android:shortcutShortLabel="@string/activity_running">
  <capability-binding android:key="actions.intent.GET_EXERCISE_OBSERVATION">
    <parameter-binding
      android:key="exerciseObservation.aboutExercise.name"
      android:value="@array/runningSynonyms"/>
  </capability-binding>
</shortcut>

<shortcut
  android:shortcutId="walking"
  android:shortcutShortLabel="@string/activity_walking">
  <capability-binding android:key="actions.intent.GET_EXERCISE_OBSERVATION">
    <parameter-binding
      android:key="exerciseObservation.aboutExercise.name"
      android:value="@array/walkingSynonyms"/>
  </capability-binding>
</shortcut>

<shortcut
  android:shortcutId="cycling"
  android:shortcutShortLabel="@string/activity_cycling">
  <capability-binding android:key="actions.intent.GET_EXERCISE_OBSERVATION">
    <parameter-binding
      android:key="exerciseObservation.aboutExercise.name"
      android:value="@array/cyclingSynonyms"/>
  </capability-binding>
</shortcut>

<capability android:name="actions.intent.GET_EXERCISE_OBSERVATION">
  <!-- ... -->
</capability>

הוספת כוונה חלופית

אובייקטים מסוג Fallback Intent מטפלים במצבים שבהם אי אפשר למלא בקשה של משתמש כי חסרים בשאילתה פרמטרים שנדרשים ליכולת. היכולת GET_EXERCISE_OBSERVATION דורשת את הפרמטר exerciseObservation.aboutExercise.name, שמוגדר על ידי המאפיין android:required="true". במקרים כאלה, כדי שהבקשה תאושר, צריך להגדיר ב-Assistant כוונת גיבוי, גם אם לא צוינו פרמטרים בשאילתה.

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

<!-- shortcuts.xml -->

<capability android:name="actions.intent.GET_EXERCISE_OBSERVATION">

  <app-widget>
    <!-- ... -->
  </app-widget>

  <!-- Fallback intent with no parameters needed to successfully execute.-->
  <intent
    android:identifier="GET_EXERCISE_OBSERVATION_FALLBACK"
    android:action="android.intent.action.VIEW"
    android:targetClass="com.devrel.android.fitactions.widgets.StatsWidgetProvider">
  </intent>
</capability>

בהגדרת הדוגמה הזו, מילוי הבקשה החלופי הוא intent של Android ללא פרמטרים בנתוני Extra שלו.

5. הפעלת הווידג'ט של Assistant

אחרי שיוצרים את היכולת GET_EXERCISE_OBSERVATION, מעדכנים את מחלקת הווידג'ט כדי לתמוך בהפעלה קולית של פעולות באפליקציה.

הוספת ספריית הווידג'טים

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

מוסיפים את התלות של ספריית Widgets Extension למשאב של אפליקציית הדוגמה /app/build.gradle:
```
// app/build.gradle

dependencies {
  //...
  implementation "com.google.assistant.appactions:widgets:0.0.1"
}
```
לוחצים על סנכרון עכשיו בתיבת האזהרה שמופיעה ב-Android Studio. סנכרון אחרי כל שינוי עוזר למנוע שגיאות כשמפתחים את האפליקציה.build.gradle

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

מוסיפים שירות למשאב AndroidManifest.xml של אפליקציית הדוגמה עם ההגדרה הזו:

<!-- AndroidManifest.xml -->
<service
   android:name=".widgets.StatsWidgetProvider"
   android:enabled="true"
   android:exported="true">
   <intent-filter>
       <action
           android:name="com.google.assistant.appactions.widgets.PIN_APP_WIDGET" />
   </intent-filter>
</service>

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

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

פותחים את הכיתה StatsWidget.kt ומייבאים את ספריית התוסף של פעולות באפליקציה לווידג'ט:
```
// StatsWidget.kt

// ... Other import statements
import com.google.assistant.appactions.widgets.AppActionsWidgetExtension
```

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

// StatsWidget.kt

private val hasBii: Boolean
private val isFallbackIntent: Boolean
private val aboutExerciseName: String
private val exerciseType: FitActivity.Type

מוסיפים את הפונקציה init כדי לאפשר לכיתה להשתמש בנתוני האפשרויות של הווידג'ט שמועברים מ-Assistant:

// StatsWidget.kt

init {
  val optionsBundle = appWidgetManager.getAppWidgetOptions(appWidgetId)
  val bii = optionsBundle.getString(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_BII)
  hasBii = !bii.isNullOrBlank()
  val params = optionsBundle.getBundle(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_PARAMS)

  if (params != null) {
    isFallbackIntent = params.isEmpty
    if (isFallbackIntent) {
      aboutExerciseName = context.resources.getString(R.string.activity_unknown)
    } else {
        aboutExerciseName = params.get("aboutExerciseName") as String
      }
  } else {
      isFallbackIntent = false
      aboutExerciseName = context.resources.getString(R.string.activity_unknown)
  }
  exerciseType = FitActivity.Type.find(aboutExerciseName)
}

במאמר הזה נסביר איך העדכונים האלה מאפשרים למחלקה StatsWidget.kt להגיב ל-intents של Android שנוצרו על ידי היכולת GET_EXERCISE_OBSERVATION:

‫optionsBundle = Bundle
- חבילות הן אובייקטים שמיועדים לשימוש בגבולות של תהליכים, בין פעילויות עם כוונות, ולאחסון מצב זמני בשינויים בהגדרות. ה-Assistant משתמש באובייקטים Bundle כדי להעביר נתוני הגדרה לווידג'ט.
bii = actions.intent.GET_EXERCISE_OBSERVATION
- השם של ה-BII זמין מהחבילה באמצעות AppActionsWidgetExtension.
hasBii = true
- בודקת אם יש BII.
params = Bundle[{aboutExerciseName=running}]
- חבילה מיוחדת שנוצרת על ידי פעולות באפליקציה מוטמעת באפשרויות הווידג'ט Bundle. הוא מכיל את צמדי המפתח/ערך של ה-BII. בדוגמה הזו, הערך running חולץ משאילתת הדוגמה "Ok Google, show my running stats on ExampleApp".
isFallbackIntent = false
- בודק אם פרמטרים נדרשים של BII קיימים בכוונת המשתמש Extras.
aboutExerciseName = running
- הפונקציה מחזירה את ערך הכוונה Extras של aboutExerciseName.
exerciseType = RUNNING
- הפונקציה משתמשת ב-aboutExerciseName כדי לחפש את אובייקט סוג מסד הנתונים המתאים.

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

ב-StatsWidget.kt, מחליפים את הפונקציה updateAppWidget() בקוד הבא:

// StatsWidget.kt

fun updateAppWidget() {
   /**
    * Checks for App Actions BII invocation and if BII parameter data is present.
    * If parameter data is missing, use data from last exercise recorded to the
    *  fitness tracking database.
    */
   if (hasBii && !isFallbackIntent) {
       observeAndUpdateRequestedExercise()
   } else observeAndUpdateLastExercise()
}

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

מוסיפים את הפונקציה observeAndUpdateRequestedExercise עם הקוד הזה:

// StatsWidget.kt

/**
* Create and observe the last exerciseType activity LiveData.
*/
private fun observeAndUpdateRequestedExercise() {
  val activityData = repository.getLastActivities(1, exerciseType)

   activityData.observeOnce { activitiesStat ->
       if (activitiesStat.isNotEmpty()) {
           formatDataAndSetWidget(activitiesStat[0])
           updateWidget()
       } else {
           setNoActivityDataWidget()
           updateWidget()
       }
   }
}

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

הפעלת TTS

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

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

ב-StatsWidget.kt, מוסיפים את הקוד הזה לפונקציה formatDataAndSetWidget:

// StatsWidget.kt

private fun formatDataAndSetWidget(
  activityStat: FitActivity,
) {
      // ...

      // Add conditional for hasBii for widget with data
      if (hasBii) {
         // Formats TTS speech and display text for Assistant
         val speechText = context.getString(
             R.string.widget_activity_speech,
             activityExerciseTypeFormatted,
             formattedDate,
             durationInMin,
             distanceInKm
         )
         val displayText = context.getString(
             R.string.widget_activity_text,
             activityExerciseTypeFormatted,
             formattedDate
         )
         setTts(speechText, displayText)
      }
}

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

מוסיפים את הפונקציה החדשה setTts ל-StatsWidget.kt באמצעות הקוד הזה:

// StatsWidget.kt

/**
 * Sets TTS to widget
 */
private fun setTts(
  speechText: String,
  displayText: String,
) {
  val appActionsWidgetExtension: AppActionsWidgetExtension =
      AppActionsWidgetExtension.newBuilder(appWidgetManager)
        .setResponseSpeech(speechText)  // TTS to be played back to the user
        .setResponseText(displayText)  // Response text to be displayed in Assistant
        .build()

  // Update widget with TTS
  appActionsWidgetExtension.updateWidget(appWidgetId)
}

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

מעדכנים את הפונקציה setNoActivityDataWidget() בקובץ StatsWidget.kt באמצעות הקוד הבא:

// StatsWidget.kt

private fun setNoActivityDataWidget() {
  // ...
  // Add conditional for hasBii for widget without data
  if (hasBii) {
    // formats speech and display text for Assistant
    // https://developers.google.com/assistant/app/widgets#library
    val speechText =
      context.getString(R.string.widget_no_activity_speech, aboutExerciseName)
    val displayText =
      context.getString(R.string.widget_no_activity_text)

    setTts(speechText, displayText)
  }
}

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

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

יצירת קטע מקדים

כדי לבדוק את פעולת האפליקציה באמצעות הפלאגין:

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

בדיקת סוג אימון צפוי

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

בשלב הראשון שבו הכלי מבקש לבחור ולהגדיר BII, בוחרים באפשרות actions.intent.GET_EXERCISE_OBSERVATION.
בתיבה exerciseObservation, מעדכנים את שם התרגיל שמוגדר כברירת מחדל מ-climbing ל-run.
לוחצים על הפעלת פעולת אפליקציה.

בדיקת סוג אימון לא צפוי

כדי לבדוק סוג תרגיל לא צפוי בכלי הבדיקה:

בתיבה exerciseObservation, מעדכנים את הערך name מ-Run ל-Climbing.
לוחצים על הפעלת פעולת אפליקציה.

‫Assistant אמורה להחזיר ווידג'ט עם המידע 'לא נמצאה פעילות'.

בדיקת כוונת ברירת המחדל

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

כדי לבדוק את ה-Intent החלופי:

בתיבה exerciseObservation, מוחקים את האובייקט aboutExercise.
לוחצים על הפעלת פעולת אפליקציה.

‫Assistant צריך להחזיר ווידג'ט עם מידע על התרגיל האחרון שהושלם.

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

מעולה!

עכשיו אתם יכולים להשתמש בווידג'ט של Android עם Assistant כדי למלא את השאילתות של המשתמשים.

מה נכלל

ב-Codelab הזה למדתם איך:

מוסיפים ווידג'ט של אפליקציה ל-BII.
משנים ווידג'ט כדי לגשת לפרמטרים מ-Android Extras.

המאמרים הבאים

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

הנה כמה הצעות למידע נוסף על הרחבת האפליקציה באמצעות פעולות באפליקציה:

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

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

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

כדי להתעדכן בהודעות האחרונות שלנו, אתם יכולים לעקוב אחרינו ב-Twitter‏ @ActionsOnGoogle. כדי לשתף את מה שיצרתם, אתם יכולים לצייץ עם ההאשטאג #appactions.

סקר משוב

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