ابزارک های اندروید را با دستیار گوگل ادغام کنید

1. بررسی اجمالی

در اولین نرم‌افزار App Actions ، یاد گرفتید که چگونه Google Assistant را به یک نمونه برنامه تناسب اندام با پیاده‌سازی اهداف داخلی (BII) از دسته Health and Fitness BII گسترش دهید.

App Actions به کاربران اجازه می‌دهد مستقیماً با ویژگی‌های خاص برنامه از Assistant راه‌اندازی کنند و چیزهایی مانند « Hey Google, start a run on ExampleApp» را بپرسند. علاوه بر راه‌اندازی برنامه‌ها، دستیار می‌تواند یک ویجت تعاملی اندروید را برای انجام درخواست‌های BII واجد شرایط به کاربر نمایش دهد.

صفحه‌ای که دستیار را نشان می‌دهد که ویجتی را در پاسخ به یک درخواست کاربر نشان می‌دهد که قابلیت GET_EXERCISE_OBSERVATION BII برنامه را فعال کرده است.

چیزی که خواهی ساخت

در این کد لبه، یاد می گیرید که چگونه ویجت های اندروید را برای انجام درخواست های کاربران دستیار برگردانید. همچنین یاد می گیرید که:

  • پارامترهای BII کاربر برای شخصی سازی ویجت ها.
  • برای ویجت‌های خود مقدمه‌های تبدیل متن به گفتار (TTS) را در Assistant ارائه دهید.
  • برای تعیین اینکه کدام BII از تکمیل ویجت پشتیبانی می کند، از مرجع Intent داخلی استفاده کنید.

پیش نیازها

قبل از ادامه، مطمئن شوید که محیط توسعه شما برای توسعه App Actions آماده است. باید داشته باشد:

  • یک ترمینال برای اجرای دستورات شل، با نصب git.
  • آخرین نسخه پایدار اندروید استودیو .
  • یک دستگاه اندروید فیزیکی یا مجازی با دسترسی به اینترنت.
  • یک حساب Google که به Android Studio، برنامه Google و برنامه Google Assistant وارد شده است.

اگر از یک دستگاه فیزیکی استفاده می کنید، آن را به دستگاه توسعه محلی خود وصل کنید.

2. درک کنید که چگونه کار می کند

دستیار Google از درک زبان طبیعی (NLU) برای خواندن درخواست کاربر و مطابقت آن با هدف داخلی دستیار (BII) استفاده می کند. سپس Assistant هدف را به قابلیت (که BII را پیاده‌سازی می‌کند) ترسیم می‌کند، که شما برای آن هدف در برنامه خود ثبت می‌کنید. در نهایت، Assistant با نمایش ویجت اندرویدی که برنامه شما با استفاده از جزئیات موجود در قابلیت تولید می کند، درخواست کاربر را برآورده می کند.

در این کد لبه، شما قابلیتی را تعریف می کنید که پشتیبانی از GET_EXERCISE_OBSERVATION BII را ثبت می کند. در این قابلیت، شما به Assistant دستور می‌دهید که یک intent Android برای کلاس ویجت FitActions ایجاد کند تا درخواست‌های این BII را برآورده کند. شما این کلاس را به‌روزرسانی می‌کنید تا یک ویجت شخصی‌سازی شده برای دستیار ایجاد کنید تا به کاربر نمایش داده شود، و یک مقدمه TTS برای دستیار برای اعلام آن.

نمودار زیر این جریان را نشان می دهد:

نمودار جریانی که تکمیل ویجت دستیار را نشان می دهد.

ویجت FitActions

برنامه نمونه FitActions حاوی ویجت اطلاعات تمرینی است که کاربران می توانند آن را به صفحه اصلی خود اضافه کنند. این ویجت یک کاندید عالی برای پاسخگویی به درخواست های کاربر است که GET_EXERCISE_OBSERVATION BII را راه اندازی می کند.

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

وقتی کاربر ویجتی را به صفحه اصلی اضافه می‌کند، ویجت به گیرنده پخش دستگاه پینگ می‌زند. این سرویس اطلاعات مربوط به ویجت را از تعریف گیرنده ویجت در منبع AndroidManifest.xml برنامه بازیابی می کند. از این اطلاعات برای تولید یک شی RemoteViews که نشان دهنده ویجت است استفاده می کند.

