שילוב 'פעולות באפליקציה' עם ווידג'טים של Android

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

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

יתרונות

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

1. Discovery: הצגה יזומה של ווידג'טים בתגובה למשתמשים בשאילתות בשפה טבעית (NLP).
2. מעורבות: הצגת ווידג'טים בהקשרים של הפעלה קולית, למשל כאשר Assistant מספקת תוצאות אישיות במסך הנעילה ובהפעלה Android Auto.
3. שמירה: המשתמשים יכולים להצמיד את הווידג'טים שמוצגים Assistant במרכז האפליקציות. לפונקציונליות ההצמדה נדרשת ספריית התוספים לווידג'טים.

איך Assistant מציגה ווידג'טים

יש שתי דרכים שבהן משתמשים יכולים להפעיל ווידג'טים ב-Assistant:

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

הפעלה מפורשת

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

• "Ok Google, show ExampleApp widget" (אני רוצה לראות את הווידג'ט של ExampleApp).
• "ווידג'טים מ-ExampleApp"

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

מימוש Intent

הקל על מציאת הווידג'טים שלך על ידי שימוש בהם כדי למלא את שאילתות שפה שהמשתמשים מבצעים ב-Assistant. לדוגמה, אפשר להחזיר את בכל פעם שמשתמש מפעיל את ה-BII של GET_EXERCISE_OBSERVATION אפליקציית כושר גופני כששואלים "Hey Google, כמה קילומטרים רצתי השבוע ExampleApp? " בנוסף לפישוט הגילוי, שילוב ווידג'טים עם פעולות באפליקציה מספקות את היתרונות הבאים:

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

הטמעת מילוי הזמנות בווידג'ט

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

1. כדי להטמיע ווידג'ט ל-Android, פועלים לפי השלבים שמתוארים בקטע יצירת ווידג'ט פשוט
2. בקובץ המשאבים shortcuts.xml של האפליקציה, צריך להוסיף רכיב <app-widget> ביכולת להכיל פרטי מילוי הזמנה ותגי <parameter> BII. עדכון של כדי לטפל בפרמטרים.
3. צריך להוסיף את ספריית התוספים לווידג'טים הנדרשת, שמאפשרת Assistant מעבירה שמות ופרמטרים של BII לווידג'טים. היא גם מאפשרת הקדמות TTS בהתאמה אישית והצמדת ווידג'ט החדשה.

בקטע הבא מתוארת הסכימה <app-widget> של shortcuts.xml.

סכימת הווידג'ט

רכיבי <app-widget> מוגדרים כמילוי הזמנות בתוך <capability> רכיבים ב-shortcuts.xml. הם דורשים את הדברים הבאים אלא אם צוין כאופציונלי:

תיאור הסכימה של הווידג'ט

<app-widget>

רכיב מילוי הזמנות של ווידג'ט ברמה העליונה.

מאפיינים:

• android:identifier: המזהה של מילוי ההזמנות. הערך הזה צריך להיות ייחודיים בכל מילוי ההזמנות של <app-widget> ו-<intent> שמוגדרים בתוך <capability>.
• android:targetClass: השם המלא של המחלקה בAppWidgetProvider מתוך הכוונה.

<parameter>

מיפוי פרמטר BII לערך Intent <parameter>. אפשר להגדיר את הערך אפס פרמטרים נוספים לכל רכיב <app-widget>. בתהליך מילוי ההזמנה, Assistant מעבירה פרמטרים על ידי עדכון התוספות במופע של הווידג'ט בתור צמדי מפתח-ערך, בפורמט הבא:

• מפתח: android:key שהוגדר לפרמטר.
• ערך: הערך שה-BII שולף מהקלט הקולי של המשתמש.

כדי לגשת לתוספות האלה, עליך להתקשר אל getAppWidgetOptions() אובייקט AppWidgetManager, שמחזיר Bundle שמכיל את השם של ה-BII המפעיל והפרמטרים שלו. צפייה חילוץ ערכי פרמטרים לקבלת פרטים.

למידע נוסף על התאמה לפרמטרים של BII, ראו נתוני פרמטרים והתאמה.

<extra>

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

• android:name: "hasTts"
• android:value: "true"

קוד לדוגמה

הדוגמה הבאה מקובץ shortcuts.xml ממחישה ווידג'ט הגדרת מילוי הזמנה יכולת BII של GET_EXERCISE_OBSERVATION:

<capability android:name="actions.intent.GET_EXERCISE_OBSERVATION">
  <app-widget
    android:identifier="GET_EXERCISE_OBSERVATION_1"
    android:targetClass="com.exampleapp.providers.exampleAppWidgetProvider"
    android:targetPackage="com.exampleapp">
    <parameter
      android:name="exerciseObservation.aboutExercise.name"
      android:key="exercisename">
    </parameter>
    <extra android:name="hasTts" android:value="true"/>
  </app-widget>
</capability>

אפשר לציין כמה רכיבי <app-widget> או להשתמש בשילוב של רכיבים של <app-widget> ו-<intent> לכל יכולת. הגישה הזו מאפשרת לספק חוויה מותאמת אישית שמבוססת על שילובים שונים של פרמטרים שסופקו על ידי משתמשים. למשל, אם המשתמש לא מציין מיקום נשלף בשאילתה שלהם אפשר להפנות אותם לפעילות באפליקציה שמופיעה להגדרת מיקומי האיסוף וההורדה. לצפייה הקטע כוונות חלופי מכיל מידע נוסף על הגדרה של כוונות חלופיות.

חילוץ ערכי פרמטרים

במחלקה AppWidgetProvider לדוגמה הבאה, הפונקציה הפרטית updateAppWidget() משמש לחילוץ השם והפרמטרים של ה-BII אפשרויות הווידג'ט Bundle:

package com.example.exampleapp

//... Other module imports
import com.google.assistant.appactions.widgets.AppActionsWidgetExtension

/**
 * Implementation of App Widget functionality.
 */
class MyAppWidget : AppWidgetProvider() {
    override fun onUpdate(
        context: Context,
        appWidgetManager: AppWidgetManager,
        appWidgetIds: IntArray
    ) {
        // There might be multiple widgets active, so update all of them
        for (appWidgetId in appWidgetIds) {
            updateAppWidget(context, appWidgetManager, appWidgetId)
        }
    }

    private fun updateAppWidget(
        context: Context,
        appWidgetManager: AppWidgetManager,
        appWidgetId: Int
    ) {
        val widgetText: CharSequence = context.getString(R.string.appwidget_text)

        // Construct the RemoteViews object
        val views = RemoteViews(context.packageName, R.layout.my_app_widget)
        views.setTextViewText(R.id.appwidget_text, widgetText)

        // Extract the name and parameters of the BII from the widget options
        val optionsBundle = appWidgetManager.getAppWidgetOptions(appWidgetId)
        val bii = optionsBundle.getString(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_BII) // "actions.intent.CREATE_TAXI_RESERVATION"
        val params = optionsBundle.getBundle(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_PARAMS)
        if (params != null && params.containsKey("dropoff")) {
            val dropoffLocation = params.getString("dropoff")
            // Build your RemoteViews with the extracted BII parameter
            // ...
        }
        appWidgetManager.updateAppWidget(appWidgetId, views)
    }
}

package com.example.exampleapp;

//... Other module imports
import com.google.assistant.appactions.widgets.AppActionsWidgetExtension;

/**
 * Implementation of App Widget functionality.
 */
public class MyAppWidget extends AppWidgetProvider {

    @Override
    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        // There might be multiple widgets active, so update all of them
        for (int appWidgetId : appWidgetIds) {
            updateAppWidget(context, appWidgetManager, appWidgetId);
        }
    }

    private static void updateAppWidget(Context context, AppWidgetManager appWidgetManager, int appWidgetId) {

        CharSequence widgetText = context.getString(R.string.appwidget_text);

        // Construct the RemoteViews object
        RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.my_app_widget);
        views.setTextViewText(R.id.appwidget_text, widgetText);

        // Extract the name and parameters of the BII from the widget options
        Bundle optionsBundle = appWidgetManager.getAppWidgetOptions(appWidgetId);
        String bii =
                optionsBundle.getString(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_BII); // "actions.intent.CREATE_TAXI_RESERVATION"
        Bundle params =
                optionsBundle.getBundle(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_PARAMS);

        if (params != null && params.containsKey(("dropoff"))){
            String dropoffLocation = params.getString("dropoff");
            // Build your RemoteViews with the extracted BII parameter
            // ...
        }

        appWidgetManager.updateAppWidget(appWidgetId, views);
    }
}

