ادغام App Actions با ویجت های اندروید

برای بسیاری از اهداف، بهترین پاسخ ارائه یک پاسخ ساده، تأیید کوتاه یا تجربه تعاملی سریع به کاربر است. برای تحقق این نوع اهداف می‌توانید یک ویجت برنامه اندروید را در دستیار Google نمایش دهید.

این راهنما نحوه پاسخگویی به درخواست‌های کاربر دستیار را با استفاده از ویجت‌ها و نحوه بهبود تجربه ویجت خود را برای Assistant با کتابخانه برنامه افزودنی ابزارک‌ها پوشش می‌دهد.

مزایا

ویجت ها نماهای برنامه های کوچکی هستند که می توانند روی سطوح اندرویدی مانند لانچر یا صفحه قفل تعبیه شوند. با App Actions، با واجد شرایط ساختن ویجت‌ها برای نمایش در دستیار، تأثیر آن‌ها را افزایش می‌دهید:

1. کشف: ویجت‌ها را در پاسخ به پرسش‌های زبان طبیعی کاربران نمایش دهید.
2. تعامل: ویجت‌ها را در زمینه‌های هندزفری نمایش دهید، مانند زمانی که «دستیار» نتایج شخصی را در صفحه قفل و در Android Auto ارائه می‌کند.
3. حفظ: به کاربران اجازه دهید ویجت های نمایش داده شده در Assistant را به لانچر خود پین کنند. عملکرد پین کردن به کتابخانه افزونه ابزارک نیاز دارد.

چگونه دستیار ویجت ها را نمایش می دهد

دو روش وجود دارد که کاربران می توانند ویجت ها را در Assistant فراخوانی کنند:

• درخواست صریح ویجت با نام.
• گفتن درخواستی به دستیار که یک هدف داخلی (BII) یا هدف سفارشی پیکربندی شده برای تکمیل ویجت را راه‌اندازی می‌کند.

استناد صریح

برای فراخوانی صریح ویجت‌ها برای هر برنامه نصب‌شده، کاربران می‌توانند موارد زیر را از دستیار بپرسند:

• "Hey Google، ابزارک ExampleApp را نشان بده."
• "ابزارک ها از ExampleApp."

Assistant این ویجت ها را با مقدمه کلی نمایش می دهد: "ExampleApp می گوید، اینجا یک ویجت است." در حالی که Assistant به صورت بومی ویجت‌های درخواست شده را بدون نیاز به کار توسط توسعه‌دهنده برنامه برمی‌گرداند، این روش فراخوانی کاربر را ملزم می‌کند که اطلاعات صریحی از ویجت برای درخواست آن داشته باشد. برای ساده کردن کشف ویجت، از روش تحقق هدف که در بخش زیر توضیح داده شده است استفاده کنید.

تحقق هدف

با استفاده از ابزارک‌ها برای پاسخگویی به جستارهای زبان طبیعی که کاربران در «دستیار» انجام می‌دهند، یافتن ویجت‌های خود را آسان‌تر کنید. برای مثال، می‌توانید هر زمان که کاربر GET_EXERCISE_OBSERVATION BII را در برنامه تناسب اندام شما راه‌اندازی کرد، با پرسیدن «Hey Google، چند مایل این هفته در ExampleApp دویده‌ام؟» یک ویجت را برگردانید؟ علاوه بر ساده‌سازی اکتشاف، ادغام ویجت‌ها با App Actions این مزایا را ارائه می‌دهد:

• دسترسی به پارامتر: دستیار پارامترهای هدف استخراج شده از پرس و جوی کاربر را در ویجت شما فراهم می کند و پاسخ های متناسب را فعال می کند.
• معرفی سفارشی TTS: می توانید یک رشته تبدیل متن به گفتار (TTS) برای دستیار ارائه دهید تا هنگام نمایش ویجت شما اعلام شود.
• پین کردن ویجت: دستیار یک دکمه Add this widget را در نزدیکی ویجت شما نمایش می دهد و به کاربران اجازه می دهد به راحتی ویجت های شما را به راه اندازی خود پین کنند.

اجرای کامل ویجت

برای پیاده سازی اجرای ویجت برای اهداف خود، این مراحل را دنبال کنید:

1. با دنبال کردن مراحل توضیح داده شده در ایجاد یک ویجت ساده، یک ویجت Android را پیاده سازی کنید.
2. در فایل منبع shortcuts.xml برنامه خود، یک عنصر <app-widget> را به قابلیت خود اضافه کنید که حاوی جزئیات تکمیل و برچسب‌های <parameter> BII است. ویجت خود را برای کنترل پارامترها به روز کنید.
3. کتابخانه افزونه ابزارک مورد نیاز را اضافه کنید، که به دستیار اجازه می‌دهد نام‌ها و پارامترهای BII را به ویجت‌های شما ارسال کند. همچنین معرفی سفارشی TTS و قابلیت پین کردن ویجت را فعال می کند.

بخش زیر طرح <app-widget> را برای shortcuts.xml شرح می دهد.

طرح ویجت

عناصر <app-widget> به عنوان تکمیل در عناصر <capability> در shortcuts.xml تعریف می‌شوند. آنها به ویژگی های زیر نیاز دارند، مگر اینکه به عنوان اختیاری ذکر شود:

توضیحات طرحواره ویجت

<app-widget>

عنصر تکمیل ویجت سطح بالا.

ویژگی ها:

• android:identifier : شناسه این تکمیل. این مقدار باید در بین عناصر <app-widget> و <intent> تعریف شده در یک <capability> منحصر به فرد باشد.
• android:targetClass : نام کلاس کامل AppWidgetProvider برای مدیریت intent.

<پارامتر>

یک پارامتر BII را به مقدار intent <parameter> نگاشت می کند. می توانید برای هر عنصر <app-widget> صفر یا چند پارامتر تعریف کنید. در حین تکمیل، دستیار پارامترها را با به‌روزرسانی موارد اضافی برای نمونه ویجت به‌عنوان جفت‌های کلید-مقدار، با قالب زیر ارسال می‌کند:

• کلید: 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> در هر قابلیت استفاده کنید. این رویکرد به شما امکان می دهد یک تجربه سفارشی بر اساس ترکیبات مختلف پارامترهای ارائه شده توسط کاربران ارائه دهید. به عنوان مثال، اگر کاربر در جستار خود مکان خروجی را مشخص نکرده است، می‌توانید او را به فعالیتی در برنامه خود هدایت کنید که گزینه‌هایی را برای تنظیم مکان‌های تحویل و رها کردن نشان می‌دهد. برای اطلاعات بیشتر در مورد تعریف مقاصد بازگشتی به بخش Fallback intents مراجعه کنید.

استخراج مقادیر پارامتر

در کلاس نمونه 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>