برنامه نمونه widgets.StatsWidgetProvider گیرنده را تعریف می‌کند.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() .

پشتیبانی از دستیار را اضافه کنید

در این لبه کد، برنامه نمونه را برای مدیریت عملکرد App Actions به روز می کنید. این تغییرات عبارتند از:

  1. پیکربندی قابلیت GET_EXERCISE_OBSERVATION BII برای برگرداندن نمونه ای از شی StatsWidget .
  2. به‌روزرسانی کلاس StatsWidget برای استفاده از ویژگی‌های App Actions مانند:
    • با استفاده از پارامترهای BII، به کاربران این امکان را می‌دهد تا با پرسیدن مواردی مانند «Hey Google، آمار اجراهای من را در ExampleApp نشان بده»، آمار تمرینی خاص را مشاهده کنند.
    • ارائه رشته های معرفی TTS.
    • مدیریت موارد خاص، مانند زمانی که درخواست کاربر شامل پارامتر نوع تمرین نیست.

3. محیط توسعه خود را آماده کنید

فایل های پایه خود را دانلود کنید

این دستور را برای کلون کردن مخزن GitHub نمونه برنامه اجرا کنید:

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

پس از کلون کردن مخزن، مراحل زیر را برای باز کردن آن در Android Studio دنبال کنید:

  1. در گفتگوی خوش آمدید به Android Studio ، روی وارد کردن پروژه کلیک کنید.
  2. پوشه ای را که مخزن را در آن کلون کرده اید، پیدا کرده و انتخاب کنید.

برای دیدن نسخه‌ای از برنامه که نشان‌دهنده لبه کد تکمیل‌شده است، مخزن نمونه برنامه را با استفاده از پرچم --branch master کلون کنید.

شناسه برنامه اندروید را به روز کنید

به‌روزرسانی شناسه برنامه برنامه به‌طور منحصربه‌فرد برنامه را در دستگاه آزمایشی شما شناسایی می‌کند و در صورتی که برنامه در کنسول Play آپلود شود، از خطای «نام بسته تکراری» جلوگیری می‌کند. برای به‌روزرسانی شناسه برنامه، app/build.gradle را باز کنید:

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

"MYUNIQUENAME" را در قسمت applicationId با چیزی منحصر به فرد برای خود جایگزین کنید.

افزونه تست را نصب کنید

افزونه Google Assistant به شما امکان می‌دهد تا App Actions خود را در یک دستگاه آزمایشی آزمایش کنید. با ارسال اطلاعات به دستیار از طریق برنامه Google در دستگاه Android شما کار می کند. اگر قبلاً افزونه را ندارید، با این مراحل آن را نصب کنید:

  1. به File > Settings ( Android Studio > Preferences در MacOS) بروید.
  2. در بخش Plugins، به Marketplace بروید و «دستیار Google» را جستجو کنید. همچنین می توانید ابزار تست را به صورت دستی دانلود و نصب کنید.
  3. ابزار را نصب کرده و اندروید استودیو را ریستارت کنید.

برنامه را روی دستگاه خود تست کنید

قبل از ایجاد تغییرات بیشتر در برنامه، به شما کمک می‌کند تا ایده‌ای در مورد کارهایی که برنامه نمونه می‌تواند انجام دهد به دست آورید.

برنامه را روی دستگاه آزمایشی خود اجرا کنید:

  1. در Android Studio، دستگاه فیزیکی یا مجازی خود را انتخاب کنید و Run > Run app را انتخاب کنید یا روی Run کلیک کنید نماد برنامه را در اندروید استودیو اجرا کنید. در نوار ابزار
  2. دکمه Home را طولانی فشار دهید تا Assistant راه‌اندازی شود و تأیید شود که کار می‌کند. اگر قبلاً این کار را نکرده‌اید، باید در دستگاه خود وارد «دستیار» شوید.

برای اطلاعات بیشتر در مورد دستگاه‌های مجازی Android، به ایجاد و مدیریت دستگاه‌های مجازی مراجعه کنید.

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

