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

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);
    }

}

توصیه های سبک TTS

از توصیه های سبک زیر برای بهینه سازی معرفی ویجت های سفارشی خود برای TTS و درخواست های نمایش داده شده استفاده کنید.

سنجاق لانچر

کتابخانه برنامه افزودنی ابزارک به دکمه افزودن این ویجت به همراه ویجت شما در Assistant نمایش داده می شود. برای فعال کردن پین کردن، تعریف گیرنده زیر را به AndroidManifest.xml اضافه کنید:

<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>

موجودی موجودی

BII هایی که از موجودی درون خطی یا موجودی وب پشتیبانی می کنند، می توانند این موجودی ها را به تکمیل ویجت شما گسترش دهند.

موجودی درون خطی

کد زیر از یک نمونه فایل shortcuts.xml یک قابلیت START_EXERCISE BII را نشان می‌دهد که برای موجودی درون خطی و تکمیل ویجت پیکربندی شده است:

<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>

در نمونه قبلی، زمانی که کاربر این قابلیت را با درخواست از Assistant فعال می‌کند، «شروع اجرا با ExampleApp»، بسته گزینه برای انجام <app-widget> شامل جفت کلید-مقدار زیر است:

• کلید = “exerciseName”
• مقدار = “RunningShortcut”

موجودی وب

کد زیر از یک نمونه فایل shortcuts.xml یک قابلیت فعال برای موجودی وب و تکمیل ویجت را نشان می دهد:

<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>

آزمایش اقدامات برنامه

برای آزمایش ابزارک‌ها در یک دستگاه فیزیکی یا مجازی، از ابزار تست اقدامات برنامه، یکی از ویژگی‌های افزونه Google Assistant برای Android Studio استفاده کنید. برای استفاده از ابزار تست، مراحل زیر را دنبال کنید:

1. دستگاه آزمایشی خود را با برنامه در حال اجرا وصل کنید.
2. در Android Studio، به Tools > App Actions > App Actions Test Tool بروید.
3. روی ایجاد پیش نمایش کلیک کنید.
4. با استفاده از Android Studio، برنامه خود را در دستگاه آزمایشی خود اجرا کنید.
5. از برنامه Assistant در دستگاه آزمایشی خود برای آزمایش App Action خود استفاده کنید. به عنوان مثال، می‌توانید چیزی مانند «Hey Google، چند مایل این هفته در ExampleApp دویده‌ام؟» بگویید.
6. رفتار برنامه خود را مشاهده کنید یا از دیباگر Android Studio استفاده کنید تا نتیجه اقدام مورد نظر را تأیید کنید.

دستورالعمل های کیفیت

این بخش الزامات کلیدی و بهترین روش‌ها را هنگام ادغام App Actions با ویجت‌ها برجسته می‌کند.

محتوا در ویجت ها

• ( الزامی ) تبلیغات را در ویجت های خود نشان ندهید.
• محتوای ویجت را کاملاً بر روی تحقق هدف متمرکز کنید. سعی نکنید چندین هدف را با یک ویجت برآورده کنید یا محتوای نامربوط اضافه کنید.

احراز هویت را کنترل کنید

• ( الزامی ) در جایی که برای تکمیل جریان کاربر به احراز هویت کاربر نیاز است، ویجتی را برگردانید که توضیح می دهد کاربر باید در برنامه ادامه دهد. احراز هویت درون خطی کاربر در Google Assistant برای App Actions پشتیبانی نمی‌شود.
• اگر کاربران به برنامه شما اجازه دهند داده‌ها را با استفاده از ویجت‌ها نشان دهد، می‌توانید ویجت خطا را در زمان اجرا برای کاربران غیرمجاز برگردانید.

مقاصد بازگشتی

• ( الزامی ) در shortcuts.xml خود، علاوه بر تکمیل ویجت خود برای یک قابلیت معین، همیشه یک <intent> بازگشتی ارائه دهید. یک هدف بازگشتی یک عنصر <intent> بدون مقادیر <parameter> لازم است.

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

• از قصد بازگشتی برای باز کردن برنامه خود در صفحه مربوطه استفاده کنید، نه صفحه اصلی.

کد زیر از یک نمونه فایل shortcuts.xml یک <capability> با یک <intent> بازگشتی نشان می دهد که از اجرای اولیه <app-widget> پشتیبانی می کند:

<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>

افشای اطلاعات گوگل پلی

این بخش داده‌های کاربر نهایی جمع‌آوری‌شده توسط آخرین نسخه کتابخانه افزونه ابزارک را فهرست می‌کند.

این SDK پاسخ‌های متن به گفتار (TTS) ارائه‌شده توسط توسعه‌دهنده را ارسال می‌کند که توسط «دستیار Google» با استفاده از فناوری گفتار «دستیار» به کاربر اعلام می‌شود. این اطلاعات توسط گوگل ذخیره نمی شود.

کنش‌های برنامه همچنین ممکن است ابرداده برنامه مشتری را برای اهداف زیر جمع‌آوری کند:

• برای نظارت بر نرخ پذیرش نسخه های مختلف SDK.
• برای تعیین کمیت استفاده از ویژگی SDK در بین برنامه ها.