dependencies {
    //...
    implementation "com.google.assistant.appactions:widgets:0.0.1"
}

import com.google.assistant.appactions.widgets.AppActionsWidgetExtension

import com.google.assistant.appactions.widgets.AppActionsWidgetExtension;

package com.example.exampleapp

//... Other module imports
import com.google.assistant.appactions.widgets.AppActionsWidgetExtension

/**
 * Implementation of App Widget functionality.
 */
object MyAppWidget : AppWidgetProvider() {
    fun updateAppWidget(
        context: Context?,
        appWidgetManager: AppWidgetManager,
        appWidgetId: Int
    ) {
        val appActionsWidgetExtension = AppActionsWidgetExtension.newBuilder(appWidgetManager)
            .setResponseSpeech("Hello world") // TTS to be played back to the user
            .setResponseText("Hello world!") // Response text to be displayed in Assistant
            .build()

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

        // Update widget UI
        appWidgetManager.updateAppWidget(appWidgetId, views)
    }
}

package com.example.exampleapp;

//... Other module imports
import com.google.assistant.appactions.widgets.AppActionsWidgetExtension;

/**
 * Implementation of App Widget functionality.
 */
public class MyAppWidget extends AppWidgetProvider {

  static void updateAppWidget(Context context, AppWidgetManager appWidgetManager,
    int appWidgetId) {

    AppActionsWidgetExtension appActionsWidgetExtension = AppActionsWidgetExtension.newBuilder(appWidgetManager)
      .setResponseSpeech("Hello world")  // TTS to be played back to the user
      .setResponseText("Hello world!")  // Response text to be displayed in Assistant
      .build();

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

      // Update widget UI
      appWidgetManager.updateAppWidget(appWidgetId, views);
    }

}