ویجت موجود را امتحان کنید

  1. روی دکمه Home ضربه بزنید تا به صفحه اصلی دستگاه آزمایشی خود بروید.
  2. یک فضای خالی در صفحه اصلی را طولانی فشار دهید و ابزارک ها را انتخاب کنید.
  3. به پایین لیست ویجت بروید تا به FitActions بروید.
  4. نماد FitActions را طولانی فشار دهید و ویجت آن را در صفحه اصلی قرار دهید.

تصویر صفحه نمایش ویجت FitActions در صفحه اصلی دستگاه.

4. App Action را اضافه کنید

در این مرحله، قابلیت GET_EXERCISE_OBSERVATION BII را اضافه می‌کنید. این کار را با افزودن یک عنصر capability جدید در shortcuts.xml انجام می دهید. این قابلیت مشخص می‌کند که چگونه قابلیت راه‌اندازی می‌شود، چگونه از پارامترهای BII استفاده می‌شود، و کدام قصد Android را برای انجام درخواست فراخوانی می‌کند.

  1. با این پیکربندی یک عنصر 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 منحصر به فرد خود جایگزین کنید.

این قابلیت، GET_EXERCISE_OBSERVATION BII را با هدف app-widget نگاشت می کند، به طوری که وقتی BII فعال می شود، ویجت نمونه سازی شده و به کاربر نمایش داده می شود.

قبل از راه‌اندازی ویجت، دستیار از پارامترهای BII از درخواست کاربر پشتیبانی می‌کند. این آزمایشگاه کد به پارامتر BII exerciseObservation.aboutExercise.name نیاز دارد که نشان دهنده نوع تمرین درخواستی کاربر است. این برنامه از سه نوع تمرین پشتیبانی می کند: "دویدن"، "پیاده روی" و "دوچرخه سواری". شما یک موجودی درون خطی برای اطلاع دستیار از این مقادیر پشتیبانی شده ارائه می کنید.

  1. با افزودن این پیکربندی، بالاتر از قابلیت 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>

یک قصد بازگشتی اضافه کنید

مقاصد بازگشتی موقعیت‌هایی را مدیریت می‌کنند که در آن درخواست کاربر نمی‌تواند برآورده شود، زیرا پرس و جو پارامترهای مورد نیاز قابلیت را ندارد. قابلیت GET_EXERCISE_OBSERVATION به پارامتر exerciseObservation.aboutExercise.name نیاز دارد که با ویژگی android:required="true" مشخص شده است. برای این موقعیت‌ها، Assistant از شما می‌خواهد که یک قصد بازگشتی تعریف کنید تا اجازه دهد درخواست موفق شود، حتی اگر هیچ پارامتری در پرس و جو ارائه نشده باشد.

  1. در 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>

در این پیکربندی نمونه، اجرای بازگشتی یک هدف اندروید است که هیچ پارامتری در داده‌های Extra آن وجود ندارد.

5. ویجت را برای Assistant فعال کنید

با ایجاد قابلیت GET_EXERCISE_OBSERVATION ، کلاس ویجت را برای پشتیبانی از فراخوان صوتی App Actions به روز کنید.

کتابخانه افزونه ابزارک را اضافه کنید

کتابخانه برنامه افزودنی ابزارک‌های برنامه، ویجت‌های شما را برای تجارب دستیار انتقال صدا بهبود می‌بخشد. به طور خاص، شما را قادر می سازد تا یک معرفی سفارشی TTS برای ویجت های خود ارائه دهید.

  1. وابستگی کتابخانه افزونه ابزارک را به منبع برنامه /app/build.gradle نمونه اضافه کنید:
    // app/build.gradle

dependencies {
  //...
  implementation "com.google.assistant.appactions:widgets:0.0.1"
}
    در کادر هشداری که در Android Studio ظاهر می شود، روی Sync Now کلیک کنید. همگام‌سازی پس از هر تغییر build.gradle به شما کمک می‌کند هنگام ساخت برنامه از خطا جلوگیری کنید.

سرویس ویجت را اضافه کنید

سرویس یک جزء برنامه کاربردی است که می تواند عملیات طولانی مدت را در پس زمینه انجام دهد. برنامه شما باید سرویسی برای پردازش درخواست‌های ویجت ارائه دهد.

  1. با این پیکربندی، سرویسی را به منبع 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 برای ارائه در دستیار استفاده می‌کند.

