ผสานรวมการดำเนินการของแอปกับวิดเจ็ต Android

วันที่

สำหรับหลายๆ ความตั้งใจ คำตอบที่ดีที่สุดคือให้คำตอบง่ายๆ ที่สรุปสั้นๆ การยืนยัน หรือประสบการณ์แบบอินเทอร์แอกทีฟสั้นๆ ให้แก่ผู้ใช้ คุณสามารถแสดง วิดเจ็ตแอป Android ใน Google Assistant เพื่อดำเนินการ Intent เหล่านี้

คู่มือนี้ครอบคลุมวิธีตอบคำถามของผู้ใช้ Assistant โดยใช้วิดเจ็ตและวิธีการ ปรับปรุงประสบการณ์การใช้งานวิดเจ็ตสำหรับ Assistant ด้วยการดำเนินการของแอป ไลบรารีส่วนขยายของวิดเจ็ต

ข้อดี

วิดเจ็ตคือมุมมองแอปพลิเคชันขนาดเล็กที่สามารถฝังใน Android เช่น Launcher หรือหน้าจอล็อก จำนวนการดำเนินการของแอปจะช่วยเพิ่ม ผลกระทบของวิดเจ็ตด้วยการทำให้วิดเจ็ตมีสิทธิ์แสดงใน Assistant ดังนี้

1. การค้นพบ: แสดงวิดเจ็ตในเชิงรุกเพื่อตอบสนองต่อผู้ใช้ คำค้นหาที่เป็นภาษาธรรมชาติ
2. การมีส่วนร่วม: แสดงวิดเจ็ตในบริบทโดยไม่ต้องสัมผัส เช่น Assistant จะแสดงผลการค้นหาเฉพาะบุคคลในหน้าจอล็อกและใน Android Auto
3. การเก็บรักษา: อนุญาตให้ผู้ใช้ปักหมุดวิดเจ็ตที่แสดงใน Assistant ไปยัง Launcher ฟังก์ชันการปักหมุดต้องใช้ ไลบรารีส่วนขยายของวิดเจ็ต

วิธีที่ Assistant แสดงวิดเจ็ต

ผู้ใช้จะเรียกใช้วิดเจ็ตใน Assistant ได้ 2 วิธีดังนี้

• การขอวิดเจ็ตด้วยชื่ออย่างชัดแจ้ง
• การพูดคำค้นหากับ Assistant ซึ่งเรียกให้แสดง Intent ในตัว (BII) หรือความตั้งใจที่กำหนดเองที่กำหนดค่าไว้สำหรับ Fulfillment วิดเจ็ต

การเรียกใช้ที่ชัดเจน

หากต้องการเรียกใช้วิดเจ็ตสำหรับแอปที่ติดตั้งแล้วอย่างชัดเจน ผู้ใช้สามารถถาม Assistant เช่น

• "Ok Google แสดงวิดเจ็ต ExampleApp"
• "วิดเจ็ตจาก ExampleApp"

Assistant แสดงวิดเจ็ตเหล่านี้พร้อมกับการแนะนำทั่วไป: "ExampleApp บอกว่า นี่วิดเจ็ต" ขณะที่ Assistant แสดงวิดเจ็ตที่ขอเข้ามาโดยอัตโนมัติ ในลักษณะนี้โดยที่นักพัฒนาแอปไม่ต้องดําเนินการใดๆ วิธีการเรียกใช้นี้ ผู้ใช้ต้องมีความรู้ที่ชัดเจนเกี่ยวกับวิดเจ็ตจึงจะขอวิดเจ็ตได้ ถึง ทำให้การค้นหาวิดเจ็ตง่ายขึ้น ให้ใช้วิธีการดำเนินการตาม Intent ที่ให้รายละเอียดไว้ใน ต่อไปนี้

การดำเนินการตาม Intent

ทำให้วิดเจ็ตของคุณหาได้ง่ายขึ้นโดยใช้วิดเจ็ตเหล่านั้นเพื่อเติมเต็มความเป็นธรรมชาติ คำค้นหาภาษาที่ผู้ใช้ค้นหาใน Assistant ตัวอย่างเช่น คุณสามารถส่งคืน เมื่อใดก็ตามที่ผู้ใช้เรียกใช้ GET_EXERCISE_OBSERVATION BII ใน แอปฟิตเนสโดยถามว่า "Ok Google ฉันวิ่งไปแล้วกี่กิโลเมตรในสัปดาห์นี้ ExampleApp ใช่ไหม" นอกจากทำให้การค้นหาง่ายขึ้นแล้ว การผสานรวมวิดเจ็ตเข้ากับ การดำเนินการของแอปมีข้อดีดังนี้

• การเข้าถึงพารามิเตอร์: Assistant จะแสดงพารามิเตอร์ความตั้งใจที่ดึงข้อมูลมา จากคำค้นหาของผู้ใช้ไปยังวิดเจ็ต คำตอบที่ปรับแต่งให้เหมาะสม
• ข้อมูลเบื้องต้นเกี่ยวกับ TTS ที่กำหนดเอง: คุณระบุสตริงการอ่านออกเสียงข้อความ (TTS) ได้ เพื่อให้ Assistant ประกาศเมื่อแสดงวิดเจ็ต
• การปักหมุดวิดเจ็ต: Assistant จะแสดงปุ่มเพิ่มวิดเจ็ตนี้ใกล้กับ วิดเจ็ตของคุณ เพื่อช่วยให้ผู้ใช้ปักหมุดวิดเจ็ตไว้ที่ Launcher ของตนได้อย่างง่ายดาย