<application>
  <receiver android:name="com.google.assistant.appactions.widgets.pinappwidget.PinAppWidgetBroadcastReceiver"
    android:exported="false">
    <intent-filter>
      <action android:name="com.google.assistant.appactions.widgets.COMPLETE_PIN_APP_WIDGET" />
    </intent-filter>
  </receiver>
  <service
    android:name=
    "com.google.assistant.appactions.widgets.pinappwidget.PinAppWidgetService"
    android:enabled="true"
    android:exported="true">
    <intent-filter>
      <action
        android:name="com.google.assistant.appactions.widgets.PIN_APP_WIDGET" />
    </intent-filter>
  </service>
</application>

<capability
  android:name="actions.intent.START_EXERCISE">
  <app-widget
    android:identifier="START_EXERCISE_1"
    android:targetClass="com.example.exampleapp.StartExerciseAppWidgetProvider">
    <parameter
      android:name="exercise.name"
      android:key="exerciseName"
      app:shortcutMatchRequired="true">
    </parameter>
  </app-widget>
</capability>

<shortcut android:shortcutId="RunningShortcut">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetClass="com.example.exampleapp.StartExcerciseActivity" />
  <capability-binding
    android:capability="actions.intent.START_EXERCISE"
    android:parameter="exercise.name"
    android:value="running;runs" />
</shortcut>

<shortcuts>
  <capability
    android:name="actions.intent.START_EXERCISE">
    <app-widget
      android:identifier="START_EXERCISE_1"
      android:targetClass="com.example.exampleapp.CreateTaxiAppWidgetProvider">
      <parameter
        android:name="exercise.name"
        android:key="exerciseName"
        android:mimeType="text/*">
        <data android:pathPattern="https://exampleapp.com/exercise/.*" />
      </parameter>
    </app-widget>
  </capability>
</shortcuts>

<shortcuts>
  <capability
    android:name="actions.intent.CREATE_TAXI_RESERVATION">
    <!-- Widget with required parameter, specified using the "android:required" attribute. -->
    <app-widget
      android:identifier="CREATE_TAXI_RESERVATION_1"
      android:targetClass="com.example.myapplication.CreateTaxiAppWidgetProvider">
      <parameter
        android:name="taxiReservation.dropoffLocation.name"
        android:key="dropoff"
        android:required="true">
      </parameter>
    </app-widget>
    <!-- Fallback intent with no parameters required to successfully execute. -->
    <intent
      android:identifier="CREATE_TAXI_RESERVATION_3"
      android:action="myapplication.intent.CREATE_TAXI_RESERVATION_1"
      android:targetClass="com.example.myapplication.TaxiReservationActivity">
    </intent>
  </capability>
</shortcuts>