کلاس ویجت را به روز کنید

برنامه شما اکنون پیکربندی شده است تا درخواست‌های قابلیت GET_EXERCISE_OBSERVATION را به کلاس ویجت شما هدایت کند. در مرحله بعد، کلاس StatsWidget.kt را به‌روزرسانی کنید تا با استفاده از مقادیر پارامتر BII، یک نمونه ویجت ایجاد کنید که برای درخواست کاربر شخصی‌سازی شده است.

  1. کلاس StatsWidget.kt را باز کنید و کتابخانه App Actions Widget Extension را وارد کنید: 
    // StatsWidget.kt

// ... Other import statements
import com.google.assistant.appactions.widgets.AppActionsWidgetExtension
  2. این متغیرهای خصوصی را اضافه کنید که هنگام تعیین اطلاعاتی که باید ویجت را پر کند از آنها استفاده می کنید: 
    // StatsWidget.kt

private val hasBii: Boolean
private val isFallbackIntent: Boolean
private val aboutExerciseName: String
private val exerciseType: FitActivity.Type
  3. تابع 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 را به اهداف Android تولید شده توسط قابلیت GET_EXERCISE_OBSERVATION نشان دهیم:

  • optionsBundle = بسته
    • بسته‌ها اشیایی هستند که برای استفاده در سراسر مرزهای فرآیند، بین فعالیت‌های دارای هدف، و ذخیره حالت گذرا در میان تغییرات پیکربندی در نظر گرفته شده‌اند. دستیار از اشیاء Bundle برای ارسال داده‌های پیکربندی به ویجت استفاده می‌کند.
  • bii = actions.intent.GET_EXERCISE_OBSERVATION
    • نام BII از Bundle با استفاده از AppActionsWidgetExtension در دسترس است.
  • hasBii = true
    • بررسی می کند که آیا BII وجود دارد یا خیر.
  • params = Bundle[{aboutExerciseName=running}]
    • یک Bundle ویژه که توسط App Actions ایجاد شده است، در داخل گزینه های ویجت Bundle قرار دارد. این شامل جفت کلید/مقدار BII است. در این مورد، مقدار running از عبارت مثال «Hey Google, show my run stats on ExampleApp» استخراج شد.
  • isFallbackIntent = false
    • وجود پارامترهای BII مورد نیاز را در Intent Extras بررسی می کند.
  • aboutExerciseName = running
    • مقدار Intent Extras را برای aboutExerciseName دریافت می کند.
  • exerciseType = RUNNING
    • از aboutExerciseName برای جستجوی شی نوع پایگاه داده مربوطه استفاده می کند.

اکنون که کلاس StatsWidget می‌تواند داده‌های ورودی App Actions Android را پردازش کند، منطق جریان ایجاد ویجت را به‌روزرسانی کنید تا بررسی کنید که آیا ویجت توسط یک App Action راه‌اندازی شده است یا خیر.

  1. در 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 ایجاد می‌کند که توسط App Actions Android intent ارسال می‌شود.

  1. تابع 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 برای دستیار ارائه دهید تا هنگام نمایش ویجت خود اعلام کند. توصیه می کنیم این مورد را برای ارائه زمینه شنیداری با ویجت های خود قرار دهید. این قابلیت توسط App Actions Widgets Extension کتابخانه ارائه می‌شود، که به شما امکان می‌دهد متن و مقدمه‌های TTS را که ویجت‌هایتان را همراهی می‌کنند در Assistant تنظیم کنید.

یک مکان خوب برای ارائه مقدمه TTS در تابع formatDataAndSetWidget است که داده های فعالیت بازگردانده شده از پایگاه داده برنامه را قالب بندی می کند.

  1. در 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)
      }
}

کد قبلی به دو منبع رشته ای ارجاع می دهد: یکی برای گفتار و دیگری برای متن. برای توصیه‌های TTS، بخش توصیه سبک متن به گفتار را در ویدیوی ویجت‌های ما بررسی کنید. نمونه همچنین به setTts اشاره دارد، یک تابع جدید که اطلاعات TTS را به نمونه ویجت ارائه می کند.

  1. این تابع جدید 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 تکمیل کنید.

  1. تابع 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. App Action را تست کنید