ใช้ Fulfillment วิดเจ็ต

ทำตามขั้นตอนต่อไปนี้เพื่อใช้การดำเนินการให้สมบูรณ์วิดเจ็ตสำหรับ Intent ของคุณ

1. ใช้งานวิดเจ็ต Android โดยทำตามขั้นตอนที่อธิบายไว้ใน สร้างวิดเจ็ตที่ใช้งานง่าย
2. ในไฟล์ทรัพยากร shortcuts.xml ของแอป ให้เพิ่ม <app-widget> เอลิเมนต์ไปยังความสามารถของคุณที่มี รายละเอียดการดำเนินการตามคำสั่งซื้อและแท็ก BII <parameter> อัปเดต จัดการพารามิเตอร์
3. เพิ่มไลบรารีส่วนขยายของวิดเจ็ตที่จำเป็น ซึ่งทำให้ Assistant จะส่งชื่อและพารามิเตอร์ BII ไปยังวิดเจ็ตของคุณ และยังทำให้ บทแนะนำ TTS ที่กำหนดเอง และ การปักหมุด วิดเจ็ต

ส่วนต่อไปนี้จะอธิบายสคีมา <app-widget> สำหรับ shortcuts.xml

สคีมาของวิดเจ็ต

องค์ประกอบ <app-widget> ได้รับการกำหนดเป็นการดำเนินการภายใน องค์ประกอบ <capability> ใน shortcuts.xml โดยจำเป็นต้องมีสิ่งต่อไปนี้ เว้นแต่จะระบุว่าไม่บังคับ

คำอธิบายสคีมาของวิดเจ็ต

<วิดเจ็ตแอป>

องค์ประกอบการดำเนินการตามคำสั่งซื้อวิดเจ็ตระดับบนสุด

แอตทริบิวต์:

• android:identifier: ตัวระบุสำหรับการจำหน่ายนี้ ค่านี้ต้อง ไม่ซ้ำกันใน Fulfillment <app-widget> และ <intent> ที่กำหนดภายใน <capability>
• android:targetClass: ชื่อเต็มของชั้นเรียนของ AppWidgetProvider เพื่อ จัดการความตั้งใจ

<พารามิเตอร์>

แมปพารามิเตอร์ BII กับค่า Intent <parameter> คุณสามารถกำหนดเลข 0 หรือ พารามิเตอร์เพิ่มเติมสำหรับองค์ประกอบ <app-widget> แต่ละรายการ ระหว่างการดำเนินการตามคำสั่งซื้อ Assistant ส่งพารามิเตอร์โดยการอัปเดตเพิ่มเติมสำหรับอินสแตนซ์วิดเจ็ตเป็นคู่คีย์-ค่า โดยใช้รูปแบบต่อไปนี้

• คีย์: android:key ที่กำหนดไว้สำหรับพารามิเตอร์
• ค่า: ค่าที่ BII ดึงมาจากการป้อนข้อมูลด้วยเสียงของผู้ใช้

คุณเข้าถึงบริการเพิ่มเติมเหล่านี้ได้โดยโทรไปที่ getAppWidgetOptions() บนเครือข่ายที่เกี่ยวข้อง AppWidgetManager ซึ่งแสดงผล Bundle ที่มีชื่อของ ทริกเกอร์ BII และพารามิเตอร์ โปรดดู ดึงค่าพารามิเตอร์เพื่อดูรายละเอียด

สำหรับข้อมูลเพิ่มเติมเกี่ยวกับการจับคู่พารามิเตอร์ BII โปรดดู ข้อมูลและการจับคู่พารามิเตอร์

<เพิ่มเติม>

แท็กที่ไม่บังคับเพื่อประกาศว่ามีการใช้การแนะนำ TTS ที่กำหนดเองสำหรับ วิดเจ็ตนี้ แท็กนี้ต้องมีค่าแอตทริบิวต์ต่อไปนี้

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

โค้ดตัวอย่าง

ตัวอย่างต่อไปนี้จากไฟล์ shortcuts.xml สาธิตการใช้วิดเจ็ต การกำหนดค่าการดำเนินการตามคำสั่งซื้อสำหรับ ความสามารถ GET_EXERCISE_OBSERVATION BII:

<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> องค์ประกอบต่อความสามารถ วิธีนี้จะช่วยให้คุณ ให้ประสบการณ์ที่กำหนดเองตามชุดค่าผสมที่แตกต่างกันของพารามิเตอร์ ที่ผู้ใช้ให้ไว้ เช่น หากผู้ใช้ไม่ได้ระบุสถานที่ส่ง ในการค้นหาของผู้ใช้ คุณสามารถนำลูกค้าไปยังกิจกรรมในแอปของคุณที่แสดง ตัวเลือกสำหรับการตั้งค่าสถานที่รับและส่ง โปรดดู ส่วน Intent สำรองสำหรับข้อมูลเพิ่มเติม เกี่ยวกับการกำหนด 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>