در طول توسعه، از افزونه Google Assistant برای پیش نمایش Assistant App Actions در یک دستگاه آزمایشی استفاده کنید. می‌توانید با استفاده از این ابزار، پارامترهای هدف را برای یک App Action تنظیم کنید تا نحوه عملکرد عملکرد شما با روش‌های مختلفی که ممکن است کاربر از «دستیار» بخواهد آن را اجرا کند، بررسی کنید.

یک پیش نمایش ایجاد کنید

برای آزمایش App Action خود با افزونه:

  1. به Tools > Google Assistant > App Actions Test Tool بروید. ممکن است از شما خواسته شود با استفاده از حساب Google خود وارد Android Studio شوید.
  2. روی ایجاد پیش نمایش کلیک کنید. در صورت درخواست، خط‌مشی‌ها و شرایط خدمات App Actions را بررسی کرده و بپذیرید.

یک نوع تمرین مورد انتظار را تست کنید

با دنبال کردن این مراحل در ابزار تست، ویجتی را بازگردانید که اطلاعات مربوط به آخرین اجرای کامل در برنامه را نشان می‌دهد:

  1. در اولین مرحله که ابزار از شما می‌خواهد یک BII را انتخاب و پیکربندی کنید، actions.intent.GET_EXERCISE_OBSERVATION را انتخاب کنید.
  2. در کادر exerciseObservation ، نام پیش‌فرض تمرین را از climbing به run به‌روزرسانی کنید.
  3. روی Run App Action کلیک کنید.

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

یک نوع تمرین غیرمنتظره را آزمایش کنید

برای آزمایش یک نوع تمرین غیرمنتظره در ابزار تست:

  1. در کادر exerciseObservation ، مقدار name را از Run به Climbing به روز کنید.
  2. روی Run App Action کلیک کنید.

دستیار باید ویجتی را برگرداند که اطلاعات «فعالیتی یافت نشد» را نمایش دهد.

صفحه‌ای که ویجتی را نشان می‌دهد که بدون اطلاعات تمرینی با استفاده از افزونه Google Assistant بازگردانده شده است.

نیت بازگشتی را آزمایش کنید

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

برای آزمایش قصد بازگشتی:

  1. در کادر exerciseObservation ، شی aboutExercise را حذف کنید.
  2. روی Run App Action کلیک کنید.

دستیار باید ویجتی را برگرداند که اطلاعات آخرین تمرین انجام شده را نشان می دهد.

صفحه ای که ویجتی را نشان می دهد که آخرین فعالیت ثبت شده را با استفاده از افزونه Google Assistant نمایش می دهد.

7. مراحل بعدی

تبریک می گویم!

اکنون این قدرت را دارید که با استفاده از ابزارک Android با دستیار، سؤالات کاربران را برآورده کنید.

آنچه را پوشش داده ایم

در این کد لبه یاد گرفتید که چگونه:

  • یک ویجت برنامه را به BII اضافه کنید.
  • ویجت را برای دسترسی به پارامترهای Android Extras تغییر دهید.

بعدش چی

از اینجا، می‌توانید اصلاحات بیشتری را در برنامه تناسب اندام خود انجام دهید. برای ارجاع به پروژه تمام شده، به مخزن اصلی در GitHub مراجعه کنید.

در اینجا چند پیشنهاد برای یادگیری بیشتر در مورد گسترش این برنامه با App Actions وجود دارد:

  • برای کشف راه‌های بیشتر برای گسترش برنامه‌هایتان به «دستیار» ، به مرجع اهداف داخلی «کنش‌های برنامه» مراجعه کنید.

برای ادامه سفر Actions on Google، این منابع را کاوش کنید:

ما را در Twitter @ActionsOnGoogle دنبال کنید تا با آخرین اعلان‌های ما همراه باشید و برای #appactions توییت کنید تا آنچه ساخته‌اید به اشتراک بگذارید!

نظرسنجی بازخورد

در نهایت، لطفاً این نظرسنجی را پر کنید تا در مورد تجربه خود در مورد این کد لبه نظر بدهید.